Git: Distributed Version Control for Code and Documents

Before we use Git to manage files, we need to create a repository for the sample project. The repository will be created locally, so it will only be on the file system of the machine you are working on.

It’s generally recommended that you practice using Git locally first, and only later dive into the decentralized features and functions of Git.

First, Git creates the directory example/ if it doesn’t already exist. Git then initializes an empty repository in this directory and creates a subdirectory .git/ for it, which is used to manage internal data. If the example/ directory already exists, Git creates a new Git repository in it. If both the directory and a repository already exist, Git does nothing. We change to the directory and look at the current state with git status:

Git tells us that we’re about to commit (Initial commit), but hasn’t found anything to commit (nothing to commit). Instead, it gives a hint as to what the next steps should be (most Git commands do that, by the way): “Create or copy files, and use git add to manage them with Git.”

Now let’s give Git a first file to manage, which is a “Hello World!” program in Perl. Of course, you can write any program in the programming language of your choice instead.

We’ll first create the hello.pl file with the following content

and execute the script once:

That means we’re ready to manage the file with Git. But let’s take a look at the output of git status first:

While the first commit is still pending, Git registers that there are already files in that directory, but the system is unaware of them — Git calls them untracked. This is, of course, our little Perl program. To manage it with Git, we use the command git add <file>:

The add generally stands for “add changes” — so you will need it whenever you have edited files, not just when you first add them!

Git doesn’t provide output for this command. Use git status to check if the call was successful:

Git will apply the changes — our new file — at the next commit. However, this commit is not yet complete — we’ve only prepared it so far.

To be precise, we’ve added the file to the Index, an intermediate stage where you collect changes that will be included in the next commit. For further explanation of this concept, see Sec. 2.1.1, “Index”.

With git status, under Changes to be committed, you can always see which files are in the Index, i.e., will be included in the next commit.

Everything is ready for the first commit with the git commit command. We also pass the -m option on the command line with a commit message describing the commit:

Git will confirm that the process has been successfully completed and the file will be managed from now on. The somewhat cryptic output means Git has created the initial commit (root-commit) with the appropriate message. A line has been added to a file, and the file has been created with Unix permissions 0644.⁠^[8]

As you’ve no doubt noticed by now, git status is an indispensable command in your daily work — we’ll use it again here:

Our sample repository is now “clean”, because there are no changes in the Working Tree or Index, nor are there any files that are not managed with Git (untracked files).

To conclude this brief introduction, we’ll introduce you to two very useful commands that you’ll often use to examine the version history of projects.

First, git show allows you to examine a single commit — it’s the most recent one, with no arguments:

You see all relevant information about the commit: the commit ID, the author, the date and time of the commit, the commit message, and a summary of the changes in Unified-Diff format.

By default, git show always prints the HEAD (a symbolic name for the most recent commit), but you could also specify, for example, the commit ID, which is the SHA-1 checksum of the commit, a unique prefix to it, or the branch (master in this case). Thus, the following commands are equivalent in this example:

If you want to view more than one commit, git log is recommended. More commits are needed to demonstrate the command in a meaningful way; otherwise, the output would be very similar to git show, since the sample repository currently contains only a single commit. So let’s add the following comment line to the “Hello World!” program:

For the sake of the exercise, let’s take another look at the current status with git status:

After that, as already described in the output of the command, use git add to add the changes to the index. As mentioned earlier, git add is used both to add new files and to add changes to files already managed.

Then create a commit:

Now git log shows you the two commits:

Git offers you the possibility to abbreviate single commands and even whole command sequences via Aliases. The syntax is:

To set st as an alias for status:

You can also include options in an alias, for example:

You will find more useful aliases later in the book; how to create more complex aliases is described in Sec. 8.3.8, “Extended Aliases”. But first, some useful abbreviations:

Very helpful is the color.ui option, which checks whether Git should color the output of various commands. Thus, deleted files and lines appear red, new files and lines appear green, commit IDs appear yellow, etc. In newer Git versions (1.8.4 and later) this setting is already set automatically, so you don’t need to do anything.

The color.ui option should be set to auto — if the output from Git is to a terminal, colors are used. If the command is written to a file instead, or the output is piped to another program, Git will not output color sequences, as this could interfere with automatic processing.

Unless set otherwise, Git assumes UTF-8 as the character encoding for all text, especially author names and the commit message. If you want a different encoding, you should configure it explicitly:⁠^[11]

Similarly, the setting i18n.logOutputEncoding determines the character set Git converts names and commit messages to before outputting them.

The encoding of the files managed by Git is not important here and is not affected by these settings — files are only bit streams that Git does not interpret.

Since Git runs on Windows systems like it does on unixoid systems, it has to solve the problem of different line-end conventions. (This only affects text files — binaries that Git recognizes as such are excluded from this treatment).

The core.eol setting, which can take one of the values lf, crlf or native, is mainly relevant for this. The default setting native lets Git use the system default — Unix: Line Feed (lf) only, Windows: Carriage Return & Line Feed (crlf). The file is automatically converted to get line feeds only, but is checked out with CRLF if necessary.

Git can convert between the two types when you check out the file, but it’s important not to mix the two. For this, the core.safecrlf option provides a mechanism to warn the user (value warn) or even disallow the commit (value true).

A safe setting, which also works with older Git versions on Windows systems, is to set core.autocrlf to input: This will automatically replace CRLF with LF when reading files from the filesystem. Your editor must then be able to handle LF line endings accordingly.

You can also specify these settings explicitly per file or subdirectory, so that the format is the same across all platforms (see Sec. 8.1, “Git Attributes — Treating Files Separately”).

Git automatically starts an editor, pager, or browser for certain actions. Usually reasonable defaults are used, but if not, you can configure your preferred program with the following options:

A word about the pager: By default, Git uses the less program, which is installed on most basic systems. The command is always started whenever a Git command produces output on a terminal. However, less is automatically configured by an environment variable to quit when the output is completely fit on the terminal. So, if a command produces a lot of output, less will automatically come to the foreground — and remain invisible otherwise.

If core.pager is set to cat, Git will not use a pager. However, this behavior can be achieved from command to command using the --no-pager parameter. In addition, you can use git config pager.diff false to ensure that the output of the diff command is never sent to the pager.

Some options can also be overridden by environment variables. In this way, options can be set in a shell script or alias for a single command only.

The latter variable is useful, for example, if you want to access the version history of another repository within a project without changing directory:

Alternatively, you can use the -c option before the subcommand to overwrite a setting for this call only. For example, you could tell Git to disable the core.trustctime option for the upcoming call:

The value of the help.autocorrect option determines what Git should do if it can’t find the subcommand you entered, for example if you accidentally type git statsu instead of git status.

If the option is set to a number n greater than zero and Git only finds a subcommand similar to the typed command, this command is executed after n tenths of a second. A value of -1 executes the command immediately. Unset or with the value 0, only the possibilities are listed.

So to correct a typo after one second, set:

You can of course cancel the command during this time with Ctrl+C.

The content of files for Git resides on three levels: the working tree, the index, and the Git repository. The working tree corresponds to the files as they reside on your workstation’s file system — so if you edit files with an editor, search in them with grep, etc., you always operate on the working tree.

The repository is the repository for commits, that is, changes, with author, date, and description. The commits together make up the version history.

Unlike many other version control systems, Git now introduces a new feature, the index. It’s a somewhat elusive intermediate level between the working tree and the repository. Its purpose is to prepare commits. This means that you don’t always have to check in all the changes you have made to a file as commits.

The Git commands add and reset act (in their basic form) on the index, making changes to the index and deleting them again; only the commit command transfers the file to the repository as it is held in the index (Figure 1, “Commands add, reset and commit”).

In the initial state, i.e. when git status outputs the message nothing to commit, the working tree and index are synchronized with HEAD. The index is therefore not “empty”, but contains the files in the same state as they are in the working tree.

Usually, the workflow is then as follows: First, you make a change to the working tree using an editor. This change is transferred to the index by add and finally saved in the repository by commit.

You can display the differences between these three levels using the diff command. A simple git diff shows the differences between the working tree and the index — the differences between the (actual) files on your working system and the files as they would be checked in if you called git commit.

The git diff --staged command, on the other hand, shows the differences between the index (also called the staging area) and the repository, that is, the differences that a commit would commit to the repository. In the initial state, when the working tree and index are in sync with HEAD, neither git diff nor git diff --staged produces output.

If you want to apply all changes to all files, there are two shortcuts: First, the -u or --update option of git add. This transfers all changes to the index, but does not yet create a commit. You can further abbreviate it with the -a or --all option of git commit. This is a combination of git add -u and git commit, which puts all changes to all files into one commit, bypassing the index. Avoid getting into the habit of using these options — they may be handy as shortcuts on occasion, but they reduce flexibility.

But why create commits step-by-step — don’t you always want to check in all changes?

Yes, of course, you usually want to commit your changes completely. However, it can be useful to check them in step by step, for example, to better reflect the development history.

An example: You have worked intensively on your software project for the past three hours, but because it was so exciting, you forgot to pack the four new features into handy commits. In addition, the features are scattered over various files.

At best, you want to be selective, that is, you don’t want to commit all changes from one file, but only certain lines (functions, definitions, tests, …​), and from different files.

Git’s index provides the flexibility you need for this. You collect some changes in the index and pack them into a commit — but all other changes are still preserved in the files.

We’ll illustrate this using the “Hello World!” example from the previous chapter. As a reminder, the contents of the hello.pl file

Now we prepare the file so that it has several independent changes that we don’t want to combine into a single commit. First, we add a shebang line at the beginning.⁠^[13] We also add a line naming the author, and the Perl statement use strict, which tells the Perl interpreter to be as strict as possible in its syntax analysis. It is important for our example that the file has been changed in several places:

With a simple git add hello.pl all new lines would be added to the index — so the state of the file in the index would be the same as in the working tree. Instead, we use the --patch option or short -p.⁠^[14] This has the effect that we are interactively asked which changes we want to add to the index. Git offers us each change one by one, and we can decide on a case-by-case basis how we want to handle them:

This is where Git shows all changes, since they’re very close together in the code. If the changes are far apart or spread across different files, they’re offered separately. The term hunk refers to loosely connected lines in the source code. Some of the options we have at this point include the following:

The options are each only one letter long and difficult to remember. A small reminder is always given by [?]. We have summarized the most important options below.

In the example we split the current hunk and enter s for split.

Git confirms that the hunk was successfully split, and now offers us a diff that contains only the shebang line.⁠^[16] We specify y for yes and q for quit on the next hunk. To check if everything worked, we use git diff with the --staged option, which shows the difference between index and HEAD (the latest commit):

To see which changes are not yet in the index, a simple call to git diff is enough to show us that — as expected — there are still two lines in the working tree:

At this point we could create a commit, but for demonstration purposes we want to start from scratch. So we use git reset HEAD to reset the index.

Git confirms and names the files that have changes in them; in this case, it’s just the one.

The git reset command is in a sense the counterpart of git add: Instead of transferring differences from the working tree to the index, reset transfers differences from the repository to the index. Committing changes to the working tree is potentially destructive, as your changes may be lost. Therefore, this is only possible with the --hard option, which we discuss in Sec. 3.2.3, “Reset and the Index”.

If you frequently use git add -p, it is only a matter of time before you accidentally select a hunk you didn’t want. If the index was empty, this is not a problem since you can reset it to start over. It only becomes a problem if you have already recorded many changes in the index and don’t want to lose them, i.e. you remove a particular hunk from the index without wanting to touch the other hunks.

Analogous to git add -p there is the command git reset -p, which removes single hunks from the index. To demonstrate this, let’s first apply all changes with git add hello.pl and then run git reset -p.

As in the example with git add -p, Git offers hunks one by one, but this time all the hunks in the index. Accordingly, the question is: Unstage this hunk [y,n,q,a,d,/,s,e,?]?, i.e. whether we want to remove the hunk from the index again. As before, by entering the question mark we get an extended description of the available options. At this point we press s once for split, n once for no and y once for yes. Now only the shebang line should be in the index:

