Blog & White

When I started to use git and read the man pages, I was sorely missing a brief description of how Git's features and concepts relate. Now that I finally understand (at least, I think) how Git works, I wrote this document. It's not a tutorial (the existing ones are good enough that I don't need to write another one), but rather a summary of how Git's main features relate to the jargon used in the man pages.

Saving your changes

Let's say you have a set of files in your working tree. Git works by saving a full copy (snapshot) of this set; this is called a commit. When you want to make a new commit using Git, you first need to tell Git which files are going to be part of this commit. You do this with the git add my_file command. The files are then added to the index, which is the list of files that are going to compose the commit. You then run git commit, which creates a new commit based on the files listed in the index. You are also prompted for a message that describes the commit. The message is structured with a heading (the first line of the message) separated by an empty line, from the body of the message. Lines starting with a hash symbol are comments and are not recorded into the message.

Adding a new file to the index and creating a commit containing this file has the side effect of letting Git track this file. If you want to create a commit composed of all the tracked files, you can run git commit -a, which implicitely adds all the tracked files to the index before creating a new commit.

A commit is identified by a SHA1 hash of its content, e.g, cdf18108b03386e1b755c1f3a3feaa30f9529390. Any non-ambiguous prefix of that hash can be used as a commit ID e.g., cdf1810.

The add/commit mechanism allows to split a set of changes into multiple commits (you create a commit for a subset of your files, then you create another commit for the rest of your files).

Creating a new repository

For a new project

The command git init creates a repository in the current directory (a .git directory that holds all the data necessary for Git to work). You can then add the files you need to have under version control (using git add, wildcards such as '*' are accepted) and create the initial commit with git commit.

Copying an existing repository

To copy an existing repository, use the git clone command. Most services that offer source code as Git repositories indicate the necessary Git command line to run.

Finding a commit

To view a summary of the changes that have happened in the repository, you can use git log; the top of the list is the most recent commit. To view the succession of changes (as diffs) that were made, use git log -p.

Git does its best not to lose anything you have recorded. The command git reflog shows a log of how the tip of branches have been updated, even if you have done acrobatic things.

Branches

When you make changes to your working tree and create a new commit, Git links the new commit to the commit that represents the state of the working directory before the changes (called in this context the parent of the new commit). The chain composed of the new commit, its parent, its parent's parent and so on, is called a branch. The name of the default branch is “master”. The most recent commit in a branch is called its HEAD.

A branch is nothing more than a name and the commit identifier of its tip; this is called a ref. For example refs/heads/master is the ref for the master branch. Finding the commits that compose the branch is a simple matter of following the tip's parent, and the parent's parent, and so on.

If you can decide to fork your work at some point, create a new branch by running git branch new_branch. This command creates the branch, but does not switch to that branch (changes and commits will still be appended to the current branch). To effectively change branch, you need to checkout the HEAD of the new branch by running git checkout new_branch. From this point on, changes and commits will be appended to the new branch.

Merging

If at some point it is necessary to merge the content of e.g., the new branch into the “master” branch, you need to checkout “master” and then run git merge new_branch.

If Git doesn't know how to merge two branches, it complains about conflicts and lets the user edit the incriminated files by hand. This is done by choosing, in sections of these files indicated with <<<<<< and >>>>>>> markers, which variant is to be retained. Once the editing has been made, the changes need to be committed (with git commit -a).

Checking out

You can checkout any commit with git checkout and thus have your working directory reflect the state of the repository at any point in time. When you do that, you are not on any branch anymore, which will cause various warning messages (such as “You are in 'detached HEAD' state”) and cause Git to behave in a way you may not expect (that is, if you don't understand properly yet how Git works). To go back to a “normal” situation, just run git branch master (or any other branch that exists). To prevent going into detached HEAD state, use git checkout -b new_branch to create a new branch that starts at <commit>.

If you have made local changes, Git won't let you checkout another branch. You must either commit them or reset the working tree before being allowed to do the checkout.

Reset

The command git reset allows to do multiple things. One of its most common use (git reset --hard) is to cancel all changes you have made to the working tree since the last commit.

If you specify a commit ID after git reset, it will move the HEAD of the current branch back to that commit, which becomes the new HEAD; all commits after this point are removed from the branch (but not from the repository! You can always restore the old HEAD by finding its commit ID with git reflog).

Working with remote repositories

Pull (and Fetch)

Some time after you have cloned a public repository, you may want to update your local copy so that it mathtches the latest version available at the original repository. This update is done with with git pull. When the repository was cloned, Git had created a remote (a link to the source repository) called by default “origin”. Below the hood, git pull calls git fetch to retrieve the commits from all the relevant branches on “origin”, and then calls git merge to merge those changes with the local current branch.

Note that refs/remotes/origin/master is the ref to the master branch at “origin”, but it is actually a branch stored locally that reflects the “master” branch on the “origin” repository. This kind of ref is used for specifying what remote branch is tracked by what local branch when using git fetch. Typically, +refs/heads/:refs/remotes/origin/ indicates that e.g., the local branch “master” tracks the remote branch “origin/master” (“*” represents a wildcard).

Push

If you have writing permissions on the remote repository, you can send your changes using git push (it defaults to the “origin” remote). Note that the HEAD of the branch to which you push changes must be the parent of your changes. If this is not the case, the push will fail and you will be asked to first pull from the remote repository to get the latest version, fix potential conflicts and only then push your changes.

It is also important to remember that you cannot normally push to a repository that has a working tree. The remote repository must have been created with the git init --bare command.