Git User's Manual (for version 1.5.3 or newer)

ChapterÂ 1, Repositories and Branches and ChapterÂ 2, Exploring git history explain how to fetch and study a project using gitâread these chapters to learn how to build and test a particular version of a software project, search for @@ -13,15 +13,19 @@ project in mind, here are some interesting examples:

The clone command creates a new directory named after the project ("git" +or "linux-2.6" in the examples above). After you cd into this directory, you will see that it contains a copy of the project files, -together with a special top-level directory named ".git", which -contains all the information about the history of the project.

How to check out a different version of a project

Git is best thought of as a tool for storing the history of a collection +called the working tree, together with a special +top-level directory named ".git", which contains all the information +about the history of the project.

How to check out a different version of a project

Git is best thought of as a tool for storing the history of a collection of files. It stores the history as a compressed collection of interrelated snapshots of the project's contents. In git each such -version is called a commit.

A single git repository may contain multiple branches. It keeps track -of them by keeping a list of heads which reference the +version is called a commit.

Those snapshots aren't necessarily all arranged in a single line from +oldest to newest; instead, work may simultaneously proceed along +parallel lines of development, called <def_branch,branches>>, which may +merge and diverge.

A single git repository can track development on multiple branches. It +does this by keeping a list of heads which reference the latest commit on each branch; the git-branch(1) command shows you the list of branch heads:

$Â gitÂ branch
*Â master

A freshly cloned repository contains a single branch head, by default @@ -387,7 +391,7 @@ file such that it contained the given content either before or after the commit. You can find out with this:

$Â Â gitÂ logÂ --rawÂ --abbrev=40Â --pretty=onelineÂ |
Â Â Â Â Â Â Â Â grepÂ -BÂ 1Â `gitÂ hash-objectÂ filename`

Figuring out why this works is left as an exercise to the (advanced) student. The git-log(1), git-diff-tree(1), and -git-hash-object(1) man pages may prove helpful.

ChapterÂ 3.Â Developing with git

Table of Contents

Telling git your name

Creating a new repository

How to make a commit

Creating good commit messages

Ignoring files

How to merge

Resolving a merge

Getting conflict-resolution help during a merge

Undoing a merge

Fast-forward merges

Fixing mistakes

Fixing a mistake with a new commit
Fixing a mistake by editing history
Checking out an old version of a file
Temporarily setting aside work in progress

Ensuring good performance

Ensuring reliability

Checking the repository for corruption
Recovering lost changes

Telling git your name

Before creating any commits, you should introduce yourself to git. The +git-hash-object(1) man pages may prove helpful.

ChapterÂ 3.Â Developing with git

Table of Contents

Telling git your name

Creating a new repository

How to make a commit

Creating good commit messages

Ignoring files

How to merge

Resolving a merge

Getting conflict-resolution help during a merge

Undoing a merge

Fast-forward merges

Fixing mistakes

Fixing a mistake with a new commit
Fixing a mistake by rewriting history
Checking out an old version of a file
Temporarily setting aside work in progress

Ensuring good performance

Ensuring reliability

Checking the repository for corruption
Recovering lost changes

Telling git your name

Before creating any commits, you should introduce yourself to git. The easiest way to do so is to make sure the following lines appear in a file named .gitconfig in your home directory:

[user]
Â Â Â Â Â Â Â Â nameÂ =Â YourÂ NameÂ ComesÂ Here
@@ -568,14 +572,14 @@ commit; for example, to revert the most recent commit:

$Â 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 editing history

If the problematic commit is the most recent commit, and you have not +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 git-revert(1) instead in -that case.

It is also possible to edit commits further back in the history, but +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 @@ -613,7 +617,10 @@ recovering lost workâsee you wish, you can remove them with git-prune(1) or the âprune option to git-gc(1):

$Â gitÂ gcÂ --prune

This may be time-consuming. Unlike most other git operations (including git-gc when run without any options), it is not safe to prune while -other git operations are in progress in the same repository.

Recovering lost changes

Reflogs

Say you modify a branch with git-reset(1) âhard, and then +other git operations are in progress in the same repository.

If git-fsck(1) complains about sha1 mismatches or missing +objects, you may have a much more serious problem; your best option is +probably restoring from backups. See +the section called âRecovering from repository corruptionâ for a detailed discussion.

Recovering lost changes

Reflogs

Say you modify a branch with git-reset(1) â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 @@ -649,7 +656,7 @@ you get exactly the history reachable from that commit that is lost. "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.

ChapterÂ 4.Â Sharing development with others

Table of Contents

Getting updates with git pull

Submitting patches to a project