A word of warning: A git add -p may tempt you to check in versions of a file that are not executable or syntactically correct (e.g. because you forgot an essential line). So don’t rely on your commit being correct just because make — which works on working tree files! -- runs successfully. Even if a later commit fixes the problem, it will still be a problem, among other things, with automated debugging via bisect (see Sec. 4.8, “Finding Regressions — Git Bisect”).

You now know how to exchange changes between working tree, index, and repository. Let’s turn to the git commit command, which you use to “commit” changes to the repository.

A commit keeps track of the state of all the files in your project at any given time, and also contains meta-information:⁠^[17]

In fact, the name of the author does not have to be the name of the committer (who commits). Often, commits are integrated or edited by maintainers (for example, by rebase, which also adjusts the committer information, see Sec. 4.1, “Moving commits — Rebase”). The committer information is usually of secondary importance, though — most programs only show the author and the date the commit was made.

When you create a commit, Git uses the user.name and user.email settings configured in the previous section to identify the commit.

If you call git commit without any additional arguments, Git will combine all changes in the index into one commit, and open an editor to create a commit message. However, the message will always contain instructions commented out with hash marks (#), or information about which files are changed by the commit. If you call git commit -v, you will still get a diff of the changes you will check in, below the instructions. This is especially useful for keeping track of the changes, and for using the auto-complete feature of your editor.

Once you exit the editor, Git creates the commit. If you don’t specify a commit message or delete the entire contents of the file, Git will abort and not create a commit.

If you only want to write one line, you can use the --message option, or short -m, which allows you to specify the message directly on the command line, thus bypassing the editor:

If you want to delete or move files managed by Git, use git rm or git mv. They act like the regular Unix commands, but they also modify the index so that the action is included in the next commit.⁠^[19]

Like the standard Unix commands, git rm also accepts the -r and -f options to recursively delete or force deletion. git mv also offers an option -f (force) if the new filename already exists and should be overwritten. Both commands accept the option -n or --dry-run, which simulates the process and does not modify files.

You will often forget to move a file via git mv or delete it via git rm, and use the standard Unix commands instead. In this case, simply mark the file (already deleted by rm) as deleted in the index, too, using git rm <file>.

To rename the file, proceed as follows: First mark the old file name as deleted using git rm <old-name>. Then add the new file: git add <new-name>. Then check via git status whether the file is marked as “renamed”.

If you want to search for an expression in all files of your project, you can usually use grep -R <expression> ..

However, Git offers its own grep command, which you can call up using git grep <expression>. This command usually searches for the expression in all files managed by Git. If you want to examine only some of the files instead, you can specify the pattern explicitly. With the following command you can find all occurrences of border-color in all CSS files:

The grep implementation of Git supports all common flags that are also present in GNU Grep. However, calling git grep is usually an order of magnitude faster, since Git has significant performance advantages due to the object database and the multithreaded design of the command.

Use git log to examine the project’s version history. The options of this command (most of which also work for git show) are very extensive, and we will introduce the most important ones below.

Without any arguments, git log will output the author, date, commit ID, and the full commit message for each commit. This is handy when you need a quick overview of who did what and when. However, the list is a bit cumbersome when you’re looking at a lot of commits.

If you only want to look at recently created commits, limit git log’s output to n commits with the -<n> option. For example, the last four commits are shown with:

To display a single commit, enter:

The <commit> argument is a legal name for a single commit, such as the commit ID or SHA-1 sum. However, if you do not specify anything, Git automatically uses HEAD. Apart from single commits, the command also understands so-called commit ranges (series of commits), see Sec. 2.1.7, “Commit-Ranges”.

The -p (--patch) option appends the full patch in Unified-Diff format below the description. Thus, a git show <commit> from the output is equivalent to git log -1 -p <commit>.

If you want to display the commits in compressed form, we recommend the --oneline option: It summarizes each commit with its abbreviated SHA-1 sum and the first line of the commit message. It is therefore important that you include as much useful information as possible in this line! For example, this would look like this:⁠^[20]

The --oneline option is only an alias for --pretty=oneline. There are other ways to customize the output of git log. The possible values for the --pretty option are:

Independently of this, you can display more information about the changes made by the commit below the commit message. Consider the following examples, which clearly show which files were changed in how many places:

So far, we’ve only looked at commands that require only a single commit as an argument, explicitly identified by its commit ID, or implicitly by the symbolic name HEAD, which references the most recent commit.

The git show command displays information about a commit, while the git log command starts at a commit, and then goes back in the version history until the beginning of the repository (called the root commit) is reached.

An important tool for specifying a series of commits is the so-called commit ranges in the form <commit1>..<commit2>. Since we have not yet worked with multiple branches, this is simply a range of commits in a repository, from <commit1> exclusive to <commit2> inclusive. If you omit one of the two boundaries, Git will take the value HEAD.

The command git show or git log -p has been used to show only the difference from the previous commit. If you want to see the differences between several commits, the command git diff.

The diff command performs several tasks. As already seen, you can examine the differences between the working tree and the index without specifying any commits, or the differences between index and HEAD with the --staged option.

However, if you pass two commits or a commit range to the command, the difference between these commits is displayed instead.

SHA-1 is a secure hash algorithm that calculates a checksum of digital information: the SHA-1 sum. The algorithm was introduced in 1995 by the American National Institute of Standards and Technology (NIST) and the National Security Agency (NSA). SHA-1 was developed for cryptographic purposes and is used for checking the integrity of messages and as a basis for digital signatures. Figure 3, “SHA-1 Algorithm” shows how it works, where we calculate the checksum of hello.py.

The algorithm is a mathematical one-way function that maps a bit sequence of maximum length 2⁶⁴-1 bits (about 2 exbibytes) to a checksum of length 160 bits (20 bytes). The checksum is usually represented as a hexadecimal character string of length 40. The algorithm results in 2¹⁶⁰ (approx. 1.5 · 10⁴⁹) different combinations for this length of checksum, and therefore it is very, very unlikely that two bit sequences have the same checksum. This property is called collision safety.

Despite all efforts of cryptologists, several years ago various theoretical attacks on SHA-1 became known, which are supposed to make the generation of collisions possible with a considerable computing effort.⁠^[22] For this reason, NIST today recommends the use of the successors of SHA-1: SHA-256, SHA-384 and SHA-512, which have longer checksums and thus make the generation of collisions more difficult. On the Git mailing list there was a debate about switching to one of these alternatives, but this step was not considered necessary.⁠^[23]

This is because, although there is a theoretical attack vector on the SHA-1 algorithm, this does not compromise the security of Git. In fact, the integrity of a repository is not primarily protected by the collision resistance of an algorithm, but by the fact that many developers have identical copies of the repository.

The SHA-1 algorithm plays a central role in Git because it is used to build checksums of the data stored in the Git repository, the Git objects. This makes them easy to reference as SHA-1 sums of their contents. In your daily work with Git, you will usually only use SHA-1 sums of commits, known as commit IDs. This reference can be passed to many Git commands, such as git show and git diff. Depending on the repository, you often only need to specify the first few characters of an SHA-1 sum, since in practice a prefix is sufficient to uniquely identify a commit.

All data stored in a Git repository is available as Git objects. There are four types:⁠^[24]

Figure 4, “Git Objects” shows three objects from the example project — a blob, a tree, and a commit.⁠^[25] The representation of each object includes the object type, the size in bytes, the SHA-1 sum, and the contents. The blob contains the content of the file hello.py (but not the file name). The tree contains references to one blob for each file in the project, i.e. one for hello.py and one for README, plus one tree per subdirectory, i.e. in this case only one for test. The files in the subdirectories are referenced separately in the respective trees that map these subdirectories.

So the commit object contains exactly one reference to a tree, and that reference is to the tree of the project content — this is a snapshot of the state of the project. The commit object also contains a reference to its direct ancestors, along with the metadata “author” and “committer” and the commit message.

Many Git commands expect a tree as an argument. However, because a commit, for example, references a tree, this is called a tree-ish argument. This refers to any object that can last be resolved to a tree. This category also includes tags (see Sec. 3.1.3, “Tags — Marking Important Versions”). Similarly, commit-ish is an argument that can be resolved to a commit.

File contents are always stored in blobs. Trees only contain references to blobs and other trees in the form of the SHA-1 sums of these objects. A commit in turn references a tree.

All Git objects are stored in the object database and are identifiable by their unique SHA-1 sum, i.e. you can find an object in the database by its SHA-1 sum once it has been stored. Thus, the object database basically functions like a large hash table, where the SHA-1 sums serve as keys for the stored contents:⁠^[26]

You will first see the four commits that make up the Git repository, including the e2c67eb commit shown in Figure 4, “Git Objects”. This is followed by trees and blobs, each with file or directory correspondence. So-called top-level trees have no directory name: They refer to the top level of a project. A commit always references a top-level tree, so there are four of them.

The hierarchical relationship of the objects listed above is shown in Figure 5, “Hierarchical Relationship of Git Objects”. On the left-hand side, you can see the four commits that are already in the repository, and on the right-hand side, the referenced contents of the most recent commit (C4). As described above, each commit contains a reference to its direct predecessor (the resulting graph of commits is discussed below). This relationship is illustrated by the arrows pointing from one commit to the next.

Each commit references the top-level tree — including the C4 commit in the example. The top-level tree in turn references the files hello.py and README in the form of blobs, and the subdirectory test in the form of another tree. Because of this hierarchical structure and the relationship of the individual objects to one another, Git is able to map the contents of a hierarchical file system as Git objects and store them in the object database.

In a short digression we will go into how to examine the object database of Git. To do this, Git provides so-called plumbing commands, a group of low-level tools for Git, as opposed to the porcelain commands you usually work with. These commands are therefore not important for Git beginners, but are simply intended to give you a different approach to the concept of the object database. For more information, see Sec. 8.3, “Writing Your Own Git Commands”.

Let’s first look at the current commit. We’ll use the git show command with the --format=raw option, so let’s output the commit in raw format, so that everything this commit contains is displayed.

As you can see, all the information in Figure 4, “Git Objects” is output: the SHA-1 sums of the commit, tree, and direct ancestor, plus the author and committer (including the date as a Unix timestamp), and the commit description. The command also provides the diff output for the previous commit — but this is not part of the commit, strictly speaking, and is therefore omitted here.

Next, let’s take a look at the tree referenced by this commit, using git ls-tree, a plumbing command to list the contents stored in a tree. It’s similar to ls -l, except that it is in the object database. With --abbrev=7 we shorten the output SHA-1 sums to seven characters.

As in Figure 4, “Git Objects” the tree referenced by the commit contains one blob for each of the two files, and one tree (also: subtree) for the test directory. We can look at its contents again with ls-tree, since we now know the SHA-1 sum of the tree. As expected, you can see that the test tree references exactly one blob, the blob for the file test.sh.

Finally, we make sure that the blob for hello.py really contains our “Hello World!” program and that the SHA-1 sum is correct. The command git show shows any objects. If we pass the SHA-1 sum of a blob, its contents are output. To check the SHA-1 sum we use the plumbing command git hash-object.

A note for curious readers: git hash-object hello.py does not produce the same output as the Unix command sha1sum hello.py. This is because not only the file content is stored in a blob. Instead, the object type, in this case blob, and the size, in this case 67 bytes, are stored in a header at the beginning of the blob. The hash-object command therefore does not calculate the checksum of the file content, but of the blob object.

The four commits that make up the sample repository are shown again in Figure 6, “Repository Content”, but in a different way: The dashed bordered tree and blob objects indicate unchanged objects, all others were added or changed in the corresponding commit. The reading direction here is from bottom to top: at the bottom is C1, which contains only the file hello.py.

Since trees only contain references to blobs and other trees, each commit stores the status of all files, but not their contents. Normally, only a few files change during a commit. New blob objects (and therefore new tree objects) are now created for the new files or those to which changes have been made. However, the references to the unchanged files remain the same.

Even more: A file that exists twice only exists once in the object database. The contents of this file are stored as a blob in the object database and are referenced by a tree in two places. This effect is known as deduplication: Duplicates are not only prevented, but not made possible in the first place. Deduplication is an essential feature of Content-Addressable File Systems, i.e. file systems that know files only by their contents (such as Git, for example, by giving an object the SHA-1 sum of itself as “name”).

Consequently, a repository in which the same 1 MB file exists 1000 times takes up only slightly more than 1 MB. Git essentially has to manage the blob, plus a commit and a tree with 1000 blob entries (20 bytes each plus the length of the filename). A checkout of this repository, on the other hand, consumes about 1 GB of space on the filesystem because Git resolves deduplication.⁠^[27]

The git checkout and git reset commands restore a previous state (see also Sec. 3.2, “Restoring Versions”): You specify the reference of the corresponding commit, and Git searches for it in the object database. The reference is then used to find the tree object of this commit from the object database. Finally, Git uses the references contained in the tree object to find all other tree and blob objects in the object database and replicates them as directories and files on the file system. This allows you to restore exactly the project state that was saved with the commit at the time.

Because each commit stores its direct ancestors, a graph structure is created. More precisely, the arrangement of the commits creates a Directed Acyclic Graph (DAG). A graph consists of two core elements: the nodes and the edges connecting these nodes. In a directed graph, the edges are also characterized by a direction, which means that when you run the graph, you can only use the edges that point in the appropriate direction to move from one node to the next. The acyclic property rules out that you can find your way back to a node by any route through the graph. So you cannot move in a circle.⁠^[28]

The graph structure is derived from the object model, because each commit knows its direct ancestor (possibly several in the case of a merge commit). The commits form the nodes of this graph — the references to ancestors form the edges.

An example graph is shown in Figure 7, “A Commit Graph”. It consists of several commits, which are colored to make it easier to distinguish between their affiliations to different development branches. First, the commits A, B, C, and D were made. They form the main development branch. Commits E and F contain feature development, which was transferred to the main development branch with commit H. Commit G is a single commit that has not yet been integrated into the main development branch.

One result of the graph structure is the cryptographically secured integrity of a repository. Git uses the SHA-1 sum of a commit to reference not only the contents of the project files at a given point in time, but also all commits executed up to that point, and their relationship to each other, i.e. the complete version history.

The object model makes this possible: each commit stores a reference to its ancestors. These references are then used to calculate the SHA-1 sum of the commit itself. So you get a different commit if you reference another ancestor.

Since the predecessor in turn references predecessors, and its SHA-1 sum depends on the predecessors, and so on, this means that the complete version history is implicitly encoded in the commit ID. Implicit here means: If even one bit of a commit changes anywhere in the version history, then the SHA-1 sum of subsequent commits, especially the topmost one, is no longer the same. The SHA-1 sum doesn’t say anything detailed about the version history, though; it’s just a checksum of it.

Eine Referenz, die Sie selten explizit, aber ständig implizit benutzen, ist HEAD. Sie referenziert meist den gerade ausgecheckten Branch, hier master:

One reference that you rarely use explicitly, but always implicitly, is HEAD. It usually refers to the branch you just checked out, in this case master:

HEAD can also point directly to a commit if you type git checkout <commit-id>. However, you are then in so-called detached-head mode, in which commits may get lost, see also Sec. 3.2.1, “Detached HEAD”.

The HEAD determines which files are found in the working tree, which commit becomes the predecessor when a new one is created, which commit is displayed by git show, and so on. When we speak of “the current branch”, we mean the HEAD in a technically correct sense.

The simple commands log, show, and diff take HEAD as their first argument, without any further arguments. The output of git log is the same as the output of git log HEAD, and so on — this applies to most commands that operate on a commit if you don’t specify one explicitly. HEAD is thus similar to the shell variable PWD, which specifies “where you are”.

When we talk about a commit, a command usually doesn’t care whether you specify the commit ID in full or in abbreviated form, or whether you access the commit by reference, such as a tag or branch. However, such a reference may not always be unique. What happens if there is a branch master and a tag with the same name? Git checks if the following references exist:

Git will take the first matching reference it finds. So you should always give tags a unique scheme so that they don’t get confused with branches. This way you can address branches directly by name instead of heads/<name>.

Especially important are the suffixes ^ and ~<n>. The syntax <ref>^ indicates the direct ancestor of <ref>. This does not always have to be unique: If two or more branches were merged, the merge commit has several direct ancestors. <ref>^ or <ref>^1 then denotes the first direct ancestor, <ref>^2 the second, and so on.⁠^[30] So the syntax HEAD^^ means “the two-level previous direct ancestor of the current commit”. Note that ^ may have a special meaning in your shell and you may need to protect it with quotes or a backslash.

The syntax <ref>~<n> is equivalent to repeating ^ n times: HEAD~10 thus denotes the tenth direct predecessor of the current commit. Note: This does not mean that only eleven commits are stored between HEAD and HEAD~10: Since ^ only follows the first string in any merge, the eleven commits stored between the two references, and all the other commits integrated by a merge, are the same. The syntax is documented in the git-rev-parse(1) man page in the “Specifying Revisions” section.

A branch is created in Git in no time. All Git needs to do is identify the currently checked out commit and store the SHA-1 sum in the .git/refs/heads/<branch-name> file.

The command is so fast because (unlike other systems) no files need to be copied and no additional metadata needs to be stored. Information about the structure of the version history can always be derived from the commit that a branch references and its ancestors.

Here is an overview of the most important options:

SHA-1 sums are a very elegant solution to describe versions decentrally, but they are semantically poor and unwieldy for humans. Unlike linear revision numbers, commit IDs alone tell us nothing about the order of versions.

During the development of software projects, different “important” versions need to be marked so that they can be easily found in the repository. The most important ones are usually those that are released, called releases. Release candidates are also often marked in this way, i.e. versions that form the basis for the next version and are checked for critical bugs in the course of quality assurance without adding new features. Depending on the project and development model, there are different conventions for marking releases and procedures for preparing and publishing them.

In the open source area, two versioning schemes have become established: the classic major/minor/micro versioning scheme and, more recently, date-based versioning. With major/minor/micro versioning, which is used e.g. with the Linux kernel and also Git, a version is identified by three (often four) numbers: 2.6.39 or 1.7.1. With date-based versioning, on the other hand, the designation is derived from the time of the release, e.g.: 2011.05 or 2011-05-19. This has the great advantage that the age of a version is easily identifiable.⁠^[33]

Git offers tags (“labels”) that can be used to mark any Git object — usually commits — to highlight prominent states in its development history. Like branches, tags are implemented as references to objects. Unlike branches, however, tags are static, meaning that they are not moved when new commits are added, and always point to the same object. There are two types of tags: annotated and lightweight. Annotated tags are tagged with metadata, such as author, description, or GPG signature. Lightweight tags, on the other hand, “simply” point to a specific Git object. For both types of tags, Git creates references under .git/refs/tags/ or .git/packed-refs. The difference is that for each annotated tag, Git creates a special Git object — a tag object — in the Object Database to store the metadata and SHA-1 sum of the selected object, while a Lightweight tag points directly to the selected object. Figure 12, “The Tag Object” shows the contents of a tag object; compare also the other git objects, Figure 4, “Git Objects”.

The tag object shown has both a size (158 bytes) and a SHA-1 sum. It contains the name (0.1), the object type and the SHA-1 sum of the referenced object as well as the name and e-mail of the author, which is called tagger in Git jargon. In addition, the tag contains a tag message that describes the version, for example, and optionally a GPG signature. In the Git project, for example, a tag message consists of the current version designation and the signature of the maintainer.

In the following, let’s first look at how you manage tags locally. Sec. 5.8, “Exchanging Tags” describes how you exchange tags between repositories.

If you check out a commit that is not referenced by a branch, you are in detached-HEAD mode:

As the explanation, which you can hide by setting the option advice.detachedHead to false, already warns you, changes you make now will be lost in case of doubt: Since your HEAD is the only direct reference to the commit after that, further commits are not directly referenced by a branch (they are unreachable, see above).

So working in detached HEAD mode is especially useful if you want to try something quickly: Has the bug actually already appeared in commit 3329661? Was there actually a README file at the time of 3329661?

If you want to undo all the changes a commit makes, the revert command helps. However, it does not delete a commit, but creates a new one whose changes are exactly the opposite of the other commit: Deleted lines become added lines, and vice versa.

Suppose you have a commit that creates a LICENSE file. The patch of the corresponding commit looks like this:

Now you can undo the changes:

Git creates a new commit on the current branch — unless you specify otherwise — with the description Revert "<Old commit message>". This commit looks like this:

Note that from now on, both the commit and the revert will appear in the version history of a project. You therefore only undo the changes, but do not delete any information from the version history.

You should therefore only use revert if you need to undo a change that has already been published. However, if you are developing locally in a separate branch, it makes more sense to delete these commits completely (see the following section on reset and the topic Rebase, Sec. 4.1, “Moving commits — Rebase”).

If you want to perform a rebase, but not for all changes to the commit, but only for those to a file, you can use this procedure:

The git show command prints the changes from commit 3329661 that apply to the LICENSE file. The -R option causes the unified-diff format to be displayed “the other way around” (reverse). The output is passed to git apply to make the changes to the file and index. The changes are then checked in.

Another way to undo a change is to check out a file from a previous commit, add it to the index, and check it in again:

If you are deleting a commit completely, not just undoing it, use git reset. The reset command sets the HEAD (and thus the current branch), and optionally the index and working tree, to a particular commit. The syntax is git reset [<option>] [<commit>].

The most important types of resets are the following:

If you call git reset without any options, this is equivalent to a git reset --mixed HEAD. We’ve already seen this command: Git sets the current HEAD to HEAD (so it doesn’t change it) and the index to HEAD — in this case, the changes you added before are lost.

The possible uses of this command are many and varied and will reappear in the various command sequences. Therefore it is important to understand the functionality, even if there are sometimes alternative commands that have the same effect.

Suppose you have made two commits to master that you actually want to move to a new branch to work on further. The following command sequence creates a new branch pointing to HEAD, and then resets HEAD and the current branch master two commits. Then check out the new branch <new-feature>.

Alternatively, the following sequence has the same effect: you create a Branch <new-feature> that points to the current commit. Then you delete master and re-create it so that it points to the second predecessor of the current commit.

The two branches, topic and master, that you want to merge, each reference the most recent commit in a chain of commits (F and D), and these two commits in turn reference a tree (corresponding to the top-level directory of your project).

First, Git calculates a so-called merge base, that is, a commit that both of the commits to be merged have as common ancestors. Usually there are several such bases — in the diagram below, A and B — and then the most recent one (which has the other bases as ancestors) is used.⁠^[37] In simple terms, this is the commit where the branches diverged (i.e., B).

Now, if you want to merge two commits (D and F to M), then the trees referenced by the commits must be merged.

Git does this as follows:⁠^[38] If a tree entry (another tree or a blob) is the same in both commits, then that very tree entry will be taken over in the merge commit. This happens in two cases:

If a tree entry disappears in one of the commits, but is still present in the other, and is the same as in the merge base, then it is not taken over. This is equivalent to deleting a file or directory if no changes have been made to the file on the other side. Similarly, if a commit brings a new tree entry, it is copied to the merge tree.

Now what happens if a file from the commits has different blobs, that is, the file has been changed at least on one side? In the event that one of the blobs is the same as in the merge base, only one side of the file has been changed, so Git can simply adopt those changes.

However, if both blobs are different from the merge base, you might run into problems. First, Git tries to apply the changes on both sides.

A 3-way merge algorithm is usually employed for this purpose. Unlike the classic 2-way merge algorithm, which is used when you have two different versions A and B of a file and want to merge them, this 3-way algorithm involves a third version C of the file, extracted from the above merge base. Therefore, because a common ancestor of the file is known, the algorithm can in many cases better (that is, not only based on the line number or context) decide how to merge changes. In practice, so many trivial merge conflicts are already solved automatically without user intervention.

However, there are conflicts that no merge algorithm, no matter how good, can merge. This happens, for example, if the context in version A of the file was changed just before a change in file B, or, worse still, version A and B and C have different versions of a line.

Such a case is called a merge conflict. Git merges all the files as best it can, and then presents the conflicting changes to the user so they can manually merge them (and thus resolve the conflict) (see Sec. 3.4, “Resolving Merge Conflicts”).

Although it is basically possible to generate a syntactically correct resolution with an algorithm that is specially designed for the respective programming language, an algorithm cannot look beyond the semantics of the code, i.e., cannot grasp the meaning of the code. Therefore, a solution generated in this way would usually not make sense.

The git merge command does not always create a merge commit. A trivial case, but one that does occur frequently, is the so-called fast-forward merge, i.e. a fast forward merge of the branch.

A fast forward merge occurs when a branch, for example topic, is the child of a second branch, master:

A simple git merge topic in Branch master now causes master to simply be moved forward — no merge commit is created.

Of course, such a behavior only works if the two branches have not diverged, i.e. if the merge base of both branches is one of the two branches itself, in this case master.

This behavior is often desirable:

There are different opinions on whether changes should always be integrated via fast-forward or whether it is better to create a merge commit, although this is not absolutely necessary. The results are the same in both cases: Changes from one branch are integrated into another.

However, when you create a Merge-Commit, the integration of a feature becomes clear. Consider the following two excerpts from the version history of a project:

In the above case, you cannot easily see which commits were previously developed in branch sha1-caching, that is, they have to do with a specific feature of the software.

In the lower version, however, you can see at first glance that there were exactly four commits on that branch, and that it was then integrated. Since nothing was developed in parallel, the merge commit would in principle be unnecessary, but it does make the integration of the feature clear.

An explicit merge commit is also helpful because you can undo it with a single command. This is useful, for example, if you have integrated a branch but it has bugs: If the code is running in production, it is often desirable to merge the entire change back in until the bug is fixed. Use for this:

Git then produces a new commit that reverses any changes made by the merge. The -m 1 option here specifies which “side” of the merge should be considered the mainline, or stable line of development: its changes are preserved. In the above example, -m 1 would cause the changes made by the four commits from branch sha1-caching, the second string of the merge, to be undone.

Git has five different merge strategies, some of which can be further adjusted by strategy options. You determine the strategy by -s, so a merge call is as follows:

Some of these strategies can only merge two branches, others any number.

The default strategy recursive knows several options that adjust the behavior especially with regard to conflict resolution. You specify them with the option -X; the syntax is:

If you only merge two branches, you do not need to explicitly specify the recursive strategy by -s recursive.

Since the strategy can only merge two branches, it is possible to speak of our version and theirs: our version is the checked-out branch in the merge process, while their version references the branch you want to integrate.

In the case of non-trivial merge conflicts, a merge tool is recommended that visualizes the three stages of a file accordingly, thereby facilitating the resolution of the conflict.

Common IDEs and editors such as Vim and Emacs offer such a mode. There are also external tools such as KDiff3⁠^[41] and Meld.⁠^[42] The latter visualizes particularly well how a file has changed between commits.

You launch such a merge tool via git mergetool. Git will go through all the files that contain conflicts and display each one (when you press enter) in a merge tool. By default this is Vimdiff.⁠^[43]

Such a program will usually display the three versions of a file — our page, their page, and the file merged as far as possible, including conflict markers — in three columns side by side, the latter sensibly in the middle. It is always essential that you make the change (conflict resolution) in the middle file, i.e. in the working copy. The other files are temporary and are deleted again when the merge tool is finished.

In principle, you can use any other tool. The mergetool script simply stores the three stages of the file with the corresponding file name and starts the diff tool on these three files. If it quits again, Git checks to see if there are any conflict markers left in the file — if not, Git will assume that the conflict was resolved successfully and automatically add the file to the index using git add. Finally, when you have finished processing all the files, you only need to make one commit call to seal the conflict resolution.

The merge.tool option determines which tool Git starts on the file. The following commands are already preconfigured, meaning that Git already knows in which order the program expects the arguments and which additional options need to be specified:

To use your own merge tool, you must set merge.tool to a suitable name, for example mymerge, and then at least specify the mergetool.mymerge.cmd option. The shell evaluates the expression stored in it, and the variables BASE, LOCAL, REMOTE, and MERGED, which are contained in the file with the conflict markers, are set to the corresponding temporary files. You can further configure the properties of your merge command, see the git-config(1) man page in the mergetool configuration section.

Git has a relatively unknown (and poorly documented), but very helpful feature: Rerere, short for Reuse Recorded Resolution. You need to set the rerere.enabled option to true to have the command called automatically (note the d at the end of enabled).

The idea behind Rerere is simple but effective: Whenever a merge conflict occurs, Rerere automatically records a pre-image, an image of the conflict file including markers. In the case of the example above, it would look like this:

If the conflict is resolved as above and the solution is checked in, Rerere saves the conflict resolution:

So far Rerere has not really helped. But now we can delete the merge commit completely (and are back to the situation before the merge). Then we execute the merge again:

Rerere notices that the conflict is known and that a solution has already been found.⁠^[44] So Rerere calculates a 3-way-merge between the saved pre-image, the saved solution and the version of the file in the working tree. This way Rerere can resolve not only the same conflicts, but also similar ones (if in the meantime further lines outside the conflict area have been changed).

The result is not directly added to the index. The solution is simply copied to the file. You can then use git diff to check whether the solution looks useful, run tests if necessary, etc. If everything looks good, you can use the automatic solution via git add as usual.

Decentralized version control systems generally manage merges much better than central ones. This is mainly due to the fact that it is common practice in decentralized systems to check in many small changes locally first. This avoids “monster commits”, which offer much more potential for conflict. This finer granular development history and the fact that merges are usually data in the version history (as opposed to simply copying the lines of code) mean that decentralized systems do not have to look at the mere contents of files when merging.

Prevention is the best way to minimize merge conflicts. Make small commits! Combine your changes so that the resulting commit makes sense as a unit. Always build Topic Branches on the latest release. Merge from topic branches into “collection branches” or directly into master, not the other way around.⁠^[45] Using Rerere prevents conflicts that have already been resolved from constantly reoccurring.

Obviously, good communication among developers is also important for prevention: If several developers implement different and mutually influencing changes to the same function, this will certainly lead to conflicts sooner or later.

Another factor that unfortunately often leads to unnecessary(!) conflicts is autogenerated content. Suppose you write the documentation of a software in AsciiDoc⁠^[46] or work on a LaTeX project with several contributors: Never add the compiled man pages or the compiled DVI/PS/PDF to the repository! In the autogenerated formats, small changes to the plaintext (i.e. in the Ascii or LaTeX version) can cause large (and unpredictable) changes to the compiled formats that Git will not resolve adequately. Instead, it makes sense to provide appropriate Makefile targets or scripts to generate the files, and possibly keep the compiled version on a separate branch.⁠^[47]

Since the listing of multiple commits is hard to keep track of, we examine a small sample repository with several branches merged together:

We recognize four branches (A-D) and one tag release. We can also display this tree on the console with the appropriate command line options using the log command (branch and tag names are printed in semi-bold for better distinction):

Now we change the above command: instead of the --all option, which puts all commits in the tree, we now specify B (the name of the branch)

We receive all commits that are accessible from B. A commit only knows its predecessor(s) (several if branches are merged). “All commits reachable from B” thus refers to the list of commits from B onwards, up to a commit that has no predecessor (called a root commit).

Instead of one, the command can also accept multiple references. So to get the same output as with the --all option, you must specify references A, B, and D. C can be omitted because the commit is already “collected” on the way from A to the root commit.

Of course, you can also specify an SHA-1 sum directly instead of symbolic references:

If a reference is preceded by a caret (^), this negates the meaning.⁠^[50] So the notation ^A means: not the commits that are accessible from A. However, this switch only excludes these commits, but not the others. So the above log command with the argument ^A will not output anything, because Git only knows which commits should not be displayed. So again, we add --all to list all commits, minus those that are accessible from A:

An alternative notation is available with --not: Instead of ^A you can also write --not A.

Such commands are especially useful for examining the difference between two branches: Which commits are in branch D that are not in A? The command returns the answer:

Because this question is often asked, there is another, more intuitive notation for it: A..D is equivalent to D ^A:

Of course the order is important here: “D without A” is a different set of commits than “A without D”! (Compare also the complete graph.)

In our example there is a tag release. To check which commits from branch D (which could stand for “Development”) are not yet included in the current release, simply specify release..D.

Gitk is a graphical program implemented in Tcl, which is usually packaged by distributors along with the actual Git commands — so you can be sure to find it on almost any system.

It represents individual commits or the entire repository in a three-part view: at the top is the tree structure with two additional columns for author and date, below is a list of changes in unified diff format, and a list of files to restrict the changes displayed.

The graph view is intuitive: Different colors help to distinguish the different version strings. Commits are always blue dots, with two exceptions: The HEAD is highlighted in yellow, and a commit that is not a root commit, but whose predecessor is not displayed, is shown in white.

Branches with an arrowhead indicate that further commits have been made on the branch. However, Gitk hides the branch due to the time distance between commits. A click on the arrowhead will take you to the continuation of the branch.

Branches appear as green labels, the currently checked out branch additionally bold. Tags are shown as yellow arrows.

You can delete or check out a branch with a right click on it. Right-clicking on commits opens a menu in which you can perform actions on the selected commit. The only thing that might be easier to do with Gitk than from the command line is cherry picking, i.e. transferring individual commits to another branch (see also Sec. 3.5, “Taking over Individual Commits: Cherry Picking”).

Gitk accepts essentially the same options as git log. Some examples:

The first command shows all commits since yesterday that have made changes to a file under the doc/ directory. The second command limits the commits to a specific range, while the third command shows the 100 most recent commits from all branches.

Many users leave gitk open during work. Then it’s important to update the display from time to time so that more recent commits appear. With F5 (Update) you load all new commits and refresh the display of the references. Sometimes, however, if you delete a branch, for example, this is not enough. Although the branch is no longer displayed, there may still be unreachable commits in the GUI as artifacts. The key combination Ctrl+F5 (Reload) completely reloads the repository, which solves the problem.

As an alternative to gitk, you can use the GTK-based gitg or Qt-based qgit on UNIX systems; on an OS X system, for example, you can use GitX; for Windows, you can use GitExtensions. Some IDEs now also have corresponding visualizations (e.g. the Eclipse plugin EGit). Furthermore, you can use full-fledged Git clients like Atlassian SourceTree (OS X, Windows; free of charge), Tower (OS X; commercial) as well as SmartGit (Linux, OS X and Windows; free for non-commercial use).

Consider the following situation: The sqlite-support branch branches off from the “fixed a bug…​” commit. But the master branch has already moved on, and a new 1.4.2 release has been made.

Now sqlite-support is checked out and rebuilt to master:

Rebase applies the three changes introduced by commits from the sqlite-support branch to the master branch. After that, the repository looks like this in Gitk:

Normally git rebase will always build the branch you are currently working on on a new one. However, there is a shortcut: If you want to base topic on master, but you are on a completely different branch, you can do this via

Git does the following internally:

Please note the (unfortunately not very intuitive) order:

A rebase can lead to conflicts. The process then stops with the following error message:

You proceed as with a regular merge conflict (see Sec. 3.4, “Resolving Merge Conflicts”) - git mergetool is very helpful here. Then simply add the changed file via git add and let the process continue via git rebase --continue.⁠^[54]

Alternatively, the problematic commit can be skipped using the git rebase --skip command. The commit is then lost unless it is referenced in another branch somewhere else! So you should only perform this action if you are certain that the commit is obsolete.

If none of this helps (e.g. if you can’t solve the conflict at that point, or if you realize that you are rebuilding the wrong tree), pull the emergency brake: git rebase --abort. This will discard all changes to the repository (including successfully copied commits), so that the state afterwards is exactly the same as it was when the rebase process was started. The command also helps if at some point you forget to finish a rebase process, and other commands complain that they can’t do their job because a rebase is in progress.

Rebase is primarily useful for keeping the commit history of a project simple and easy to understand. For example, a developer might be working on a feature, but then have something else to do for a few weeks. Meanwhile, however, development on the project has progressed, there’s been a new release, etc. Only now does the developer get to finish a feature. (Even if you want to send patches via email, rebase helps to avoid conflicts, see Sec. 5.9, “Patches via E-mail”.)

For the version history it is now much more logical if his feature was not “dragged along” unfinished for a long period of time alongside the actual development, but if the development branches off from the last stable release.

Rebase is good for exactly this change in history: The developer can now simply enter the command git rebase v1.4.2 on the branch where he developed the feature, to rebuild his feature branch on the commit with the release tag v1.4.2. This makes it much easier to see what differences the feature really brings to the software.

It also happens to every developer in the heat of the moment that commits end up in the wrong branch. There is a bug that happens to be there, which is quickly fixed by a commit; but then a test must be written directly to avoid this bug in the future (another commit), and this must be noted in the documentation. After the actual work is done, you can use Rebase to “transplant” those commits to another location in the commit graph.

Rebase can also be useful if a branch requires a feature that has only recently been incorporated into the software. A merge of the master branch does not make sense semantically, because then these and other changes are inseparably merged with the feature branch. Instead, you rebase the branch on a new commit that already contains the required feature, and then use that in further development.

The concept of rebase is initially a little difficult to understand. But once you have understood what is possible with it, the question arises: What is the point of a simple merge if you can edit everything with rebase?

When git-rebase is not used, or hardly used at all, a project history often develops that becomes relatively unmanageable, because merges have to be performed constantly and for a few commits at a time.

If, on the other hand, too much rebase is used, there is a danger that the entire project will be senselessly linearized: The flexible branching of Git is used for development, but the branches are then integrated into the publishing branch one after the other (!) like a zip fastener via rebase. This presents us with two main problems:

This is how you can make the most of Git’s flexible branching. The conclusion is that rebase should be used neither too much nor too little. Both make the project history (in different ways) confusing.

In general, you are doing well with the following rules of thumb:

As mentioned earlier, a rebase inevitably changes the SHA-1 sums of all commits that are “rebuilt”. If these changes have not yet been published, that is, if a developer has them in a private repository, that’s not too bad either.

But if a branch (e.g.  `master`) is published⁠^[55] and later rewritten via rebase, this has unpleasant consequences for all involved: All branches based on master will now reference the old copy of the master branch that has been rewritten. So each branch must be rebased to the new master (which in turn changes all commit IDs). This effect continues, and can be very time-consuming to fix (depending on when such a rebase happens, and how many developers are involved in the project), especially if you’re new to git.

Therefore you should always remember the following rule:

Exceptions are conventions like personal branches or pu. The latter is an abbreviation for Proposed Updates and is usually a branch where new, experimental features are tested for compatibility. No one builds their own work on this branch, so it can be rewritten without problems and prior notice.

Another possibility is offered by private branches, i.e. those that start with <user>/ for example. If you make an agreement that developers will do their own development on these branches, but always base their features on “official” branches, then the developers may rewrite their branches as they wish.

If a feature is being developed over a long period of time, and parts of the feature are already flowing into a mainstream release (e.g. via cherry-pick), the rebase command will detect these commits and omit them when copying or rebuilding the commits, because the change is already contained in the branch.

For example, after a rebase, the new branch consists only of the commits that have not yet been incorporated into the base branch. This way, commits do not appear twice in the version history of a project. If the branch had simply been merged, the same commits with different SHA-1 sums would sometimes be present in different places in the commit graph.

There are situations where there is a vanilla version (“simplest version”) of a piece of software and also a certain number of patches applied to it before the vanilla version is shipped. For example, your company builds software, but before each delivery to the customer, some adjustments have to be made (depending on the customer). Or you have open source software in use, but have adapted it a bit to your needs - every time a new, official version of the software is released, you have to reapply your changes and then rebuild the software.⁠^[56]

To manage patch stacks, there are some programs that build on top of Git, but give you the convenience of not having to work directly with the rebase command. For example, TopGit⁠^[57] allows You can define dependencies between branches - if something changes in a branch and other branches depend on it, TopGit will rebuild them on demand. An alternative to TopGit is Stacked Git⁠^[58].

Now, you may have wondered: git rebase <reference> always copies all commits that are between reference> and HEAD. But what if you only want to implement part of a branch, to “transplant” it, so to speak? Consider the following situation:

You were developing a feature on the branch topic when you noticed a bug; you created a branch bugfix and found another bug. Semantically speaking, your branch bugfix has nothing to do with the topic branch. Therefore, it makes sense to branch off from the master branch.

But if you now rebuild the branch bugfix using git rebase master, the following happens: All nodes that are in bugfix but not in master are copied to the master branch in order - that is, nodes D, E, F, and G. However, D and E are not part of the bugfix at all.

This is where the --onto option comes into play: It allows you to specify a start and end point for the list of commits to be copied. The general syntax is

In this example, we only want to build the commits F and G (or also: the commits from topic to bugfix) from the top of master. Therefore the command is

The result looks as expected:

You have learned about the commit --amend command in Sec. 2.1, “Git Commands”, which you can use to improve a commit. However, it only refers to the current (last) commit. With rebase --onto you can also adjust commits that are further back in the past.

First, find the commit you want to edit and create a branch to it:

Then you make your changes, add changed files with git add, and then correct the commit with git commit --amend --no-edit (the --no-edit option takes meta-information like the description of the old commit and does not offer it again for editing).

Now apply all the commits from the master branch from above to your corrected commit:

This will copy all commits from 21d8691 (exclusive!) to master (inclusive!). The faulty commit 21d8691 is no longer referenced, and therefore no longer appears. The fix-master branch is now obsolete and can be deleted.

An equivalent way to edit a commit is with the edit action in the interactive rebase (see Sec. 4.2.2, “Editing Commits Arbitrarily”).

There are situations where you may need to adjust the default git rebase behavior. First, this is the case when you use rebase to edit a branch that contains merges. rebase may try to mimic these instead of linearizing the commits. The -p' or `--preserve-merges option is responsible for this. ⁠^[59]

With the -m or --merge option, you can tell git rebase to use merge strategies (see also Sec. 3.3.3, “Merge Strategies”). When using these strategies, keep in mind that rebase internally commits commit by commit to the new branch via cherry-pick; therefore the roles of ours and theirs are reversed: theirs refers to the branch you are building on a new base!

An interesting use case is therefore the strategy option theirs for the merge strategy recursive: If conflicts occur, priority is given to changes from the commit being copied. So such a scenario is useful if you know that there are conflicting changes, but are certain that the changes from the branch you are building are more correct than those from the tree you are building on. If you rebuild topic to master, such a call would look like this:

In cases where the recursive (default) strategy gives preference to changes from commits from topic', you will find a corresponding note `Auto-merging <commit description>.

A small, very useful option that rebase passes directly to git apply is --whitespace=fix. It causes Git to automatically correct whitespace errors (such as trailing spaces). If you have merge conflicts due to whitespace (for example, due to changed indentation), you can also use the strategy options presented in Sec. 3.3.4, “Options for the Recursive Strategy” to have solutions generated automatically (for example, by specifying -Xignore-space-change).

The squash and fixup commands allow two or more commits to be merged together.

Nobody always writes error-free code immediately. Often there is a big commit in which you have implemented a new feature; shortly after that, small bugs are found. What to do? A detailed description of why you forgot to add or remove a line out of carelessness? Not really useful, and especially annoying for other developers who want to review your code later. It would be nice to maintain the illusion that the commit was bug-free the first time…​

For every bug you find, make a small commit with a more or less meaningful description. This could look like this, for example:

When some such commits have accumulated, start an interactive rebase process over the last commits. Simply estimate how many commits you want to work on, and then edit the last five using git rebase -i HEAD~5, for example.

In the editor the commits now appear in reverse order compared to the output of git log. Now arrange the small bugfix commits so that they are below the commit you are fixing. Then mark the fix commits with squash (or s), like this:

Save the file and close the editor; the rebase process starts. Because you selected squash, rebase stops after commits are merged. The editor will display the commit messages of the merged commits, which you now summarize appropriately. If you use the keyword fixup, or f for short, instead of squash, the commit message of the commits marked in this way will be thrown away—​probably more convenient for this way of working.

After the rebase the version history looks much tidier:

If you start the commit message with fixup! or squash! followed by the beginning of the description of the commit you want to fix, you execute the command

The commits marked with fixup! or squash! as above are automatically moved to the correct position and given the action squash or fixup. This allows you to exit the editor directly, and the commits are merged. If you frequently work with this option, you can also make this behavior the default for rebase calls by setting a configuration option: To do this, set the rebase.autosquash setting to true.

If you mark a commit with edit, it can be edited as you wish. rebase will go through the commits sequentially, as in the other cases. For the commits marked edit, rebase stops and HEAD is set to the corresponding commit. You can then modify the commit as if it were the most recent in the branch. Afterwards, you let rebase continue running:

A convenient alternative to git blame on the console is the graphical tool git gui blame (you may need to install the git-gui package for this).

If you examine a file via git gui blame <file>, the different blocks that originate from different commits are displayed with a grey background. On the left you see the abbreviated commit ID and the initials of the author.

Only when you hover your mouse over such a block does a small popup window appear with information about the commit that changed the lines, possibly with a message stating from which file and which commit this block of code was moved or copied.

In code review, people are often interested in how a file actually looked like before a certain change was made. For this purpose, the graphical blame tool offers the following possibility to go back in the version history: Right-click on the commit ID of a code block and select Blame Parent Commit from the context menu - now the predecessor of this change is displayed. You can go back several steps this way. Use the green arrow in the upper left corner to jump back into the future again.

The syntax for patterns is based on the shell syntax:

An example:⁠^[60]

Files that are already versioned are not automatically ignored. To ignore such a file anyway, explicitly tell Git to “forget” the file:

To delete the file with the next commit, but still keep it in the working tree:

Files that are already ignored will not appear in the output of git status. Also, git add refuses to accept the file; the --force and -f options force Git to consider the file after all:

The git clean command deletes ignored as well as unknown (so-called untracked) files. Since files may be irretrievably lost, the command has the --dry-run (or -n) option; it tells you what would be deleted. As a further precaution, the command refuses to delete anything unless you explicitly pass the --force or -f.⁠^[61] option

By default, git clean only deletes the unknown files, with -X it only removes the ignored files, and with -x it removes both unknown and ignored files. With the option -d it additionally deletes directories that come into question. So to delete unknown as well as ignored files and directories, enter

With git stash you save the current state of working tree and index, if they differ from HEAD:

With the --keep-index option the index remains intact. This means that all changes that are already in the index remain in the working tree and in the index and are additionally stored in the stash.

The changes to the working tree and index are "put aside", and Git does not create a commit on the current branch. To restore the saved state again, ``apply the saved patch to the current working tree and delete the stash at the same time, use

Between saving and restoring the repository you can change the repository as you like, e.g. change the branch, make commits, etc. The stash is always applied to the current working tree.

The command git stash pop is an abbreviation for the two commands git stash apply and git stash drop:

Both pop and apply maintain the changes in the working tree, the index state is not restored again. The --index option also restores the stored state of the index.

Conflicts can occur if you apply a stash to a commit other than the one on which it was created:

In this case, use the usual recipes to solve the conflict, see Sec. 3.4, “Resolving Merge Conflicts”. It is important, however, that the conflict markers are labeled Updated Upstream (the version in the current working tree) and Stashed Changes (changes in the stash):

The stash is applied to the current working tree by default, provided it is clean - if not, Git aborts:

While Git suggests that you add the changes to the index, how you should proceed depends on your goal. If you want to have the changes in the stash in addition to those in the working tree, here’s a good idea:

For explanation: First, the unsaved changes to the working tree are added to the index; then the changes are extracted from the stash and applied to the working tree, and finally the index is reset.

Alternatively, you can create an additional stash and apply the changes you want to have to a clean working tree:

For this recipe you use several stashes. First you store the changes in the working tree into a new stash, then you get the changes you actually want from the previous stash and delete it after the application.

By default, Git sets the following message for a stash

In most cases this is sufficient to identify a stash. If you plan to keep your stashes longer (possible, but not really recommended), or if you want to do more than one, we recommend that you add a better note to them:

Git manages all stashes as a stack, i.e. more recent states are on top and are processed first. The stashes are named with a reflog syntax (see also Sec. 3.7, “Reflog”):

If you create a new stash, it will be called stash@{0} and the number of the others will be incremented: stash@{0} becomes stash@{1}, stash@{1} becomes stash@{2} and so on.

If you do not specify an explicit stash, the commands apply, drop and show refer to the most recent, i.e. stash@{0}.

To view individual stashes, use git stash show. By default, this command prints a balance of the added and removed lines (like git diff --stat):

The git stash list command prints a list of currently created stashes:

Individual stashes can be deleted with the command git stash drop, all with git stash clear. If you delete a stash by mistake, you won’t find it again via the usual reflog mechanisms! However, the following command prints the former stashes:⁠^[62]

It is also important that the entries shown in this way only exist as unreachable objects in the object database and are therefore subject to the normal maintenance mechanisms — they are therefore deleted after some time and are not kept permanently.

Git creates two commit objects for each stash, one for working tree changes and one for index changes. Both have the current HEAD as their ancestor, the working tree object has the index object as its ancestor. This makes a stash in Gitk appear as a triangle, which is a bit confusing at first:

With the alias git tree (see Sec. 3.6.1, “Revision Parameters”) this looks like this:

Since the stash objects are not referenced by a branch, the working tree object is kept alive with a special reference, refs/stash. However, this only applies to the latest stash. Older stashes are only referenced in the Reflog (see ` Sec. 3.7, “Reflog”) and therefore do not appear in Gitk. In contrast to normal reflog entries, stored stashes do not expire and are therefore not deleted by the normal maintenance mechanisms.

You start a bisect session with the following commands:

Once you’ve defined the two points, Git checks out a commit in the middle, so you’re now in detached-head mode (see Sec. 3.2.1, “Detached HEAD”). After you have checked whether the regression is still present, you can mark it with git bisect good or git bisect bad. Git will automatically check out the next commit.

You may not be able to test the checked out commit, for example, because the program does not compile correctly. In this case, you can use git git bisect skip to have another commit nearby selected and proceed with it as usual. You can cancel the debugging at any time with git bisect reset.

Ideally, you can test automatically whether the error occurs — with a test that must run successfully if the regression does not occur.

You can then define the points good and bad as above. Afterwards you enter git bisect run <path/to/test>.

Based on the return value, bisect decides whether the checked commit is good (if the script ends successfully, i.e. with return value 0) or bad (values 1—​127). A special case is the return value 125, which causes a git bisect skip. So if you have a program that needs to be compiled, the first thing you should do is to add a command like make || exit 125, so that the commit is skipped if the program does not compile properly.

Bisect can then automatically identify the problematic commit. This looks like this, for example:

Git supports several protocols for accessing a remote repository, the most common three being Git protocol, SSH, and HTTP(S). Designed specifically for Git, the Git protocol favors data transfer by always transferring the smallest possible amount of data. It doesn’t support authentication, so it’s often transmitted over an SSH connection. This ensures both efficient (Git protocol) and secure (SSH) transmission. HTTP(S) is used when a firewall is configured very restrictively and the allowed ports are drastically restricted.⁠^[67]

In general, a valid URL contains the transfer protocol, the address of the server and the path to the repository:⁠^[68]

For the SSH protocol the short form still exists:

It is also possible to clone repositories locally using the following syntax:

If you want to know what URLs are configured for a remote repository, use git remote’s --verbose or -v option:

You can see that there are two URLs for the remote repository origin, but they are set to the same value by default. The first URL (fetch) specifies from where and with which protocol changes are downloaded. The second URL (push) specifies where changes are uploaded to and with which protocol. Different URLs are particularly interesting if you download or upload with different protocols. A common example is to download with the git protocol (git://) and upload with the SSH protocol (ssh://). It is then downloaded without authentication and encryption, which provides a speed advantage, but uploaded with authentication and encryption, which ensures that only you or other authorized people can upload. You can use the git remote set-url command to customize the URLs:

The current status of the remote repository is stored locally. Git uses the mechanism of remote tracking branches, special branches — local references — that reflect the state of the remote branches. They “track” the remote branches and are advanced or set by Git when synchronizing with the remote, if the branches in the remote have changed. In terms of the commit graph, remote tracking branches are markers within the graph that point to the same commits as the branches in the remote repository. You can’t modify remote tracking branches like normal branches; Git manages them automatically, so it updates them. When you clone a repository, Git initializes a remote tracking branch for each remote branch.

Figure 31, “Generated Remote Tracking Branches” shows an example. The origin remote repository has three branches: pu, maint, and master. Git creates a remote tracking branch in the cloned repository for each of these remote branches. It also creates a local branch master in the clone that corresponds to the remote branch master. This is checked out and is the branch you should work in if you plan to upload commits to the master (but see Sec. 5.3.1, “git fetch”).

In the git fetch example, there is only one branch on the remote side, master. That’s why Git creates only one remote tracking branch in the clone, origin/master. The git branch -r command shows all remote tracking branches:

The special entry origin/HEAD → origin/master states that in the remote repository the HEAD points to the branch master. This is important for cloning, because this branch is checked out after cloning. The list of remote tracking branches is a bit sparse in this example, you can see more entries in a clone of the Git-via-Git repository:

All branches can be displayed with git branch -a:

In this case, Git uses the prefix remotes/ to clearly distinguish remote tracking branches from normal ones. If you have enabled color output, the different branches will also be color-coded: the checked-out branch green, remote tracking branches red.

Remote Tracking Branches are also references only and are therefore stored under .git/refs like all references. However, since they are special references that are also linked to a remote repository, they end up under .git/refs/remotes/<remote-name> (see Sec. 3.1.1, “HEAD and Other Symbolic References”). In Gitk, the remote tracking branches are displayed with the prefix remotes/<remote-name>/, which is also colored dark yellow (Figure 32, “Branch next and the corresponding remote tracking branch in Gitk”).

As soon as new commits are created by other developers in a remote, you want to download them to your local repository. In the simplest case, you just want to find out which commits you don’t have locally, download them, and update the remote tracking branches so that they reflect the current status in the remote.

Use the git fetch command to do this:

Git acknowledges the call with a message that origin/master has been set from commit 79170e8 to commit 003e3c7. The notation master → origin/master indicates that the branch master from the remote was used to update the remote tracking branch origin/master. In other words: Branches from the remote on the left and remote tracking branches on the right.

See Figure 33, “Remote Tracking Branches are updated” for the effect this has on the commit graph: On the left side is the initial state of the remote origin and next to it that of the clone. Both the remote and the clone have new commits since the last synchronization (C and D). The remote tracking branch origin/master in the clone points to commit B; this is the last state of the remote known to the clone. By calling git fetch origin, Git updates the remote tracking branch in the clone to reflect the current status of the master (pointing to commit C) in the remote. To do this, Git downloads the missing commit C and then sets the remote tracking branch on it.

Suppose you want to transfer commits from the remote repository to your local branch. To do this, first run a git fetch to fetch new commits, and then merge the change from the corresponding remote tracking branch:⁠^[71]

For this use case, Git provides the git pull command to speed up your workflow. It is a combination of git fetch and git merge or git rebase.

Downloading new commits from origin and merging all commits referenced by the master there into the current branch can be done with the following command:

In Figure 34, “What happens with a pull” we illustrate the process. On the left, you see the remote repository origin and next to it the current status of the local repository. The repository was cloned when it only contained commits A and B, so the remote tracking branch points origin/master to B. In the meantime, both the remote (C) and local (D) repositories have been added.

On the right side is the state after git pull origin master. Commit C has been added to the local repository. The fetch call contained in the pull has updated the remote tracking branch, i.e. it points to the same commit as the master in origin and thus reflects the state there. In addition, the merge call contained in the pull has integrated the master from origin into the local master, as you can see from the merge commit M and the current position of the local master.

Alternatively, the --rebase option instructs the pull command to rebase the local branch to the remote tracking branch after fetch:

In Figure 35, “What happens during a pull with rebase” you can see what happens if you perform a rebase instead of the default merge.

The initial situation is the same as in Figure 34, “What happens with a pull”. The fetch contained in the pull moves the remote tracking branch origin/master to commit C. However, rebase does not create a merge commit; instead, a call to rebase gives the commit D a new base, and the local master is set to the new commit D'. (Rebase is described in detail in Sec. 4.1, “Moving commits — Rebase”).

Git beginners often ask themselves whether they should use fetch or pull. The answer depends on how you develop: How big is the project? How many remotes are there? How heavily are branches used?

There are two ways to delete references in the remote: The older one (before Git version 1.7.0) is to omit the local reference in the refspec — this statement means you want to upload “nothing”. So you replace an existing reference with the empty one.

However, newer git versions usually use the git push command with the --delete option, which is syntactically much clearer:

Note that in other clones, the remote tracking branch origin/bugfix, if present, does not automatically disappear! See the section on pruning above (Sec. 5.3, “Downloading Commits”).

In everyday life you often run git push without specifying remote and refspec. In this case, Git uses the configuration entries (upstream branch and push.default) to decide which references are sent where.

By default, Git proceeds like this:⁠^[73] If you don’t specify a remote, Git will look for the upstream configuration of the current branch. If the name of the branch on the remote side matches the name of the local branch, the corresponding reference is uploaded (this is to protect you from uploading, for example, your branch devel to master if the upstream configuration is incorrect). If no upstream branch is configured, Git aborts with an error message:

If you use git push <remote> to specify a remote but no branch, Git will attempt to upload the current branch to the remote under the same name.

The strategy described here is also known as simple. For most use cases, it does what the user expects and protects against avoidable errors. However, you can set the push.default option responsible for this to one of the following values if required:

In some cases, Git will automatically configure upstream branches (for example, after a git clone). However, you need to do this explicitly, especially for new branches that you are uploading for the first time. You can do this either afterwards using the --set-upstream-to option or, in short, -u of git branch:

Alternatively, and if you think about it, you can also have git push write the configuration when you call git push with the -u option:

To view the upstream configuration of your branches, call git branch -vv. The output shows the upstream partner of a branch (if any) in square brackets.

The git remote show command gives a concise summary of the remote, including the branches available there, whether they are tracked locally (tracking status) and which local branches are configured for specific tasks.

The command must request the current status from the remote, i.e. the command fails if the remote is not available, e.g. due to a missing network connection. The option -n prevents the query.

If you have configured an upstream branch, when you change the branch (git checkout) and query the status (git status), you will receive a notification about the status of the branch compared to the upstream, for example:

Here there are four different possibilities:

With the -v (compare only) or -vv (compare and upstream name) option, git branch displays the appropriate information for local branches:

The command prints the SHA-1 prefix for all branches and the commit message of the current commit. If an upstream is configured for the branch, Git returns both the name and a comparison to the upstream. In the example, you see four different branches. master has an additional commit that has not yet been uploaded to the remote, and is therefore ahead. The branch feature, on the other hand, has no upstream branch configured, so it currently exists only locally. The branch next is up-to-date with the corresponding remote tracking branch. The Branch pu, on the other hand, “lags” behind its upstream and is therefore displayed as behind. The only state missing here is diverged — then both ahead and behind are shown including the number of “missing” commits.

To generate a pull request automatically, there is the git command request-pull. The syntax is:

As <URL> you specify your public repository (either as the actual URL or as a configured remote repository), and as <start> you select the reference on which the feature is built (in many cases the branch master, which should match the master branch of the official repository). Optionally, you can specify an <end>; if you omit this, Git will use HEAD.

The output is by default STDOUT, and includes the repository’s URL and branch name, a short description of all commits by author, and a diff state, i.e., a balance of added and deleted lines by file. This output can easily be forwarded to an e-mail program. If you add the -p option, a patch with all changes is appended below the text.

For example, to ask someone to download the two latest commits from a repository:

In principle, Git automatically downloads new tags when you call git fetch or git pull. That is, if you download a commit that has a tag pointing to it, that tag will be included. However, if you use a refspec to exclude individual branches, then commits in those branches will not be downloaded, and thus no tags that may point to those commits will be downloaded. Conclusion: Git only downloads relevant tags. With the options --no-tags (no tags) and --tags or -t (all tags) you can adjust the default behavior. Note, however, that --tags not only downloads the tags, but necessarily the commits to which they point.

Git notifies you when new tags arrive:

If you want to know what tags are present on the remote side, use git ls-remote with the --tags option. For example, you can get all release candidates of git version 1.7.1 with the following call:

Git outputs the SHA-1 sums of the tags and their contents.⁠^[75]

Git does not automatically upload tags. You need to pass them explicitly to git push, similar to the branches, e.g. to upload the tag v0.1:

If you want to upload all tags at once, use the --tags option. But be careful: Avoid this option if you use Annotated Tags to mark versions and Lightweight Tags to mark something locally, as described in Sec. 3.1.3, “Tags — Marking Important Versions”, because with this option you would upload all tags, as already mentioned.

Attention: Once you have uploaded a tag, you should never change it! The reason: Let’s say Axel changes a tag, like v0.7, that he has already released. First it pointed to the 5b6eef commit, and now to bab18e. Beatrice had already downloaded the first version pointing to 5b6eef, but Carlos had not yet. The next time Beatrice calls git pull, Git won’t download the new version from the v0.7 tag; the assumption is that tags don’t change, so Git doesn’t check the validity of the tag! When Carlos now runs git pull, he also gets the v0.7 tag, but it now points to bab18e. Finally, two versions of the tag — each pointing to different commits --- are in circulation. Not a very helpful situation. It gets really confusing when both Carlos and Beatrice use the same public repository, and upload all tags by default.⁠^[76] The tag “jumps” back and forth between two commits in the public repository, so to speak; which version you get with a clone depends on who pushed last.

If you do get this mishap, you have two options:

The git format-patch command exports one or more commits as patches in Unix mailbox format and prints one file per commit. The file names consist of a sequential numbering and the commit message, and end in .patch.⁠^[77] As an argument, the command expects either a single commit or a range such as A..B. If you specify a single commit, Git will evaluate this as the selection from the commit to the HEAD.

Figure 38, “Formatting three commits to 'master' as patches” shows the initial situation. We want to export the three commits in the fix-git-svn-docs branch, that is, all commits from master, as patches:

The generated files contain, among other things, the header fields From, Date and Subject, which are used for sending as e-mail. These fields are completed using the information available in the commit — author, date, and commit message. The files also contain a diff-stat summary and the changes themselves as a patch in unified diff format. The [PATCH m/n] suffix⁠^[78] in the subject line is used later by Git to apply the patches in the correct order.

A corresponding excerpt follows:

If you plan to send a series of patches, it is recommended that you use the --cover-letter option to create a kind of “cover page” in which you describe the series. By default the file is called 0000-cover-letter.patch. Apart from the default headers, such a file looks like this:

As you can see, the Subject: still has the prefix [PATCH 0/3]; this way, all recipients can immediately see that it is a cover page. The file also contains the output of git shortlog and git diff --stat. Replace * SUBJECT HERE with a subject and BLURB HERE * with a summary of the patch series. Send the file together with the patch files.

Send the generated files with git send-email (or an email client of your choice). The command expects as its only mandatory argument either one or more patch files, a directory full of patches, or a selection of commits (in which case Git also calls git format-patch internally):

The command git send-email sets the fields Message-Id and In-Reply-To. This makes all e-mails after the first one look like replies to them and thus most mail programs will display them as a continuous thread:⁠^[79]

You can customize the command with options such as --to, --from and` --cc` (see the git-send-email(1) man page). However, if not specified, the essential information is queried interactively — most important is an address to which the patches should be sent.⁠^[80]

Before the emails are actually sent, you will see the header again; you should check if everything is as you want it, and then answer the question` Send this email? ([y]es|[n]o|[q]uit|[a]ll):` answer with y for “yes”. To get familiar with the command, you can first send all emails only to yourself or use the --dry-run option.

If you want to use your preferred Mail User Agent (MUA) (e.g. Thunderbird, Kmail or others) to send patches, there may be a few things to consider. Some MUAs are notorious for mutilating patches so that Git won’t recognize them as such.⁠^[83]

Patch emails exported with git format-patch are translated back into commits by the git command git am (apply from mailbox). A new commit is created from each email, and its meta-information (author, commit message, etc.) is generated from the email header lines (From, Date). As mentioned earlier, Git uses the number in the subject to determine the order in which the commits should be entered. To complete the example from earlier: If the emails are in the Maildir directory patches, then that’s enough:

When you apply patches from others using git am, the values of Author/AuthorDate and Committer/CommitDate are different. This means that both the author of the commit and the person who commits it are honored. In particular, the attributes are retained; it remains traceable who wrote which lines of code. With Gitk, the author and committer values are displayed by default; on the command line, set the --format=fuller option, which is accepted by git log and git show, among others:

With the Dictator and Lieutenants Workflow (Sec. 5.10, “A Distributed, Hierarchical Workflow”), it can happen that more than two people are involved in a commit. In this case, it makes sense that everyone who reviews the patch also “approves” it, especially the author. For this purpose, there is a --signoff option (-s for short) for the git commit and git am commands, which appends the committer’s name and email to the commit message:

This feature is especially useful for larger projects, which usually have guidelines on how to format commits and how best to send them.⁠^[84]

Conflicts can occur when patches are entered with git am, e.g. if the patches are based on an older version and the lines concerned have already been changed. In this case, the process is interrupted and you then have several options for how to proceed. Either resolve the conflict, update the index and continue the process with git am --continue, or skip the patch with git am --skip. Use git am --abort to abort the process and restore the current status of the branch.

Because patches usually contain changes made by others, it can sometimes be difficult to find the right solution to a conflict. The best strategy for patches that cannot be applied is to ask the author of the patches to rebase them to a well-defined base, such as the current master, and send them again.

Submodules are managed by Git as subdirectories that have a special entry in the .gitmodules file. The command git submodule is responsible for handling them.

First we need to import the library. This is done with the following command:

From the output of git status we can now see that there is a new directory libgit2 and that the file .gitmodules with the following content has been created

This file has already been added to the index, prepared for committing. The libgit2 directory, on the other hand, does not appear in the output of git diff --staged as usual:

Instead of listing all the files in the directory, Git saves a “special” file (recognizable by the unusual file mode 160000) that simply records the commit the module is currently on.

We import these changes, and from now on we can compile libgit2 in its subdirectory and then link against it:

The parent project and libgit2 are now merged in the working tree, but their version history is and remains separate. In the Git repository of libgit2 you can behave exactly the same way as in a “real” repository. For example, you can look at the output of git log in the parent project and after a cd libgit2 in the submodule.

Unlike submodules, which maintain their character as a standalone Git repository, when you work with Subtrees, you directly merge the history of two projects. A comparison of the two approaches follows.

Essentially, this technique is based on so-called subtree-merges, which were briefly discussed in Sec. 3.3.3, “Merge Strategies” about merge strategies. In our example, a subtree-merge is done by merging regular commits from the libgit2 repository under the libgit2/ tree (directory) — a top-level file in the library repository thus becomes a top-level file in the libgit2/ tree, which in turn is part of the repository.

Git has a command to manage subtree-merges.⁠^[86] You must always explicitly specify which subdirectory you are referring to by using -P <prefix>. To import the libgit2 in version 0.8.0, use:

The command automatically downloads all required commits and creates a merge commit that creates all the files of libgit2 under the directory libgit2/. The merge commit now links the previous version history to that of libgit2 (by referencing an original commit and then referencing other commits).

The result of this procedure is that your repository now contains all relevant commits from libgit2. Your repository now has two root commits (see also multi-root repositories in Sec. 4.7, “Multiple Root Commits”).

The files are now stored inseparably linked to the project. A git clone of this repository would also transfer all files under libgit2.⁠^[87]

Now what happens when you want to “upgrade” to v0.10.0? Use the pull command from git subtree for this:

Note: Since the original libgit2 commits are present, these commits also seem to change top-level files (e.g., COPYING when you use git log --name-status to examine the version history). In fact, these changes are actually made in libgit2, which is the responsibility of the merge commit, which aligns the trees accordingly.

The question “Submodules or Subtrees?” cannot be answered in general, but only on a case by case basis. The decisive criterion should be the affiliation of the subproject to the superordinate one: If you include third-party software, it is probably more likely to be submodules, your own with limited commits and a direct relationship to the main project rather than a subtree.

For example, when you install CGit (see Sec. 7.5, “CGit — CGI for Git”), you must initialize and update a submodule to compile libgit.a. So CGit needs the source code of Git, but doesn’t want to merge the development history with that of Git (the comparatively few CGit commits would be lost in this!). You can, however, compile CGit against another version of Git if you wish — the flexibility of the sub-repository is preserved.

The graphical repository browser Gitk, on the other hand, is managed as a subtree. It is developed in git://ozlabs.org/~paulus/gitk, but is included in the main Git repository with the subtree-merge strategy under gitk-git/.

The maintainer of a software must have a good overview of the features that are actively being developed and will soon be integrated. In most development models, commits graduate from one branch to the next — in the model presented above, first from the pu branches to next and then to master.

First of all, you should always clean up your local branches in order not to lose the overview. The command git branch --merged master, which lists all branches that are already fully integrated into master (or another branch), is especially helpful here. You can usually delete these.

To get a rough overview of the tasks that need to be done, it is recommended to use git show-branch. Without any further arguments, it lists all local branches, each with an exclamation mark (!) in its own color. The current branch gets a star (*). Below the output all commits are shown and for each branch in the respective column a plus (+) or a star (*) if the commit is part of the branch. A minus (-) indicates merge commits.

Only so many commits are shown until a common merge base of all commits is found (in the example: master~4). If you don’t want to examine all branches at once, but only the branches under pu/, for example, then explicitly specify this as argument. --topics <branch> defines <branch> as integration branch, whose commits are not explicitly shown.

So the following command shows you all commits of all pu branches and their relation to master:

However, the git show-branch command only recognizes identical, i.e. identical commits. If you use git cherry-pick to copy a commit to another branch, the changes are almost the same, but git show-branch would not detect this because the SHA-1 sum of the commit changes.

The git cherry tool is responsible for these cases. It uses the small tool git-patch-id internally, which reduces a commit to its changes. It ignores whitespace changes and the contextual position of the hunks (line numbers). So the tool returns the same ID for patches that essentially commit the same change.

Usually, git cherry is used when the question arises: Which commits have already been transferred to the integration branch? The command git cherry -v <upstream> <topic> is used for this: It lists all commits from <topic>, and puts a minus (-) in front of them if they are already in <upstream>, otherwise a plus (+). This looks like this:

Two of the patches were already applied after master. git cherry recognizes this, although the commit IDs have changed.

Git provides the following two useful tools to help you prepare for a release:

A good release includes a so-called changelog, i.e. a summary of the most important changes including thanks to people who have contributed help. This is where git shortlog comes in. It shows the respective authors, how many commits each one has made, and the commit messages of each commit. This makes it easy to see who did what.

The --numbered or -n option sorts the output by the number of commits instead of alphabetically. With --summary or -s the commit messages are omitted.

But if in doubt, don’t simply write the output of git log or git shortlog to the file CHANGELOG. Especially with many technical commits, the changelog is not helpful (if you’re interested in this information, you can always check the repository). But you can take the output as a basis, delete unimportant changes and combine the rest into meaningful groups.

The git archive command helps to create a source code archive. The command can handle both tar and zip format. Additionally, you can set a prefix for the files to be saved with the option --prefix=. The top level of the repository is then stored below this prefix, usually the name and version number of the software:

As a mandatory argument the command expects a commit (or a tree), which should be packed as an archive. In the above example the HEAD. But it could also have been a commit ID, a reference (branch or tag) or directly a tree object.⁠^[91]

Again, you can use git describe after you have tagged a release commit. If you have a suitable tag scheme <name>-<X.Y.Z> as above, the following command is sufficient:

It’s possible that not all of the files you manage in your git repository should also be in the source code archives, such as the project website. You can also specify paths - so to limit the archive to the src directory and the LICENSE and README files, use

Git will store the SHA-1 sum in the archive if you specify a commit as an argument. In tar format, this is stored as a pax header entry, which Git can read again with the command git get-tar-commit-id:

In zip files, Git simply saves the SHA-1 sum in the comment field:

Git is designed for decentralized repository management; the smallest unit for exchanging changes between repositories is commits. However, since there are sometimes thousands of commits between two versions of a piece of software, and a single commit-by-commit transfer would generate a lot of overhead, commits are grouped together into so-called packfiles before being transferred. These packfiles are a simple but effective format.⁠^[92] They are also used to store (older) commits on the hard disk in a space-saving way (git gc or git repack, see Sec. B.1, “Cleaning Up”).

These packfiles are usually transmitted via the Git protocol, which runs on port 9418/TCP by default. The Git protocol is deliberately kept very simple in design and offers only a few functions that are directly related to the structure of Git: What data to send or receive, and a way for the sender and receiver sides to agree on the smallest possible amount of data that needs to be transmitted to synchronize both sides.

Therefore, the Git protocol does not include any authentication option. Instead, Git uses an already existing, secure and simple authentication structure: SSH, the 'Secure Shell'.

So while the Git protocol can be used unencrypted and in raw form for anonymous read-only access, writing or uploading via Git protocol only works via SSH.

Git also supports transport via HTTP(S), FTP(S), and Rsync. Although Rsync is now considered deprecated, and should not be used anymore, there are some use cases for HTTP(S): In particularly restrictive environments with very restrictive firewall rules, you may be able to access a repository via HTTP(S) (i.e. only on port 80 or 443) for both read and write operations. Platforms like GitHub (see Ch. 11, GitHub) therefore offer HTTPS as default transport method.

If you want to synchronize changes to repositories on the same computer, this does not have to be done via detours: Git communicates directly with the other side via Unix pipes, negotiates a common basis and synchronizes the data. (Of course, this requires that the user invoking the Git command has at least read permission to the other repository’s pack files).

So far, you’ve probably worked mostly with Git repositories, which were working tree and repository in one: The repository-internal data is stored in the .git subdirectory, all other files belong to the working tree, i.e. you can edit them while Git observes and stores the changes to these files (tracking).

A so-called bare repository, i.e. a “mere” repository, has no assigned working tree. It contains only the files and directories that are stored in a “regular” repository under .git.

You create such a bare repository with git init --bare. Take a look at the difference between the two options:

To create a backup of one of your normal repositories, you can create a new bare repository (e.g. on a USB stick) and upload all your references (and thus all your commits):

With git init the files are usually created with read and write permission according to the umask setting. This is also a convenient choice for the end user. However, if you want to set up a repository on a server, you can use the --shared option to specify who (at the filesystem level) can access the repository.

When you initialize a repository with --shared, the receive.denyNonFastForwards option is automatically set. It prevents uploading commits that cannot be integrated via Fast-Forwards (even if the user explicitly wants to via git push -f).

Usually, write access to Git repositories located on another computer can only be granted via SSH. However, it is generally undesirable to grant a user who will have access to a repository the same user rights to the whole system.

Git works around this problem with the included git-shell program. It works like a shell, but only allows you to run four Git commands that are responsible for uploading and downloading pack files. Interactive use or execution of other commands is denied by the shell unless you explicitly enable the “Interactive Mode” of the shell — see the git-shell(1) man page for details.

If you create a new user and assign the git shell to him, e.g., using chsh <user>, he cannot log in via SSH, but he can upload commits to all git repositories to which he has write permission.

It’s a major advantage that Git uses SSH as an encrypted and authenticated transport channel, because most users already have a key pair (public/private) with which they log in on other computers.

So instead of tediously assigning (and then sending out) passwords to accounts, a system administrator can limit access to Git repositories to users who authenticate against SSH public keys. This saves time for the user (by eliminating the need to re-enter a password), but also saves the administrator from having to worry about password changes (which would not be easily possible using the Git shell).

In the following we will show you how to set up two users on your system, max and moritz, and let them work on the same repository.

First, we have to set up a repository that the two users will want to access later. Assuming that other repositories might follow later, we will create a Unix group git (generally for Git users) and a directory /var/repositories with read permission for members of the git group, as well as a git-example group and its corresponding directory, writeable only for members of git-example, in which the repository will later be located:

We also create a repository in the last created directory:

Next we create the two users. Note that this call will not create a home directory for the users under /home/. Also, both are added to the git and git-example groups:

Next, we have to assign a password to each user via passwd so that they can log in via SSH. Afterwards, the new users can now work together on a project. You add the remote as follows:

All other users who want to contribute to this project must belong to the git-example group. So this approach is essentially based on the use of Unix groups and Unix users. However, a server admin usually wants to offer not only Git, but various services. And to control the user administration entirely via Unix groups is rather inflexible.

The installation of Gitolite is simple. All you need to do is have your public key ready to register as an administrator. You don’t need root privileges unless you need to create the git user first,⁠^[95] so skip the next step if you have already created such a user.

First, create a user on the computer that will act as the git server (henceforth <server>). Usually, this user is called git, but you may also call it something else (e.g. gitolite). You can specify /home/git as your home directory or, as in this example, something like /var/git:

Now switch to the git user. Gitolite needs the .ssh/ and bin/ directories, so we need to create them:

Now clone the Gitolite repository and install a symlink to bin (this is already the whole installation):

You can now configure Gitolite and enter your public key with which you want to manage the Gitolite configuration:

Check that Gitolite works on the computer where you normally work (and where you have stored the corresponding private key):

You should verify that your key gives you read and write permission to the gitolite-admin repository. Now clone it onto your computer:

The repository contains the entire configuration for Gitolite. You check in your changes there and upload them via git push: the server automatically updates the settings.

The Gitolite admin directory contains two subdirectories, conf and keydir. To introduce a new user to Gitolite, you need to put their SSH key under keydir/<user>.pub. If the user has multiple keys, you can store them in separate files of the format <user>@<description>.pub:

Don’t forget to check in the new keys with git add keydir followed by git commit. To make them known to the gitolite installation, you also need to upload the commits using git push.

Then you can assign permissions to this username in the conf/gitolite.conf configuration file.

You can save yourself a lot of administrative work and typing by using macros. You can combine groups (of users or repositories), e.g.:

These macros are also evaluated recursively. When defining them, it does not have to be clear whether they are users or repositories; the macros are only evaluated at runtime. This allows you to create groups from other groups:

There is a special group @all which, depending on the context, contains all users or all repositories.

You can configure one (or more) repositories as follows:

R and W stand for read or write access. The plus means that forced uploading is also allowed (non-fast-forward, i.e. also deleting commits).

For a repository, of course, several such lines can be entered. In a small project there could be maintainers, other developers and testers. Then the access rights could be regulated as follows:

Thus, the testers have read-only access, while the developers are allowed to upload new commits, but only if they can be integrated via fast-forward. The main maintainers are allowed “everything”.

These lines are processed sequentially. If the line applies to a user, Gitolite authorizes the user and grants him the appropriate rights. If no line matches the user, the user is rejected and is not allowed to change anything in the repository.

A user can view all his permissions by simply logging into the Git server via SSH. Immediately after installation, this is how it looks like to the administrator:

If you want to install a web-based tool to browse the Git repositories later, you should also name a person in charge and describe the project:

For this to work, you must first enable Gitolite to set these config settings: This is done on the server where Gitolite is installed, in the file .gitolite.rc: Enter the value gitweb\..* under the GIT_CONFIG_KEYS key.

Especially in corporate environments, access rights often have to be differentiated even more finely than a mere “has access” and “must not access”. For this purpose, Gitolite offers access restriction on directory- and file- as well as tag- and branch-level.

We will first look at a case that occurs frequently: developers should be able to develop on development branches at will, but only a small group of maintainers should be able to edit “important” branches such as master.

This could be implemented in a similar way:

Here a “development namespace” is created: The group of developers can work with branches below dev/, e.g. create dev/feature or delete it. However, the developers can only read the master branch, not change it — this is reserved for the maintainers.

The part between the flags (RW+) and the equal sign is a so-called Perl-Compatible Regular Expression (PCRE). If it does not start with refs/, the expression refers to all references below refs/heads/, i.e. branches. In the above example, any references below refs/heads/dev/ can be modified — but not the dev branch itself, nor anything-dev!

But if such an expression starts explicitly with refs/, you can manage any references. In the following way you can set up that all maintainers are allowed to create Release Candidate tags,⁠^[96] but only one maintainer is really allowed to create the versioning tag (or any other):

If one of the maintainers still wants to upload a tag like v1.0, the following happens:

As mentioned above, here the rules are applied one after the other. Since the tag v1.0 does not match the regular expression above, only the bottom line comes into question, but the username does not match. No line is left (fallthru), so the action is not allowed.

The concept of personal namespaces is somewhat more flexible. This gives each developer his own hierarchy of branches that he can manage.

There is a special keyword for this, USER, which is replaced by the user name currently accessing the branch. This makes the following possible:

Now all developers under p/<user>/ can manage their branches as they like. The lower directive makes sure that all developers can read these branches. Now max can e.g. create p/max/bugfixes, but moritz can only read them.

Gitolite also allows file- and directory-level access restrictions. The virtual reference VREF/NAME is responsible for this. For example, you can allow the documentation team only (writing⁠^[97]) access to doc/:

However, the following pitfalls must be taken into account: Once the keyword VREF/NAME appears once, the file-based rules are applied to all users. If none of them apply, access is allowed — so the second rule is important, which prohibits access for @doc unless the commit only modifies files under doc/ (see also Sec. 7.2.7, “Explicitly Prohibiting Actions” below).

Access control checks at the commit level which files are modified; if a commit contains changes to a file that the user is not allowed to edit, the entire push process is aborted. In particular, no actions can be performed that involve commits from other developers that modify files outside the allowed range.

Specifically, in relation to the above example, this means that @doc members generally cannot create new branches. Creating a new branch would mean creating a new reference to an initial commit and then fast-forwarding all commits from top to root, i.e., the entire project history. However, there are certainly commits in it that modify files outside of doc/, and so the action is prohibited.

Previously, a user was only rejected if he failed all rules (fallthru), i.e. if no rights were assigned to him. But the - flag (instead of RW) can be used to explicitly restrict access. Again, the rules are passed through from top to bottom.

This directive prohibits members of @developers from making commits that modify the Makefile.⁠^[98]

By convention, you should never upload forced updates to the master or maint branches (see also Sec. 3.1, “References: Branches and Tags”). You can now force this policy with Gitolite:

If a branch that is not called master or maint is uploaded, only the third rule is applied and arbitrary access (including non fast-forward updates) is allowed. Commits that can be integrated to master or maint via fast-forward are allowed by the first rule. Note the missing plus sign, though: A forced update is not covered by the first rule, but by the second one, which explicitly prohibits everything (that has not been allowed before).

With the means presented here and others, which you can take from the documentation, ⁠^[99] you are able to force policies very flexibly. However, it may not be useful to control everything down to the smallest detail. As mentioned above, especially a control on file name level is problematic. Then, if hours of work go into a commit, but it can’t be uploaded because one of those restrictions prohibits it, the frustration is great (and fixing that commit is not trivial, either; see rebase, Sec. 4.1, “Moving commits — Rebase”).

At the branch level, it makes sense to give only a limited group of developers access to “important” branches (such as master). Of course, strict control over who can do what comes at the expense of flexibility, and it’s this flexibility that makes branching in Git so practical.

As a rule, the Git daemon is supposed to constantly deliver a large number of repositories. To do this, it runs constantly in the background or is restarted for each request. The latter task is typically performed by Inetd from OpenBSD. To make this work, you just need to add the following (one!) line to /etc/inetd.conf:

<user> must be a user who has read access to the repositories. This can be root, because the Inetd normally runs with root privileges, but should be git or a similarly unprivileged account.

The configuration for the xinetd is similar, but more self-explanatory. It is stored e.g. under /etc/xinet.d/git-daemon:

Do not forget to restart the respective daemon via /etc/init.d/[x]inetd restart.⁠^[101]

Debian offers the git-daemon-run package which contains configuration files for sv.⁠^[102] The package essentially creates a gitlog user and two executable shell scripts, /etc/sv/git-daemon/run and /etc/sv/git-daemon/log/run. Modify the former to run the Git daemon in the directory where your repositories are located: