Git User's Manual

working directory -> index
index -> object database
object database -> index
index -> working directory
Tying it all together

9. Glossary of git terms

10. Notes and todo list for this manual

Preface

This manual is designed to be readable by someone with basic unix +Git User's Manual

Git User's Manual

Table of Contents

Preface

1. Git Quick Start

Creating a new repository
Managing branches
Exploring history
Making changes
Merging
Sharing your changes
Repository maintenance

2. Repositories and Branches

How to get a git repository

How to check out a different version of a project

Understanding History: Commits

Understanding history: commits, parents, and reachability
Undestanding history: History diagrams
Understanding history: What is a branch?

Manipulating branches

Examining branches from a remote repository

Naming branches, tags, and other references

Updating a repository with git fetch

Fetching branches from other repositories

3. Exploring git history

How to use bisect to find a regression

Naming commits

Creating tags

Browsing revisions

Generating diffs

Viewing old file versions

Examples

Check whether two branches point at the same history
Find first tagged version including a given fix

4. Developing with git

Telling git your name

Creating a new repository

how to make a commit

creating good commit messages

how to merge

Resolving 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

Ensuring good performance

Ensuring reliability

Checking the repository for corruption
Recovering lost changes

5. Sharing development with others

Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Setting up a public repository
Exporting a git repository via http
Exporting a git repository via the git protocol
Pushing changes to a public repository
Setting up a shared repository
Allow web browsing of a repository
Examples

6. Rewriting history and maintaining patch series

Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Reordering or selecting from a patch series
Other tools
Problems with rewriting history

7. Advanced branch management

Fetching individual branches
Understanding git history: fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches

8. Git internals

working directory -> index
index -> object database
object database -> index
index -> working directory
Tying it all together

9. Glossary of git terms

10. Notes and todo list for this manual

Preface

This manual is designed to be readable by someone with basic unix commandline skills, but no previous knowledge of git.

Chapter 1 gives a brief overview of git commands, without any explanation; you may prefer to skip to chapter 2 on a first reading.

Chapters 2 and 3 explain how to fetch and study a project using git—the tools you'd need to build and test a particular version of a @@ -154,7 +154,7 @@ branch name, but this longer name can also be useful. Most importantly, it is a globally unique name for this commit: so if you tell somebody else the object name (for example in email), then you are guaranteed that name will refer to the same commit in their repository -that you it does in yours (assuming their repository has that commit at +that it does in yours (assuming their repository has that commit at all).

Understanding history: commits, parents, and reachability

Every commit (except the very first commit in a project) also has a parent commit which shows what happened before this commit. Following the chain of parents will eventually take you back to the @@ -280,7 +280,7 @@ text editor. (See the "CONFIGURATION FILE" section of collection of files. It does this by storing compressed snapshots of the contents of a file heirarchy, together with "commits" which show the relationships between these snapshots.

Git provides extremely flexible and fast tools for exploring the -history of a project.

We start with one specialized tool which is useful for finding the +history of a project.

We start with one specialized tool that is useful for finding the commit that introduced a bug into a project.

How to use bisect to find a regression

Suppose version 2.6.18 of your project worked, but the version at "master" crashes. Sometimes the best way to find the cause of such a regression is to perform a brute-force search through the project's @@ -596,7 +596,7 @@ the lost commits; run git-fsck and watch for output that mentions dangling commit 7281251ddd2a61e38657c827739c57015671a6b3
dangling commit 2706a059f258c6b245f298dc4ff2ccd30ec21a63
dangling commit 13472b7c4b80851a1bc551779171dcb03655e9b5
-...

and watch for output that mentions "dangling commits". You can examine +...

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 @@ -604,7 +604,7 @@ 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 gotten 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

Chapter 5. Sharing development with others

Table of Contents

Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Setting up a public repository
Exporting a git repository via http
Exporting a git repository via the git protocol
Pushing changes to a public repository
Setting up a shared repository
Allow web browsing of a repository
Examples

Getting updates with git pull

After you clone a repository and make a few changes of your own, you +reference pointing to it, for example, a new branch:

$ git branch recovered-branch 7281251ddd

Chapter 5. Sharing development with others

Table of Contents

Getting updates with git pull
Submitting patches to a project
Importing patches to a project
Setting up a public repository
Exporting a git repository via http
Exporting a git repository via the git protocol
Pushing changes to a public repository
Setting up a shared repository
Allow web browsing of a repository
Examples

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 @@ -621,13 +621,13 @@ repository that you pulled from.

(But note that no such commit will be cre updated to point to the latest commit from the upstream branch).

The git-pull command can also be given "." as the "remote" repository, in which case it just merges in a branch from the current repository; so the commands

$ git pull . branch
-$ git merge branch

are roughly equivalent. The former is actually very commonly used.

Submitting patches to a project

If you just have a few changes, the simplest way to submit them may +$ git merge branch

are roughly equivalent. The former is actually very commonly used.

Submitting patches to a project

If you just have a few changes, the simplest way to submit them may just be to send them as patches in email:

First, use git-format-patch(1); for example:

$ git format-patch origin

will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD.

You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the git-send-email(1) script to automate the process. Consult the mailing list for your project first to determine how they -prefer such patches be handled.

Importing patches to a project

Git also provides a tool called git-am(1) (am stands for +prefer such patches be handled.

Importing patches to a project

Git also provides a tool called git-am(1) (am stands for "apply mailbox"), for importing such an emailed series of patches. Just save all of the patch-containing messages, in order, into a single mailbox file, say "patches.mbox", then run

$ git am -3 patches.mbox

Git will apply each patch in order; if any conflicts are found, it @@ -699,16 +699,16 @@ save typing; so, for example, after

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

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 -set this up.

Allow web browsing of a repository

The gitweb cgi script provides users an easy way to browse your +set this up.

Allow web browsing of a repository

The gitweb cgi script provides users an easy way to browse your project's files and history without having to install git; see the file -gitweb/README in the git source tree for instructions on setting it up.

Examples

TODO: topic branches, typical roles as in everyday.txt, ?

Chapter 6. Rewriting history and maintaining patch series

Table of Contents

Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Reordering or selecting from a patch series
Other tools
Problems with rewriting history

Normally commits are only added to a project, never taken away or +gitweb/README in the git source tree for instructions on setting it up.

Examples

TODO: topic branches, typical roles as in everyday.txt, ?

Chapter 6. Rewriting history and maintaining patch series

Table of Contents

Creating the perfect patch series
Keeping a patch series up to date using git-rebase
Reordering or selecting from a patch series
Other tools
Problems with rewriting 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 +assumption.

Creating the perfect patch series

Suppose you are a contributor to a large project, and you want to add a complicated feature, and to present it to the other developers in a way that makes it easy for them to read your changes, verify that they are correct, and understand why you made each change.

If you present all of your changes as a single patch (or commit), they @@ -727,7 +727,7 @@ The complete series produces the same end result as your own (probably much messier!) development process did.

We will introduce some tools that can help you do this, explain how to use them, and then explain some of the problems that can arise because -you are rewriting history.

Keeping a patch series up to date using git-rebase

Suppose you have a series of commits in a branch "mywork", which +you are rewriting history.

Keeping a patch series up to date using git-rebase

Suppose you have a series of commits in a branch "mywork", which originally branched off from "origin".

Suppose you create a branch "mywork" on a remote-tracking branch "origin", and created some commits on top of it:

$ git checkout -b mywork origin
$ vi file.txt
@@ -751,7 +751,7 @@ 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

Reordering or selecting from a patch series

Given one existing commit, the git-cherry-pick(1) command +return mywork to the state it had before you started the rebase:

$ git rebase --abort

Reordering or selecting from a patch series

Given one existing commit, the git-cherry-pick(1) command allows you to apply the change introduced by that commit and create a new commit that records it. So, for example, if "mywork" points to a series of patches on top of "origin", you might do something like:

$ git checkout -b mywork-new origin
@@ -761,9 +761,9 @@ cherry-pick, and possibly modifying them as you go using commit —amend.

Another technique is to use git-format-patch to create a series of patches, then reset the state to before the patches:

$ git format-patch origin
$ git reset --hard origin

Then modify, reorder, or eliminate patches as preferred before applying -them again with git-am(1).

Other tools

There are numerous other tools, such as stgit, which exist for the +them again with git-am(1).

Other tools

There are numerous other tools, such as stgit, which exist for the purpose of maintaining a patch series. These are out of the scope of -this manual.

Problems with rewriting history

The primary problem with rewriting the history of a branch has to do +this manual.

Problems with rewriting history

The primary problem with rewriting the history of a branch has to do with merging. Suppose somebody fetches your branch and merges it into their branch, with a result something like this:

o--o--O--o--o--o <-- origin
        \                 t--t--t--m <-- their branch:

Then suppose you modify the last three commits:

        o--o--o <-- new head of origin
@@ -782,7 +782,7 @@ new.  The results are likely to be unexpected.
You may still choose to pub
 and it may be useful for others to be able to fetch those branches in
 order to examine or test them, but they should not attempt to pull such
 branches into their own work.
For true distributed development that supports proper merging,
-published branches should never be rewritten.

Chapter 7. Advanced branch management

Table of Contents

Fetching individual branches
Understanding git history: fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches

Fetching individual branches

Instead of using git-remote(1), you can also choose just +published branches should never be rewritten.

Chapter 7. Advanced branch management

Table of Contents

Fetching individual branches
Understanding git history: fast-forwards
Forcing git fetch to do non-fast-forward updates
Configuring remote branches

Fetching individual branches

Instead of using git-remote(1), you can also choose just to update one branch at a time, and to store it locally under an arbitrary name:

$ git fetch origin todo:my-todo-work

The first argument, "origin", just tells git to fetch from the repository you originally cloned from. The second argument tells git @@ -804,10 +804,10 @@ resulting in a situation like:

o--o--o--o--a--b &l described in the following section. However, note that in the situation above this may mean losing the commits labeled "a" and "b", unless you've already created a reference of your own pointing to -them.

Forcing git fetch to do non-fast-forward updates

If git fetch fails because the new head of a branch is not a +them.

Forcing git fetch to do non-fast-forward updates

If git fetch fails because the new head of a branch is not a descendant of the old head, you may force the update with:

$ git fetch git://example.com/proj.git +master:refs/remotes/example/master

Note the addition of the "+" sign. Be aware that commits which the old version of example/master pointed at may be lost, as we saw in -the previous section.

Configuring remote branches

We saw above that "origin" is just a shortcut to refer to the +the previous section.

Configuring remote branches

We saw above that "origin" is just a shortcut to refer to the repository which you originally cloned from. This information is stored in git configuration variables, which you can see using git-config(1):

$ git config -l
@@ -827,8 +827,8 @@ $ 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.

Chapter 8. Git internals

Table of Contents

working directory -> index
index -> object database
object database -> index
index -> working directory
Tying it all together

There are two object abstractions: the "object database", and the -"current directory cache" aka "index".

The Object Database

The object database is literally just a content-addressable collection +options mentioned above.

Chapter 8. Git internals

Table of Contents

working directory -> index
index -> object database
object database -> index
index -> working directory
Tying it all together