Importing patches to a project

Public git repositories

Setting up a public repository
Exporting a git repository via the git protocol
Exporting a git repository via http
Pushing changes to a public repository
Setting up a shared repository
Allowing web browsing of a repository

Examples

Maintaining topic branches for a Linux subsystem maintainer

Getting updates with git pull

After you clone a repository and make a few changes of your own, you +dangling objects can arise in other situations.

ChapterÂ 4.Â Sharing development with others

Table of Contents

Getting updates with git pull

Submitting patches to a project

Importing patches to a project

Public git repositories

Setting up a public repository
Exporting a git repository via the git protocol
Exporting a git repository via http
Pushing changes to a public repository
What to do when a push fails
Setting up a shared repository
Allowing web browsing of a repository

Examples

Maintaining topic branches for a Linux subsystem maintainer

Getting updates with git pull

After you clone a repository and make a few changes of your own, you may wish to check the original repository for updates and merge them into your own work.

We have already seen how to keep remote tracking branches up to date with git-fetch(1), and how to merge two branches. So you can merge in changes from the @@ -744,11 +751,9 @@ maintainers to fetch your latest changes, but they do not allow write access, which you will need to update the public repository with the latest changes created in your private repository.

The simplest way to do this is using git-push(1) and ssh; to update the remote branch named "master" with the latest state of your -branch named "master", run

$Â gitÂ pushÂ ssh://yourserver.com/~you/proj.gitÂ master:master

or just

$Â gitÂ pushÂ ssh://yourserver.com/~you/proj.gitÂ master

As with git-fetch, git-push will complain if this does not result in -a fast forward. Normally this is a sign of -something wrong. However, if you are sure you know what you're -doing, you may force git-push to perform the update anyway by -preceding the branch name by a plus sign:

$Â gitÂ pushÂ ssh://yourserver.com/~you/proj.gitÂ +master

Note that the target of a "push" is normally a +branch named "master", run

$Â gitÂ pushÂ ssh://yourserver.com/~you/proj.gitÂ master:master

or just

$Â gitÂ pushÂ ssh://yourserver.com/~you/proj.gitÂ master

As with git-fetch, git-push will complain if this does not result in a +fast forward; see the following section for details on +handling this case.

Note that the target of a "push" is normally a bare repository. You can also push to a repository that has a checked-out working tree, but the working tree will not be updated by the push. This may lead to unexpected results if @@ -758,7 +763,31 @@ save typing; so, for example, after

$Â catÂ > Â Â Â Â Â Â Â Â urlÂ =Â ssh://yourserver.com/~you/proj.git
EOF

you should be able to perform the above push with just

$Â gitÂ pushÂ public-repoÂ master

See the explanations of the remote.<name>.url, branch.<name>.remote, and remote.<name>.push options in git-config(1) for -details.

Setting up a shared repository

Another way to collaborate is by using a model similar to that +details.

What to do when a push fails

If a push would not result in a fast forward of the +remote branch, then it will fail with an error like:

error:Â remoteÂ 'refs/heads/master'Â isÂ notÂ anÂ ancestorÂ of
+Â localÂ Â 'refs/heads/master'.
+Â MaybeÂ youÂ areÂ notÂ up-to-dateÂ andÂ needÂ toÂ pullÂ first?
+error:Â failedÂ toÂ pushÂ toÂ 'ssh://yourserver.com/~you/proj.git'

This can happen, for example, if you:

+use git reset âhard to remove already-published commits, or +
+use git commit âamend to replace already-published commits + (as in the section called âFixing a mistake by rewriting historyâ), or +
+use git rebase to rebase any already-published commits (as + in the section called âKeeping a patch series up to date using git-rebaseâ). +

You may force git-push to perform the update anyway by preceding the +branch name with a plus sign:

$Â gitÂ pushÂ ssh://yourserver.com/~you/proj.gitÂ +master

Normally whenever a branch head in a public repository is modified, it +is modified to point to a descendent of the commit that it pointed to +before. By forcing a push in this situation, you break that convention. +(See the section called âProblems with rewriting historyâ.)

Nevertheless, this is a common practice for people that need a simple +way to publish a work-in-progress patch series, and it is an acceptable +compromise as long as you warn other developers that this is how you +intend to manage the branch.

It's also possible for a push to fail in this way when other people have +the right to push to the same repository. In that case, the correct +solution is to retry the push after first updating your work by either a +pull or a fetch followed by a rebase; see the +next section and +git for CVS users for more.

Setting up a shared repository

