Git 2.13.0  •  User's Manual

Home

Developing with Git (draft)

Telling Git your name

Before creating any commits, you should introduce yourself to Git. The easiest way to do so is to use linkgit:git-config[1]:

$ git config --global user.name 'Your Name Comes Here'
$ git config --global user.email 'you@yourdomain.example.com'

Which will add the following to a file named .gitconfig in your home directory:

[user]
        name = Your Name Comes Here
        email = you@yourdomain.example.com

See the “CONFIGURATION FILE” section of linkgit:git-config[1] for details on the configuration file. The file is plain text, so you can also edit it with your favorite editor.

Creating a new repository

Creating a new repository from scratch is very easy:

$ mkdir project
$ cd project
$ git init

If you have some initial content (say, a tarball):

$ tar xzvf project.tar.gz
$ cd project
$ git init
$ git add . # include everything below ./ in the first commit:
$ git commit

How to make a commit

Creating a new commit takes three steps:

1. Making some changes to the working directory using your favorite editor.

2. Telling Git about your changes.

3. Creating the commit using the content you told Git about in step 2.

In practice, you can interleave and repeat steps 1 and 2 as many times as you want: in order to keep track of what you want committed at step 3, Git maintains a snapshot of the tree’s contents in a special staging area called “the index.”

At the beginning, the content of the index will be identical to that of the HEAD. The command git diff --cached, which shows the difference between the HEAD and the index, should therefore produce no output at that point.

Modifying the index is easy:

To update the index with the contents of a new or modified file, use

$ git add path/to/file

To remove a file from the index and from the working tree, use

$ git rm path/to/file

After each step you can verify that

$ git diff --cached

always shows the difference between the HEAD and the index file—this is what you’d commit if you created the commit now—and that

$ git diff

shows the difference between the working tree and the index file.

Note that git add always adds just the current contents of a file to the index; further changes to the same file will be ignored unless you run git add on the file again.

When you’re ready, just run

$ git commit

and Git will prompt you for a commit message and then create the new commit. Check to make sure it looks like what you expected with

$ git show

As a special shortcut,

$ git commit -a

will update the index with any files that you’ve modified or removed and create a commit, all in one step.

A number of commands are useful for keeping track of what you’re about to commit:

$ git diff --cached # difference between HEAD and the index; what
                    # would be committed if you ran "commit" now.
$ git diff          # difference between the index file and your
                    # working directory; changes that would not
                    # be included if you ran "commit" now.
$ git diff HEAD     # difference between HEAD and working tree; what
                    # would be committed if you ran "commit -a" now.
$ git status        # a brief per-file summary of the above.

You can also use linkgit:git-gui[1] to create commits, view changes in the index and the working tree files, and individually select diff hunks for inclusion in the index (by right-clicking on the diff hunk and choosing “Stage Hunk For Commit”).

Creating good commit messages

Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, linkgit:git-format-patch[1] turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.

Ignoring files

A project will often generate files that you do not want to track with Git. This typically includes files generated by a build process or temporary backup files made by your editor. Of course, not tracking files with Git is just a matter of not calling git add on them. But it quickly becomes annoying to have these untracked files lying around; e.g. they make git add . practically useless, and they keep showing up in the output of git status.

You can tell Git to ignore certain files by creating a file called .gitignore in the top level of your working directory, with contents such as:

# Lines starting with '#' are considered comments.
# Ignore any file named foo.txt.
foo.txt
# Ignore (generated) html files,
*.html
# except foo.html which is maintained by hand.
!foo.html
# Ignore objects and archives.
*.[oa]

See linkgit:gitignore[5] for a detailed explanation of the syntax. You can also place .gitignore files in other directories in your working tree, and they will apply to those directories and their subdirectories. The .gitignore files can be added to your repository like any other files (just run git add .gitignore and git commit, as usual), which is convenient when the exclude patterns (such as patterns matching build output files) would also make sense for other users who clone your repository.

If you wish the exclude patterns to affect only certain repositories (instead of every repository for a given project), you may instead put them in a file in your repository named .git/info/exclude, or in any file specified by the core.excludesFile configuration variable. Some Git commands can also take exclude patterns directly on the command line. See linkgit:gitignore[5] for the details.

