Learn the workings of Git, not just the commands - JohnHau/mis GitHub Wiki

Don't just memorize commands -- understand how it all fits together Git is a commonly used decentralized source code repository. It was created by the Linux creator Linus Torvalds for the management of the Linux kernel source code. Whole services like GitHub are based around it. So, if you want to program in the Linux world or use IBM’s DevOps Services with Git, it helps to have a good understanding of Git.

When I started working with Git I had some experience with Concurrent Versions System (CVS) and Apache Subversion (SVN), so I tried to understand it in terms of those classic source code repository systems. That way of thinking only got me a limited understanding of Git’s capabilities. Since then I have grown to understand Git much better, so this article is a kind of “note to self” text to remind myself how Git works and explain it to those who are new to it. I assume you know your way around other more classical source code repositories like CVS or SVN.

Basics So let’s start with a basic example in a classical source code repository as in Figure 1. In a classical source code repository, folder with files and subfolders are handled as the content (CVS and Git don’t actually handle folders, just files at a path location). The repository holds all versions of the content, while the working directory is the place where you modify the code. You checkout code from the repository to the working directory and commit changes you’ve made in this working directory back into a new version of the content in the repository.

This series of versions is called a stream or branch. In SVN, the main stream is called trunk; in CVS it usually goes by the name HEAD; in Git it is usually named master. Branches are used in an implementation project to separate out the development of a specific feature or for the maintenance of an older version.

How Git works The main principle of Git, once you understand it, is astonishingly simple.

First, Git handles content in snapshots, one for each commit, and knows how to apply or roll back the change sets between two snapshots. This is an important concept. In my opinion, understanding the concept of applying and rolling back change sets makes Git much easier to understand and work with.

This is the real basic principle. Anything else follows from this. So let’s delve into Git a bit further.

Working with Git To start with, here’s a list of common commands you will use when working with Git:

git init — initializes a repository git checkout — checks out a branch from repository into the working directory git add — adds a change in a file to a change set git commit — commits a change set from the working directory into the repository To start working with Git, you just need to run the git init command. It turns the current directory into the Git working directory and creates the repository in the .git (hidden) directory it creates there. You can then start working with Git. The checkout and commit commands are similar to the other source code repositories, but the focus on change sets is the reason why in Git you have the add command (similar to SVN). With this command, a change in the working directory is added to the staging area for the next commit. This staging area is usually called the index. Figure 3 illustrates the process of creating a change set from snapshot version A to snapshot version B.

git status helps you keep track of which changes have been added, or not, on what branch you are on.

While git status lists the modified files in the workspace as well as the files in the index, you can look at the differences between files with the git diff command. Just using git diff (without parameters) only shows the changes in the working directory that have not yet been added to the index. You need to use git diff --cached to see what is actually in the index: the staged changes. git diff or git diff -- shows the difference between the current working directory and the named commit for the working directory or the given path respectively. The name can be a commit ID, a branch name, or another name. This is a good time to talk about naming.

Naming Note: Due to the length of the commit IDs, I will only use abbreviations like “(A)”, “(B)”, and so on in the diagrams.

Let’s look at the naming of things in Git. Snapshots are the main elements in Git. They are named with the commit ID, which is a hash ID like “c69e0cc32f3c1c8f2730cade36a8f75dc8e3d480” for example. It is derived from the content of the snapshot, which comprises of the actual content and some metadata like time of submission, author information, parents, etc. The snapshot does not have a dotted number version like in CVS, or a transaction number (and path under the /branches top directory) as in SVN. Because of this, you cannot determine any kind of order from the Git snapshot names as you can in other repositories. Git can, for convenience, abbreviate these long hashes to short names by taking the minimum number of characters from the start of the ID, so that the short name is still unique within the repository. In the above example, the short name is “c69e0cc”.

Note that the term commit, is used both as verb for creating a snapshot and as name for the resulting snapshot.

Normally you don’t have to work with the commit IDs; instead you work with branches. A named stream of changes, in other source code repositories, is called a branch. In Git, a stream of changes is an ordered list of change sets as they are applied one after another to go from one snapshot to the next. A branch in Git is only a named pointer to a specific snapshot. It notes the place where new changes should be applied to when this branch is used. When a change is applied to a branch, then also the branch label moves to the new commit.

How does Git know where to put the change from a workspace? That is where HEAD points. The HEAD of the development is where you last checked out your workspace and, more importantly, where to commit the changes. It usually points to the branch you last checked out. Note that this is different from CVS’ interpretation of the term HEAD as the tip of development of the default branch.

The tag command names a commit and allows you to address the individual commit with a readable name. Basically, a tag is an alias for a commit ID but commits can also be addressed with some shortcuts. HEAD as the tip of development in the working directory. HEAD^1 is the first parent of the HEAD commit, HEAD^2 the second and so on.

For more details, see the main page to gitrevisions. Because names like tags or branch names are references to commits, they are called refnames. A reflog shows what has been changed during the lifetime of the name, from when it was created (usually by a branch) until the current state.

Branching The concept behind branching is that each snapshot can have more than one child. Applying a second change set to the same snapshot creates a new, separate stream of development. And if it is named, it is called a branch.

Merging When you implemented your new feature, you checked it into the repository, for example, on your “feature” branch. When the feature is finished, you need to merge it back into the master branch. You do this by checking out the master branch, and use git merge . Git then merges the changes from the given branch into the checked out branch. What Git does to achieve this is it applies all of the change sets from the feature branch onto the tip of the master branch.

Depending on the type of changes in the two branches, and possible conflicts, there are three possibilities that can happen.

Fast forward merge: The receiving branch did not get any changes since the two branches diverged. The receiving branch still points to the last commit before the other branch diverged. In this case, Git moves the branch pointer of the receiving branch forward as shown in Figure 5. Because there is nothing to do besides moving the branch pointer forward, Git calls this a fast forward merge.

he revert command documents the revert as a new commit. If you don’t want that to be documented, you can reset the branch pointer to an earlier commit but this is out of scope for this article.

So why did I go over this section in such detail? It is because it is crucial to understand these features when discussing the collaborative features in the next section. In fact, once you understand this first section, the second section will be almost immediately clear. Most of the collaborative functionality is based on the base functionality discussed so far.

Collaboration In classical source code repositories there is always a clear notion what a branch is; it’s the one on the central repository.

In Git, however, there is no such thing as a master branch. Wait, didn’t I write above that there commonly is a master branch? Yes, I did. However. This master branch only exists locally. There is no relationship between the master branch in one repository and the one in another repository, except for the relationship you create.

When you check out a branch that only exists as a remote tracking branch (but not as a local branch), Git automatically creates the local branch from the remote tracking branch and checks this one out.

Once you have that, you can merge the contents of the remote branch into your own branch. Figure 11 shows the checkout into the local master branch, but that does not need to be the case, you could merge it into any other branch with a common history like the normal merge command.

Note that in such cases you could do a normal merge, but also have the option to do a rebase merge to rebase the changes in your local branch to the new, updated head of the remote branch.

Besides the fetch and push commands there is another way of distributing patches; the old style, via mail. For this there is the command git format-patch , which creates a patch file for each commit that leads from the given commit to the state of the current branch. git am applies these patch files to the current branch.

Caveats One caveat: If you try push into a repository where someone actually tracks the branch and locally works on it. This would probably mess up the branch management so Git warns you about it and tells you to first synchronize the state of the remote branch with a pull.

It also becomes clear that you should not rebase a remote tracking branch. It would not match the remote branch anymore, thus it would not give a fast-forward merge on push. You have broken your repository structure.

Advanced Git

Above I have described the rebasing as replaying of change sets on top of a different branching (or diversion) point from the original branch. Git normally does the replay in the order in which the commits have been made. As an advanced feature git rebase -i allows you to actually select which commits should be made in which order, and even if commits can be deleted or two commits can be combined (“squashed”). Just make sure you don’t do this to commits that have already been pushed – otherwise, those that have work based on these commits may get a lot of conflicts.

I have also written how to check out a specific branch but you can also check out any commit (snapshot). This lets the HEAD pointer point to the commit, and not the branch. This is called detached HEAD mode. When you commit a change in this situation, you start a new stream of development. Basically you branch out, but without having given a branch name to this new branch. The tip of development is only reachable by using a commit ID; it is not reachable by any refname. You can create a branch from this HEAD though using the usual “git branch ” command.

What happens to commits that are unreachable by any reference? Well, if you do not do anything special, they are kept in the repository. However, you can and hosting services might actually run git gc, the Git garbage collector to remove unnecessary files. Commits not reachable by any refname are unnecessary and will thus be removed. So it is good practice to always work on a real branch, especially when it is so fast and easy to create a new branch in Git.

Conclusion Git on one side is based on simple principles but the flexibility it provides can be overwhelming at times. The main takeaway is that Git manages snapshots and the change sets between snapshots. The most common commands apply and roll back those change sets between the different branches. The second takeaway is that handling a remote branch is basically the same as handling a local branch because there even is a local mirror of the remote branch.

With this I have finished my speed run through the workings of Git. These commands cover basically all of what I do with Git. More details to all the commands can be found in the respective man pages, and with the knowledge given here you are hopefully better able to understand them and use them. Also, the commands themselves and git status often give valuable hints on what to do next.

Another great tool to help you understand Git is the graphical gitk tool that shows the structure of the local repository. Use gitk --all to show all branches and tags, etc. It also provides a simple interface to initiate actions on Git.

Git is usually already installed on your Linux system. You may have to install development tools from your package manager. For Windows you can download it on the Git homepage.

I hope now you have a better understanding of the workings of Git and are not afraid to use its flexibility.

Thanks for some interesting discussions on this topic and for reviewing this article go to my colleague Witold Szczeponik who understands Git even better than I do.