Another way to collaborate is by using a model similar to that commonly used in CVS, where several developers with special rights all push to and pull from a single shared repository. See git for CVS users for instructions on how to @@ -940,7 +969,7 @@ do
Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â Â ;;
Â Â Â Â Â Â Â Â esac
Â Â Â Â Â Â Â Â gitÂ logÂ origin/master..$branchÂ |Â gitÂ shortlog
-done

ChapterÂ 5.Â Rewriting history and maintaining patch series

Table of Contents

Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Rewriting a single commit
Reordering or selecting from a patch series
Other tools
Problems with rewriting history
Why bisecting merge commits can be harder than bisecting linear history

Normally commits are only added to a project, never taken away or replaced. Git is designed with this assumption, and violating it will cause git's merge machinery (for example) to do the wrong thing.

However, there is a situation in which it can be useful to violate this assumption.

Creating the perfect patch series

Suppose you are a contributor to a large project, and you want to add a @@ -989,10 +1018,12 @@ patches to the new mywork. The result will look like:

$Â gitÂ rebaseÂ --continue
and git will continue applying the rest of the patches.
At any point you may use the âabort option to abort this process and
-return mywork to the state it had before you started the rebase:
$Â gitÂ rebaseÂ --abort

Modifying a single commit

We saw in the section called âFixing a mistake by editing historyâ that you can replace the +return mywork to the state it had before you started the rebase:

$Â gitÂ rebaseÂ --abort

Rewriting a single commit

We saw in the section called âFixing a mistake by rewriting historyâ that you can replace the most recent commit using

$Â 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.

You can also use a combination of this and git-rebase(1) to edit -commits further back in your history. First, tag the problematic commit with

$Â gitÂ tagÂ badÂ mywork~5

(Either gitk or git-log may be useful for finding the commit.)

Then check out that commit, edit it, and rebase the rest of the series +changes, giving you a chance to edit the old commit message first.

You can also use a combination of this and git-rebase(1) to +replace a commit further back in your history and recreate the +intervening changes on top of it. First, tag the problematic commit +with

$Â gitÂ tagÂ badÂ mywork~5

(Either gitk or git-log may be useful for finding the commit.)

Then check out that commit, edit it, and rebase the rest of the series on top of it (note that we could check out the commit on a temporary branch, but instead we're using a detached head):

$Â gitÂ checkoutÂ bad
$Â #Â makeÂ changesÂ hereÂ andÂ updateÂ theÂ index
@@ -1116,7 +1147,7 @@ $Â gitÂ fetchÂ example

You can also add a "+" to force the update ea throwing away commits on mybranch.

Also note that all of the above configuration can be performed by directly editing the file .git/config instead of using git-config(1).

See git-config(1) for more details on the configuration -options mentioned above.

Recovering from repository corruption

By design, git treats data trusted to it with caution. However, even in +the absence of bugs in git itself, it is still possible that hardware or +operating system errors could corrupt data.

The first defense against such problems is backups. You can back up a +git directory using clone, or just using cp, tar, or any other backup +mechanism.

As a last resort, you can search for the corrupted objects and attempt +to replace them by hand. Back up your repository before attempting this +in case you corrupt things even more in the process.

We'll assume that the problem is a single missing or corrupted blob, +which is sometimes a solveable problem. (Recovering missing trees and +especially commits is much harder).

Before starting, verify that there is corruption, and figure out where +it is with git-fsck(1); this may be time-consuming.

Assume the output looks like this:

$Â git-fsckÂ --full
+brokenÂ linkÂ fromÂ Â Â Â treeÂ 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
+Â Â Â Â Â Â Â Â Â Â Â Â Â Â toÂ Â Â Â blobÂ 4b9458b3786228369c63936db65827de3cc06200
+missingÂ blobÂ 4b9458b3786228369c63936db65827de3cc06200

(Typically there will be some "dangling object" messages too, but they +aren't interesting.)

Now you know that blob 4b9458b3 is missing, and that the tree 2d9263c6 +points to it. If you could find just one copy of that missing blob +object, possibly in some other repository, you could move it into +.git/objects/4b/9458b3â¦ and be done. Suppose you can't. You can +still examine the tree that pointed to it with git-ls-tree(1), +which might output something like:

$Â gitÂ ls-treeÂ 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
+100644Â blobÂ 8d14531846b95bfa3564b58ccfb7913a034323b8Â Â Â Â .gitignore
+100644Â blobÂ ebf9bf84da0aab5ed944264a5db2a65fe3a3e883Â Â Â Â .mailmap
+100644Â blobÂ ca442d313d86dc67e0a2e5d584b465bd382cbf5cÂ Â Â Â COPYING
+...
+100644Â blobÂ 4b9458b3786228369c63936db65827de3cc06200Â Â Â Â myfile
+...

So now you know that the missing blob was the data for a file named +"myfile". And chances are you can also identify the directoryâlet's +say it's in "somedirectory". If you're lucky the missing copy might be +the same as the copy you have checked out in your working tree at +"somedirectory/myfile"; you can test whether that's right with +git-hash-object(1):

$Â gitÂ hash-objectÂ -wÂ somedirectory/myfile

which will create and store a blob object with the contents of +somedirectory/myfile, and output the sha1 of that object. if you're +extremely lucky it might be 4b9458b3786228369c63936db65827de3cc06200, in +which case you've guessed right, and the corruption is fixed!

Otherwise, you need more information. How do you tell which version of +the file has been lost?

The easiest way to do this is with:

$Â gitÂ logÂ --rawÂ --allÂ --full-historyÂ --Â somedirectory/myfile

Because you're asking for raw output, you'll now get something like

commitÂ abc
+Author:
+Date:
+...
+:100644Â 100644Â 4b9458b...Â newsha...Â MÂ somedirectory/myfile
+
+
+commitÂ xyz
+Author:
+Date:
+
+...
+:100644Â 100644Â oldsha...Â 4b9458b...Â MÂ somedirectory/myfile

This tells you that the immediately preceding version of the file was +"newsha", and that the immediately following version was "oldsha". +You also know the commit messages that went with the change from oldsha +to 4b9458b and with the change from 4b9458b to newsha.

If you've been committing small enough changes, you may now have a good +shot at reconstructing the contents of the in-between state 4b9458b.

If you can do that, you can now recreate the missing object with

$Â gitÂ hash-objectÂ -wÂ <recreated-file>

and your repository is good again!

(Btw, you could have ignored the fsck, and started with doing a

$Â gitÂ logÂ --rawÂ --all

and just looked for the sha of the missing object (4b9458b..) in that +whole thing. It's up to you - git does have a lot of information, it is +just missing one particular blob version.

You have to run git submodule update after git pull if you want to update -submodules, too.

Pitfalls with submodules

Always publish the submodule change before publishing the change to the +submodules, too.

Pitfalls with submodules

Always publish the submodule change before publishing the change to the superproject that references it. If you forget to publish the submodule change, others won't be able to clone the repository:

$Â cdÂ ~/git/super/a
$Â echoÂ iÂ addedÂ anotherÂ lineÂ toÂ thisÂ fileÂ >>Â a.txt
@@ -2386,4 +2468,7 @@ temporary branch creation?

Add more good examples. Entire sections of jus might be a good idea; maybe make an "advanced examples" section a standard end-of-chapter section?

Include cross-references to the glossary, where appropriate.

Document shallow clones? See draft 1.5.0 release notes for some documentation.

Add a section on working with other version control systems, including -CVS, Subversion, and just imports of series of release tarballs.

More details on gitweb?

Write a chapter on using plumbing and writing scripts.

Alternates, clone -reference, etc.

git unpack-objects -r for recovery

+CVS, Subversion, and just imports of series of release tarballs.

More details on gitweb?

Write a chapter on using plumbing and writing scripts.

Alternates, clone -reference, etc.

More on recovery from repository corruption. See: + http://marc.theaimsgroup.com/?l=git&m=117263864820799&w=2 + http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2 + http://marc.theaimsgroup.com/?l=git&m=117147855503798&w=2

Git User's Manual (for version 1.5.3 or newer)

Preface

Git User's Manual (for version 1.5.3 or newer)

Preface

How to check out a different version of a project

How to check out a different version of a project

ChapterÂ 3.Â Developing with git

Telling git your name

ChapterÂ 3.Â Developing with git

Telling git your name

Fixing a mistake by editing history

Fixing a mistake by rewriting history

Checking out an old version of a file

Recovering lost changes

Reflogs

Recovering lost changes

Reflogs

ChapterÂ 4.Â Sharing development with others

Getting updates with git pull

ChapterÂ 4.Â Sharing development with others

Getting updates with git pull

Setting up a shared repository

What to do when a push fails

Setting up a shared repository

ChapterÂ 5.Â Rewriting history and maintaining patch series

ChapterÂ 5.Â Rewriting history and maintaining patch series

Creating the perfect patch series

Modifying a single commit

Rewriting a single commit

ChapterÂ 7.Â Git concepts

ChapterÂ 7.Â Git concepts

The Object Database

The index

Recovering from repository corruption

The index

ChapterÂ 8.Â Submodules

ChapterÂ 8.Â Submodules

Pitfalls with submodules

Pitfalls with submodules