How to merge

You can rejoin two diverging branches of development using linkgit:git-merge[1]:

$ git merge branchname

merges the development in the branch branchname into the current branch.

A merge is made by combining the changes made in branchname and the changes made up to the latest commit in your current branch since their histories forked. The work tree is overwritten by the result of the merge when this combining is done cleanly, or overwritten by a half-merged results when this combining results in conflicts. Therefore, if you have uncommitted changes touching the same files as the ones impacted by the merge, Git will refuse to proceed. Most of the time, you will want to commit your changes before you can merge, and if you don’t, then linkgit:git-stash[1] can take these changes away while you’re doing the merge, and reapply them afterwards.

If the changes are independent enough, Git will automatically complete the merge and commit the result (or reuse an existing commit in case of fast-forward, see below). On the other hand, if there are conflicts—for example, if the same file is modified in two different ways in the remote branch and the local branch—then you are warned; the output may look something like this:

$ git merge next
 100% (4/4) done
Auto-merged file.txt
CONFLICT (content): Merge conflict in file.txt
Automatic merge failed; fix conflicts and then commit the result.

Conflict markers are left in the problematic files, and after you resolve the conflicts manually, you can update the index with the contents and run Git commit, as you normally would when creating a new file.

If you examine the resulting commit using gitk, you will see that it has two parents, one pointing to the top of the current branch, and one to the top of the other branch.

Resolving a merge

When a merge isn’t resolved automatically, Git leaves the index and the working tree in a special state that gives you all the information you need to help resolve the merge.

Files with conflicts are marked specially in the index, so until you resolve the problem and update the index, linkgit:git-commit[1] will fail:

$ git commit
file.txt: needs merge

Also, linkgit:git-status[1] will list those files as “unmerged”, and the files with conflicts will have conflict markers added, like this:

<<<<<<< HEAD:file.txt
Hello world
=======
Goodbye
>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt

All you need to do is edit the files to resolve the conflicts, and then

$ git add file.txt
$ git commit

Note that the commit message will already be filled in for you with some information about the merge. Normally you can just use this default message unchanged, but you may add additional commentary of your own if desired.

The above is all you need to know to resolve a simple merge. But Git also provides more information to help resolve conflicts:

Getting conflict-resolution help during a merge

All of the changes that Git was able to merge automatically are already added to the index file, so linkgit:git-diff[1] shows only the conflicts. It uses an unusual syntax:

$ git diff
diff --cc file.txt
index 802992c,2b60207..0000000
--- a/file.txt
+++ b/file.txt
@@@ -1,1 -1,1 +1,5 @@@
++<<<<<<< HEAD:file.txt
 +Hello world
++=======
+ Goodbye
++>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt

Recall that the commit which will be committed after we resolve this conflict will have two parents instead of the usual one: one parent will be HEAD, the tip of the current branch; the other will be the tip of the other branch, which is stored temporarily in MERGE_HEAD.

During the merge, the index holds three versions of each file. Each of these three “file stages” represents a different version of the file:

$ git show :1:file.txt  # the file in a common ancestor of both branches
$ git show :2:file.txt  # the version from HEAD.
$ git show :3:file.txt  # the version from MERGE_HEAD.

When you ask linkgit:git-diff[1] to show the conflicts, it runs a three-way diff between the conflicted merge results in the work tree with stages 2 and 3 to show only hunks whose contents come from both sides, mixed (in other words, when a hunk’s merge results come only from stage 2, that part is not conflicting and is not shown. Same for stage 3).

The diff above shows the differences between the working-tree version of file.txt and the stage 2 and stage 3 versions. So instead of preceding each line by a single + or -, it now uses two columns: the first column is used for differences between the first parent and the working directory copy, and the second for differences between the second parent and the working directory copy. (See the “COMBINED DIFF FORMAT” section of linkgit:git-diff-files[1] for a details of the format.)

After resolving the conflict in the obvious way (but before updating the index), the diff will look like:

$ git diff
diff --cc file.txt
index 802992c,2b60207..0000000
--- a/file.txt
+++ b/file.txt
@@@ -1,1 -1,1 +1,1 @@@
- Hello world
 -Goodbye
++Goodbye world

This shows that our resolved version deleted “Hello world” from the first parent, deleted “Goodbye” from the second parent, and added “Goodbye world”, which was previously absent from both.

Some special diff options allow diffing the working directory against any of these stages:

$ git diff -1 file.txt          # diff against stage 1
$ git diff --base file.txt      # same as the above
$ git diff -2 file.txt          # diff against stage 2
$ git diff --ours file.txt      # same as the above
$ git diff -3 file.txt          # diff against stage 3
$ git diff --theirs file.txt    # same as the above.

The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help for merges:

$ git log --merge
$ gitk --merge

These will display all commits which exist only on HEAD or on MERGE_HEAD, and which touch an unmerged file.

You may also use linkgit:git-mergetool[1], which lets you merge the unmerged files using external tools such as Emacs or kdiff3.

Each time you resolve the conflicts in a file and update the index:

$ git add file.txt

the different stages of that file will be “collapsed”, after which git diff will (by default) no longer show diffs for that file.

Undoing a merge

If you get stuck and decide to just give up and throw the whole mess away, you can always return to the pre-merge state with

$ git reset --hard HEAD

Or, if you’ve already committed the merge that you want to throw away,

$ git reset --hard ORIG_HEAD

However, this last command can be dangerous in some cases—never throw away a commit you have already committed if that commit may itself have been merged into another branch, as doing so may confuse further merges.

Fast-forward merges

There is one special case not mentioned above, which is treated differently. Normally, a merge results in a merge commit, with two parents, one pointing at each of the two lines of development that were merged.

However, if the current branch is an ancestor of the other—so every commit present in the current branch is already contained in the other branch—then Git just performs a “fast-forward”; the head of the current branch is moved forward to point at the head of the merged-in branch, without any new commits being created.

Fixing mistakes

If you’ve messed up the working tree, but haven’t yet committed your mistake, you can return the entire working tree to the last committed state with

$ git reset --hard HEAD

If you make a commit that you later wish you hadn’t, there are two fundamentally different ways to fix the problem:

1. You can create a new commit that undoes whatever was done by the old commit. This is the correct thing if your mistake has already been made public.

2. You can go back and modify the old commit. You should never do this if you have already made the history public; Git does not normally expect the “history” of a project to change, and cannot correctly perform repeated merges from a branch that has had its history changed.

Fixing a mistake with a new commit

Creating a new commit that reverts an earlier change is very easy; just pass the linkgit:git-revert[1] command a reference to the bad commit; for example, to revert the most recent commit:

$ git revert HEAD

This will create a new commit which undoes the change in HEAD. You will be given a chance to edit the commit message for the new commit.

You can also revert an earlier change, for example, the next-to-last:

$ git revert HEAD^

In this case Git will attempt to undo the old change while leaving intact any changes made since then. If more recent changes overlap with the changes to be reverted, then you will be asked to fix conflicts manually, just as in the case of resolving a merge.

Fixing a mistake by rewriting history

If the problematic commit is the most recent commit, and you have not yet made that commit public, then you may just destroy it using git reset.

Alternatively, you can edit the working directory and update the index to fix your mistake, just as if you were going to create a new commit, then run

$ git commit --amend

which will replace the old commit by a new commit incorporating your changes, giving you a chance to edit the old commit message first.

Again, you should never do this to a commit that may already have been merged into another branch; use linkgit:git-revert[1] instead in that case.

It is also possible to replace commits further back in the history, but this is an advanced topic to be left for another chapter.

Checking out an old version of a file

In the process of undoing a previous bad change, you may find it useful to check out an older version of a particular file using linkgit:git-checkout[1]. We’ve used git checkout before to switch branches, but it has quite different behavior if it is given a path name: the command

$ git checkout HEAD^ path/to/file

replaces path/to/file by the contents it had in the commit HEAD^, and also updates the index to match. It does not change branches.

