Reading Understanding Git

A Stack Overflow user had this sentence about Git snapshots:

Snapshot is to a repository as screenshot is to a video.

It is a good metaphor: if you think of the entire life of your project, a snapshot is a record of its state at a moment in time. It is a version of the project.

This version is archived in a compressed form in a special .git directory inside your project.

By default git log gives a lot of information for each commit. While this is sometimes useful, if you want to get a clear picture of your overall project history, it may be better to reduce each commit log to a one-liner:

git log --oneline

You can customize the commit log to your liking by playing with colors, time format, etc.

Try for instance:

git log \
    --graph \
    --date-order \
    --date=short \
    --pretty=format:'%C(cyan)%h %C(blue)%ar %C(auto)%d'`
                   `'%C(yellow)%s%+b %C(magenta)%ae'

To see all the available flags, run man git-log.

The --graph flag allows to view this history in the form of a graph.

git log --graph

The --all flag shows all commits that are attached to the history, including those on other branches or "above" HEAD.

This may not make much sense yet, but it will this afternoon. It is an important flag to remember if you are ever wondering where some of your commits are when you run git log!

Let's imagine that you are starting to work on a project.

First, you create a directory.
In it, you create several sub-directories.
In those, you create a number of files.

You can open these files, read them, edit them, etc. This is something you are very familiar with.

In the Git world, this is the working directory or working tree of the project.
That is: an uncompressed version of your files that you can access and edit.
You can think of it as a sandbox because this is where you can experiment with the project. This is where the project gets developed.

Now, Git has two other important pieces in its architecture.

If you want the project history to be useful to future you, it has to be nice and tidy. You don't want to record snapshots haphazardly or you will never be able to find anything back.

Before you record a snapshot, you carefully select the elements of the project as it is now that would be useful to write to the project history together. The index or staging area is what allows to do that: it contains the suggested future snapshot.

Finally, the last tree in Git architecture is one snapshot in the project history that serves as a reference version of the project: if you want to see what you have been experimenting on in your "sandbox", you need to compare the state of the working directory with some snapshot.

Remember that HEAD is a pointer pointing at a branch, that a branch is itself a pointer pointing at a commit, and finally that a commit is a Git object pointing at a snapshot. When the HEAD pointer moves around, whatever snapshot it points to populates the HEAD tree.

As we saw earlier, when you create a commit, HEAD automatically points to the new commit. So the HEAD tree is often filled with the last snapshot you created. But—as we will see later—we can move the HEAD pointer around through other ways. So the HEAD tree can be populated by any snapshot in your project history.

To display the status of these trees, you run:

git status

When you edit files in your project, you make changes in the working directory or working tree.

The other two trees remain at version v1.

If you run git status, this is what you get:

On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   File

no changes added to commit (use "git add" and/or "git commit -a")

You stage that file (meaning that you will include the changes of that file in the next snapshot) with:

git add File

After which, your Git trees look like this:

Now, the index also has File at version v2 and git status returns:

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   File

Finally, you create a snapshot and the commit pointing to it—recording the staged changes to history—with:

git commit -m "Added File"

-m is a flag that allows to provide the commit message directly in the command line. If you don't use it, Git will open a text editor so that you can type the message. Without a message, there can be no commit.

Now your trees look like this:

We are back where we were at the start of this section, except that we have created an additional snapshot.

Our working tree is clean again and git status returns:

On branch main
nothing to commit, working tree clean

This means that there are no uncommitted changes in the working tree or the staging area: all the changes have been written to history.

Why do we first need to stage before we can commit? This allows you to pick and choose the changes that you want to include in a commit.

As a result, instead of having a messy bag of all your current changes whenever you write a commit, you can select changes that constitute a coherent unit and commit them together, leaving unrelated changes to be committed later.

This allows for a clearer history that will be much more useful in the future.

We don't work in perfectly linear and organized fashion: we tend to jump from one thing to another. To make it a lot easier when we will need to revisit our project history, it is better to create a history that is more organized that the real chronological history of our work events.

That's all your unstaged changes on tracked files (new files will not be shown)*.

You can get those differences with:

git diff

This will show you all the differences in the Python script between versions vy and vy+1.

*Git can detect new files you have never staged: it lists them in the output of git status. Until you put them under version control by staging them for the first time however, Git has no information about their content: at this point, they are untracked and they are not part of the working tree yet. So their content never appears in the output of git diff.

That's your staged changes ready to be committed. That is, that's what would be committed by git commit -m "Some message".

You get those differences with:

git diff --cached

This will show you all the differences in the markdown manuscript between versions vx and vx+1.

This is the combination of the previous two, that is, all your staged and unstaged changes (again, only on tracked files).

You can display those differences with:

git diff HEAD

This will show you the differences in the Python script between versions vy and vy+1 and in the markdown manuscript between versions vx and vx+1.