If you just want to look at an old version of the file, without modifying the working directory, you can do that with linkgit:git-show[1]:

$ git show HEAD^:path/to/file

which will display the given version of the file.

Temporarily setting aside work in progress

While you are in the middle of working on something complicated, you find an unrelated but obvious and trivial bug. You would like to fix it before continuing. You can use linkgit:git-stash[1] to save the current state of your work, and after fixing the bug (or, optionally after doing so on a different branch and then coming back), unstash the work-in-progress changes.

$ git stash save "work in progress for foo feature"

This command will save your changes away to the stash, and reset your working tree and the index to match the tip of your current branch. Then you can make your fix as usual.

... edit and test ...
$ git commit -a -m "blorpl: typofix"

After that, you can go back to what you were working on with git stash pop:

$ git stash pop

Ensuring good performance

On large repositories, Git depends on compression to keep the history information from taking up too much space on disk or in memory. Some Git commands may automatically run linkgit:git-gc[1], so you don’t have to worry about running it manually. However, compressing a large repository may take a while, so you may want to call gc explicitly to avoid automatic compression kicking in when it is not convenient.

Ensuring reliability

Checking the repository for corruption

The linkgit:git-fsck[1] command runs a number of self-consistency checks on the repository, and reports on any problems. This may take some time.

$ git fsck
dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
dangling blob 218761f9d90712d37a9c5e36f406f92202db07eb
dangling commit bf093535a34a4d35731aa2bd90fe6b176302f14f
dangling commit 8e4bec7f2ddaa268bef999853c25755452100f8e
dangling tree d50bb86186bf27b681d25af89d3b5b68382e4085
dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
...

You will see informational messages on dangling objects. They are objects that still exist in the repository but are no longer referenced by any of your branches, and can (and will) be removed after a while with gc. You can run git fsck --no-dangling to suppress these messages, and still view real errors.

Recovering lost changes

Reflogs

Say you modify a branch with git reset --hard, and then realize that the branch was the only reference you had to that point in history.

Fortunately, Git also keeps a log, called a “reflog”, of all the previous values of each branch. So in this case you can still find the old history using, for example,

$ git log master@{1}

This lists the commits reachable from the previous version of the master branch head. This syntax can be used with any Git command that accepts a commit, not just with git log. Some other examples:

$ git show master@{2}           # See where the branch pointed 2,
$ git show master@{3}           # 3, ... changes ago.
$ gitk master@{yesterday}       # See where it pointed yesterday,
$ gitk master@{"1 week ago"}    # ... or last week
$ git log --walk-reflogs master # show reflog entries for master

A separate reflog is kept for the HEAD, so

$ git show HEAD@{"1 week ago"}

will show what HEAD pointed to one week ago, not what the current branch pointed to one week ago. This allows you to see the history of what you’ve checked out.

The reflogs are kept by default for 30 days, after which they may be pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn how to control this pruning, and see the “SPECIFYING REVISIONS” section of linkgit:gitrevisions[7] for details.

Note that the reflog history is very different from normal Git history. While normal history is shared by every repository that works on the same project, the reflog history is not shared: it tells you only about how the branches in your local repository have changed over time.

Examining dangling objects

In some situations the reflog may not be able to save you. For example, suppose you delete a branch, then realize you need the history it contained. The reflog is also deleted; however, if you have not yet pruned the repository, then you may still be able to find the lost commits in the dangling objects that git fsck reports. See section_title for the details.

$ git fsck
dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
...

You can examine one of those dangling commits with, for example,

$ gitk 7281251ddd --not --all

which does what it sounds like: it says that you want to see the commit history that is described by the dangling commit(s), but not the history that is described by all your existing branches and tags. Thus you get exactly the history reachable from that commit that is lost. (And notice that it might not be just one commit: we only report the “tip of the line” as being dangling, but there might be a whole deep and complex commit history that was dropped.)

If you decide you want the history back, you can always create a new reference pointing to it, for example, a new branch:

$ git branch recovered-branch 7281251ddd

Other types of dangling objects (blobs and trees) are also possible, and dangling objects can arise in other situations.