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

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 -software project, to search for regressions, and so on.

Chapter 4 explains how to do development with git, and chapter 5 how -to share that development with others.

Further chapters cover more specialized topics.

Comprehensive reference documentation is available through the man -pages. For a command such as "git clone", just use

$ man git-clone

Chapter 1. Git Quick Start

Table of Contents

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

This is a quick summary of the major commands; the following chapters -will explain how these work in more detail.

Creating a new repository

From a tarball:

$ tar xzf project.tar.gz
-$ cd project
-$ git init
-Initialized empty Git repository in .git/
-$ git add .
-$ git commit

From a remote repository:

$ git clone git://example.com/pub/project.git
-$ cd project

Managing branches

$ git branch         # list all local branches in this repo
-$ git checkout test  # switch working directory to branch "test"
-$ git branch new     # create branch "new" starting at current HEAD
-$ git branch -d new  # delete branch "new"

Instead of basing new branch on current HEAD (the default), use:

$ git branch new test    # branch named "test"
-$ git branch new v2.6.15 # tag named v2.6.15
-$ git branch new HEAD^   # commit before the most recent
-$ git branch new HEAD^^  # commit before that
-$ git branch new test~10 # ten commits before tip of branch "test"

Create and switch to a new branch at the same time:

$ git checkout -b new v2.6.15

Update and examine branches from the repository you cloned from:

$ git fetch             # update
-$ git branch -r         # list
-  origin/master
-  origin/next
-  ...
-$ git checkout -b masterwork origin/master

Fetch a branch from a different repository, and give it a new -name in your repository:

$ git fetch git://example.com/project.git theirbranch:mybranch
-$ git fetch git://example.com/project.git v2.6.15:mybranch

Keep a list of repositories you work with regularly:

$ git remote add example git://example.com/project.git
-$ git remote                    # list remote repositories
-example
-origin
-$ git remote show example       # get details
-* remote example
-  URL: git://example.com/project.git
-  Tracked remote branches
-    master next ...
-$ git fetch example             # update branches from example
-$ git branch -r                 # list all remote branches

Exploring history

$ gitk                      # visualize and browse history
-$ git log                   # list all commits
-$ git log src/              # ...modifying src/
-$ git log v2.6.15..v2.6.16  # ...in v2.6.16, not in v2.6.15
-$ git log master..test      # ...in branch test, not in branch master
-$ git log test..master      # ...in branch master, but not in test
-$ git log test...master     # ...in one branch, not in both
-$ git log -S'foo()'         # ...where difference contain "foo()"
-$ git log --since="2 weeks ago"
-$ git log -p                # show patches as well
-$ git show                  # most recent commit
-$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
-$ git diff v2.6.15..HEAD    # diff with current head
-$ git grep "foo()"          # search working directory for "foo()"
-$ git grep v2.6.15 "foo()"  # search old tree for "foo()"
-$ git show v2.6.15:a.txt    # look at old version of a.txt

Search for regressions:

$ git bisect start
-$ git bisect bad                # current version is bad
-$ git bisect good v2.6.13-rc2   # last known good revision
-Bisecting: 675 revisions left to test after this
-                                # test here, then:
-$ git bisect good               # if this revision is good, or
-$ git bisect bad                # if this revision is bad.
-                                # repeat until done.

Making changes

Make sure git knows who to blame:

$ cat >>~/.gitconfig <<\EOF
-[user]
- name = Your Name Comes Here
- email = you@yourdomain.example.com
-EOF

Select file contents to include in the next commit, then make the -commit:

$ git add a.txt    # updated file
-$ git add b.txt    # new file
-$ git rm c.txt     # old file
-$ git commit

Or, prepare and create the commit in one step:

$ git commit d.txt # use latest content only of d.txt
-$ git commit -a # use latest content of all tracked files

Merging

$ git merge test   # merge branch "test" into the current branch
-$ git pull git://example.com/project.git master
-                   # fetch and merge in remote branch
-$ git pull . test  # equivalent to git merge test

Sharing your changes

Importing or exporting patches:

$ git format-patch origin..HEAD # format a patch for each commit
- # in HEAD but not in origin
-$ git am mbox # import patches from the mailbox "mbox"

Fetch a branch in a different git repository, then merge into the -current branch:

$ git pull git://example.com/project.git theirbranch

Store the fetched branch into a local branch before merging into the -current branch:

$ git pull git://example.com/project.git theirbranch:mybranch

After creating commits on a local branch, update the remote -branch with your commits:

$ git push ssh://example.com/project.git mybranch:theirbranch

When remote and local branch are both named "test":

$ git push ssh://example.com/project.git test

Shortcut version for a frequently used remote repository:

$ git remote add example ssh://example.com/project.git
-$ git push example test

Repository maintenance

Check for corruption:

$ git fsck

Recompress, remove unused cruft:

$ git gc

Chapter 2. Repositories and Branches

Table of Contents

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
Understanding history: History diagrams
Understanding history: What is a branch?

Manipulating branches

Examining an old version without creating a new branch

Examining branches from a remote repository

Naming branches, tags, and other references

Updating a repository with git fetch

Fetching branches from other repositories

How to get a git repository

It will be useful to have a git repository to experiment with as you +Git User's Manual (for version 1.5.1 or newer)

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

Table of Contents

Preface

1. 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
Understanding history: History diagrams
Understanding history: What is a branch?

Manipulating branches

Examining an old version without creating a new branch

Examining branches from a remote repository

Naming branches, tags, and other references

Updating a repository with git fetch

Fetching branches from other repositories

2. Exploring git history

How to use bisect to find a regression

Naming commits

Creating tags

Browsing revisions

Generating diffs

Viewing old file versions

Examples

Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release

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

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

Ensuring good performance

Ensuring reliability

Checking the repository for corruption
Recovering lost changes

4. Sharing development with others

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

5. Rewriting history and maintaining patch series

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

6. Advanced branch management

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

7. Git internals

The Object Database

The "index" aka "Current Directory Cache"

The Workflow

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

Examining the data

Merging multiple trees

Merging multiple trees, continued

How git stores objects efficiently: pack files

Dangling objects

A birds-eye view of Git's source code

8. GIT Glossary

A. Git Quick Start

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

B. Notes and todo list for this manual

Preface

Git is a fast distributed revision control system.

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

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 +regressions, and so on.

People needing to do actual development will also want to read +Chapter 3, Developing with git and Chapter 4, Sharing development with others.

Further chapters cover more specialized topics.

Comprehensive reference documentation is available through the man +pages. For a command such as "git clone", just use

$ man git-clone

See also Appendix A, Git Quick Start for a brief overview of git commands, +without any explanation.

Also, see Appendix B, Notes and todo list for this manual for ways that you can help make this manual more +complete.

Chapter 1. Repositories and Branches

Table of Contents

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
Understanding history: History diagrams
Understanding history: What is a branch?

Manipulating branches

Examining an old version without creating a new branch

Examining branches from a remote repository

Naming branches, tags, and other references

Updating a repository with git fetch

Fetching branches from other repositories

How to get a git repository

It will be useful to have a git repository to experiment with as you read this manual.

The best way to get one is by using the git-clone(1) command to download a copy of an existing repository for a project that you are interested in. If you don't already have a project in mind, here @@ -157,7 +88,7 @@ example in email), then you are guaranteed that name will refer to the same commit in their repository that it does in yours (assuming their repository has that commit at all). Since the object name is computed as a hash over the contents of the commit, you are guaranteed that the commit can never change -without its name also changing.

In fact, in Chapter 8, Git internals we shall see that everything stored in git +without its name also changing.

In fact, in Chapter 7, Git internals we shall see that everything stored in git history, including file data and directory contents, is stored in an object with a name that is a hash of its contents.

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. @@ -293,7 +224,7 @@ a new stanza:

$ ...

This is what causes git to track the remote's branches; you may modify or delete these configuration options by editing .git/config with a text editor. (See the "CONFIGURATION FILE" section of -git-config(1) for details.)

Chapter 3. Exploring git history

Table of Contents

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

Git is best thought of as a tool for storing the history of a +git-config(1) for details.)

Chapter 2. Exploring git history

Table of Contents

How to use bisect to find a regression

Naming commits

Creating tags

Browsing revisions

Generating diffs

Viewing old file versions

Examples

Counting the number of commits on a branch
Check whether two branches point at the same history
Find first tagged version including a given fix
Showing commits unique to a given branch
Creating a changelog and tarball for a software release

Git is best thought of as a tool for storing the history of a 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 @@ -384,7 +315,10 @@ will not be the same as the diff produced by the git-diff example.

$ git show v2.5:fs/locks.c

Before the colon may be anything that names a commit, and after it -may be any path to a file tracked by git.

Examples

Check whether two branches point at the same history

Suppose you want to check whether two branches point at the same point +may be any path to a file tracked by git.

Examples

Counting the number of commits on a branch

Suppose you want to know how many commits you've made on "mybranch" +since it diverged from "origin":

$ git log --pretty=oneline origin..mybranch | wc -l

Alternatively, you may often see this sort of thing done with the +lower-level command git-rev-list(1), which just lists the SHA1's +of all the given commits:

$ git rev-list origin..mybranch | wc -l

Check whether two branches point at the same history

Suppose you want to check whether two branches point at the same point in history.

$ git diff origin..master

will tell you whether the contents of the project are the same at the two branches; in theory, however, it's possible that the same project contents could have been arrived at by two different historical @@ -420,7 +354,38 @@ available
! [v1.5.0-rc2] GIT v1.5.0-rc2
...

then search for a line that looks like

+ ++ [e05db0fd] Fix warnings in sha1_file.c - use C99 printf format if
available

Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and -from v1.5.0-rc2, but not from v1.5.0-rc0.

Chapter 4. Developing with git

Table of Contents

Telling git your name

Creating a new repository

How to make a commit

Creating good commit messages

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

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 +from v1.5.0-rc2, but not from v1.5.0-rc0.

Showing commits unique to a given branch

Suppose you would like to see all the commits reachable from the branch +head named "master" but not from any other head in your repository.

We can list all the heads in this repository with +git-show-ref(1):

$ git show-ref --heads
+bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial
+db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint
+a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master
+24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2
+1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes

We can get just the branch-head names, and remove "master", with +the help of the standard utilities cut and grep:

$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master'
+refs/heads/core-tutorial
+refs/heads/maint
+refs/heads/tutorial-2
+refs/heads/tutorial-fixes

And then we can ask to see all the commits reachable from master +but not from these other heads:

$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 |
+ grep -v '^refs/heads/master' )

Obviously, endless variations are possible; for example, to see all +commits reachable from some head but not from any tag in the repository:

$ gitk ($ git show-ref --heads ) --not $( git show-ref --tags )

(See git-rev-parse(1) for explanations of commit-selecting +syntax such as —not.)

Creating a changelog and tarball for a software release

The git-archive(1) command can create a tar or zip archive from +any version of a project; for example:

$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz

will use HEAD to produce a tar archive in which each filename is +preceded by "prefix/".

If you're releasing a new version of a software project, you may want +to simultaneously make a changelog to include in the release +announcement.

Linus Torvalds, for example, makes new kernel releases by tagging them, +then running:

$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7

where release-script is a shell script that looks like:

#!/bin/sh
+stable="$1"
+last="$2"
+new="$3"
+echo "# git tag v$new"
+echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz"
+echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz"
+echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new"
+echo "git shortlog --no-merges v$new ^v$last > ../ShortLog"
+echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"

and then he just cut-and-pastes the output commands after verifying that +they look OK.

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

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

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
@@ -581,7 +546,7 @@ changes, giving you a chance to edit the old commit message first.

Again, 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 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 +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 git-checkout(1). We've used git checkout before to switch branches, but it has quite different behavior if it is given a path @@ -644,7 +609,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 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 +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 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 @@ -681,18 +646,17 @@ leave your tree and index untouched, you may omit that option.)

Once the i resolution, instead of creating a new commit, just run

$ git am --resolved

and git will create the commit for you and continue applying the remaining patches from the mailbox.

The final result will be a series of commits, one for each patch in the original mailbox, with authorship and commit log message each -taken from the message containing each patch.

Setting up a public repository

Another way to submit changes to a project is to simply tell the -maintainer of that project to pull from your repository, exactly as -you did in the section "Getting updates with git pull".

If you and maintainer both have accounts on the same machine, then -then you can just pull changes from each other's repositories -directly; note that all of the commands (git-clone(1), -git-fetch[1], git-pull[1], etc.) that accept a URL as an argument -will also accept a local directory name; so, for example, you can -use

$ git clone /path/to/repository
-$ git pull /path/to/other/repository

If this sort of setup is inconvenient or impossible, another (more -common) option is to set up a public repository on a public server. -This also allows you to cleanly separate private work in progress -from publicly visible work.

You will continue to do your day-to-day work in your personal +taken from the message containing each patch.

Public git repositories

Another way to submit changes to a project is to tell the maintainer of +that project to pull the changes from your repository using git-pull[1]. +In the section "Getting updates with git pull" we described this as a way to get updates from the "main" +repository, but it works just as well in the other direction.

If you and the maintainer both have accounts on the same machine, then +you can just pull changes from each other's repositories directly; +commands that accepts repository URLs as arguments will also accept a +local directory name:

$ git clone /path/to/repository
+$ git pull /path/to/other/repository

However, the more common way to do this is to maintain a separate public +repository (usually on a different host) for others to pull changes +from. This is usually more convenient, and allows you to cleanly +separate private work in progress from publicly visible work.

You will continue to do your day-to-day work in your personal repository, but periodically "push" changes from your personal repository into your public repository, allowing other developers to pull from that repository. So the flow of changes, in a situation @@ -705,15 +669,23 @@ your personal repo ------------------> your public repo | | | | | they push V -their public repo <------------------- their repo

Now, assume your personal repository is in the directory ~/proj. We -first create a new clone of the repository:

$ git clone --bare ~/proj proj.git

The resulting directory proj.git contains a "bare" git repository—it is -just the contents of the ".git" directory, without a checked-out copy of -a working directory.

Next, copy proj.git to the server where you plan to host the +their public repo <------------------- their repo

Setting up a public repository

Assume your personal repository is in the directory ~/proj. We +first create a new clone of the repository and tell git-daemon that it +is meant to be public:

$ git clone --bare ~/proj proj.git
+$ touch proj.git/git-daemon-export-ok

The resulting directory proj.git contains a "bare" git repository—it is +just the contents of the ".git" directory, without any files checked out +around it.

Next, copy proj.git to the server where you plan to host the public repository. You can use scp, rsync, or whatever is most -convenient.

If somebody else maintains the public server, they may already have -set up a git service for you, and you may skip to the section -"Pushing changes to a public repository", below.

Otherwise, the following sections explain how to export your newly -created public repository:

Exporting a git repository via http

The git protocol gives better performance and reliability, but on a +convenient.

Exporting a git repository via the git protocol

This is the preferred method.

If someone else administers the server, they should tell you what +directory to put the repository in, and what git:// url it will appear +at. You can then skip to the section +"Pushing changes to a public repository", below.

Otherwise, all you need to do is start git-daemon(1); it will +listen on port 9418. By default, it will allow access to any directory +that looks like a git directory and contains the magic file +git-daemon-export-ok. Passing some directory paths as git-daemon +arguments will further restrict the exports to those paths.

You can also run git-daemon as an inetd service; see the +git-daemon(1) man page for details. (See especially the +examples section.)

Exporting a git repository via http

The git protocol gives better performance and reliability, but on a host with a web server set up, http exports may be simpler to set up.

All you need to do is place the newly created bare git repository in a directory that is exported by the web server, and make some adjustments to give web clients some extra information they need:

$ mv proj.git /home/you/public_html/proj.git
@@ -725,8 +697,7 @@ $ clone or pull from that url, for example with a commandline like:

$ git clone http://yourserver.com/~you/proj.git

(See also setup-git-server-over-http for a slightly more sophisticated setup using WebDAV which also -allows pushing over http.)

Exporting a git repository via the git protocol

This is the preferred method.

For now, we refer you to the git-daemon(1) man page for -instructions. (See especially the examples section.)

Pushing changes to a public repository

Note that the two techniques outline above (exporting via +allows pushing over http.)

Pushing changes to a public repository

Note that the two techniques outlined above (exporting via http or git) allow other maintainers to fetch your latest changes, but they do not allow write access, which you will need to update the public repository with the @@ -742,13 +713,168 @@ 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.

Allowing 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/INSTALL 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
Modifying a single commit
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/INSTALL in the git source tree for instructions on setting it up.

Examples

Maintaining topic branches for a Linux subsystem maintainer

This describes how Tony Luck uses git in his role as maintainer of the +IA64 architecture for the Linux kernel.

He uses two public branches:

+A "test" tree into which patches are initially placed so that they + can get some exposure when integrated with other ongoing development. + This tree is available to Andrew for pulling into -mm whenever he + wants. +
+A "release" tree into which tested patches are moved for final sanity + checking, and as a vehicle to send them upstream to Linus (by sending + him a "please pull" request.) +

He also uses a set of temporary branches ("topic branches"), each +containing a logical grouping of patches.

To set this up, first create your work tree by cloning Linus's public +tree:

$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work
+$ cd work

Linus's tree will be stored in the remote branch named origin/master, +and can be updated using git-fetch(1); you can track other +public trees using git-remote(1) to set up a "remote" and +git-fetch[1] to keep them up-to-date; see Chapter 1, Repositories and Branches.

Now create the branches in which you are going to work; these start out +at the current tip of origin/master branch, and should be set up (using +the —track option to git-branch(1)) to merge changes in from +Linus by default.

$ git branch --track test origin/master
+$ git branch --track release origin/master

These can be easily kept up to date using git-pull(1)

$ git checkout test && git pull
+$ git checkout release && git pull

Important note! If you have any local changes in these branches, then +this merge will create a commit object in the history (with no local +changes git will simply do a "Fast forward" merge). Many people dislike +the "noise" that this creates in the Linux history, so you should avoid +doing this capriciously in the "release" branch, as these noisy commits +will become part of the permanent history when you ask Linus to pull +from the release branch.

A few configuration variables (see git-config(1)) can +make it easy to push both branches to your public tree. (See +the section called “Setting up a public repository”.)

$ cat >> .git/config <<EOF
+[remote "mytree"]
+        url =  master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
+        push = release
+        push = test
+EOF

Then you can push both the test and release trees using +git-push(1):

$ git push mytree

or push just one of the test and release branches using:

$ git push mytree test

$ git push mytree release

Now to apply some patches from the community. Think of a short +snappy name for a branch to hold this patch (or related group of +patches), and create a new branch from the current tip of Linus's +branch:

$ git checkout -b speed-up-spinlocks origin

Now you apply the patch(es), run some tests, and commit the change(s). If +the patch is a multi-part series, then you should apply each as a separate +commit to this branch.

$ ... patch ... test ... commit [ ... patch ... test ... commit ]*

When you are happy with the state of this change, you can pull it into the +"test" branch in preparation to make it public:

$ git checkout test && git pull . speed-up-spinlocks

It is unlikely that you would have any conflicts here … but you might if you +spent a while on this step and had also pulled new versions from upstream.

Some time later when enough time has passed and testing done, you can pull the +same branch into the "release" tree ready to go upstream. This is where you +see the value of keeping each patch (or patch series) in its own branch. It +means that the patches can be moved into the "release" tree in any order.

$ git checkout release && git pull . speed-up-spinlocks

After a while, you will have a number of branches, and despite the +well chosen names you picked for each of them, you may forget what +they are for, or what status they are in. To get a reminder of what +changes are in a specific branch, use:

$ git log linux..branchname | git-shortlog

To see whether it has already been merged into the test or release branches +use:

$ git log test..branchname

$ git log release..branchname

(If this branch has not yet been merged you will see some log entries. +If it has been merged, then there will be no output.)

Once a patch completes the great cycle (moving from test to release, +then pulled by Linus, and finally coming back into your local +"origin/master" branch) the branch for this change is no longer needed. +You detect this when the output from:

$ git log origin..branchname

is empty. At this point the branch can be deleted:

$ git branch -d branchname

Some changes are so trivial that it is not necessary to create a separate +branch and then merge into each of the test and release branches. For +these changes, just apply directly to the "release" branch, and then +merge that into the "test" branch.

To create diffstat and shortlog summaries of changes to include in a "please +pull" request to Linus you can use:

$ git diff --stat origin..release

and

$ git log -p origin..release | git shortlog

Here are some of the scripts that simplify all this even further.

==== update script ====
+# Update a branch in my GIT tree.  If the branch to be updated
+# is origin, then pull from kernel.org.  Otherwise merge
+# origin/master branch into test|release branch
+
+case "$1" in
+test|release)
+        git checkout $1 && git pull . origin
+        ;;
+origin)
+        before=$(cat .git/refs/remotes/origin/master)
+        git fetch origin
+        after=$(cat .git/refs/remotes/origin/master)
+        if [ $before != $after ]
+        then
+                git log $before..$after | git shortlog
+        fi
+        ;;
+*)
+        echo "Usage: $0 origin|test|release" 1>&2
+        exit 1
+        ;;
+esac

==== merge script ====
+# Merge a branch into either the test or release branch
+
+pname=$0
+
+usage()
+{
+        echo "Usage: $pname branch test|release" 1>&2
+        exit 1
+}
+
+if [ ! -f .git/refs/heads/"$1" ]
+then
+        echo "Can't see branch <$1>" 1>&2
+        usage
+fi
+
+case "$2" in
+test|release)
+        if [ $(git log $2..$1 | wc -c) -eq 0 ]
+        then
+                echo $1 already merged into $2 1>&2
+                exit 1
+        fi
+        git checkout $2 && git pull . $1
+        ;;
+*)
+        usage
+        ;;
+esac

==== status script ====
+# report on status of my ia64 GIT tree
+
+gb=$(tput setab 2)
+rb=$(tput setab 1)
+restore=$(tput setab 9)
+
+if [ `git rev-list test..release | wc -c` -gt 0 ]
+then
+        echo $rb Warning: commits in release that are not in test $restore
+        git log test..release
+fi
+
+for branch in `ls .git/refs/heads`
+do
+        if [ $branch = test -o $branch = release ]
+        then
+                continue
+        fi
+
+        echo -n $gb ======= $branch ====== $restore " "
+        status=
+        for ref in test release origin/master
+        do
+                if [ `git rev-list $ref..$branch | wc -c` -gt 0 ]
+                then
+                        status=$status${ref:0:1}
+                fi
+        done
+        case $status in
+        trl)
+                echo $rb Need to pull into test $restore
+                ;;
+        rl)
+                echo "In test"
+                ;;
+        l)
+                echo "Waiting for linus"
+                ;;
+        "")
+                echo $rb All done $restore
+                ;;
+        *)
+                echo $rb "<$status>" $restore
+                ;;
+        esac
+        git log origin/master..$branch | git shortlog
+done

Appendix A. Git Quick Start

Table of Contents

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

This is a quick summary of the major commands; the following chapters +will explain how these work in more detail.

Creating a new repository

From a tarball:

$ tar xzf project.tar.gz
+$ cd project
+$ git init
+Initialized empty Git repository in .git/
+$ git add .
+$ git commit

From a remote repository:

$ git clone git://example.com/pub/project.git
+$ cd project

Managing branches

$ git branch         # list all local branches in this repo
+$ git checkout test  # switch working directory to branch "test"
+$ git branch new     # create branch "new" starting at current HEAD
+$ git branch -d new  # delete branch "new"

Instead of basing new branch on current HEAD (the default), use:

$ git branch new test    # branch named "test"
+$ git branch new v2.6.15 # tag named v2.6.15
+$ git branch new HEAD^   # commit before the most recent
+$ git branch new HEAD^^  # commit before that
+$ git branch new test~10 # ten commits before tip of branch "test"

Create and switch to a new branch at the same time:

$ git checkout -b new v2.6.15

Update and examine branches from the repository you cloned from:

$ git fetch             # update
+$ git branch -r         # list
+  origin/master
+  origin/next
+  ...
+$ git checkout -b masterwork origin/master

Fetch a branch from a different repository, and give it a new +name in your repository:

$ git fetch git://example.com/project.git theirbranch:mybranch
+$ git fetch git://example.com/project.git v2.6.15:mybranch

Keep a list of repositories you work with regularly:

$ git remote add example git://example.com/project.git
+$ git remote                    # list remote repositories
+example
+origin
+$ git remote show example       # get details
+* remote example
+  URL: git://example.com/project.git
+  Tracked remote branches
+    master next ...
+$ git fetch example             # update branches from example
+$ git branch -r                 # list all remote branches

Exploring history

$ gitk                      # visualize and browse history
+$ git log                   # list all commits
+$ git log src/              # ...modifying src/
+$ git log v2.6.15..v2.6.16  # ...in v2.6.16, not in v2.6.15
+$ git log master..test      # ...in branch test, not in branch master
+$ git log test..master      # ...in branch master, but not in test
+$ git log test...master     # ...in one branch, not in both
+$ git log -S'foo()'         # ...where difference contain "foo()"
+$ git log --since="2 weeks ago"
+$ git log -p                # show patches as well
+$ git show                  # most recent commit
+$ git diff v2.6.15..v2.6.16 # diff between two tagged versions
+$ git diff v2.6.15..HEAD    # diff with current head
+$ git grep "foo()"          # search working directory for "foo()"
+$ git grep v2.6.15 "foo()"  # search old tree for "foo()"
+$ git show v2.6.15:a.txt    # look at old version of a.txt

Search for regressions:

$ git bisect start
+$ git bisect bad                # current version is bad
+$ git bisect good v2.6.13-rc2   # last known good revision
+Bisecting: 675 revisions left to test after this
+                                # test here, then:
+$ git bisect good               # if this revision is good, or
+$ git bisect bad                # if this revision is bad.
+                                # repeat until done.

Making changes

Make sure git knows who to blame:

$ cat >>~/.gitconfig <<\EOF
+[user]
+ name = Your Name Comes Here
+ email = you@yourdomain.example.com
+EOF

Select file contents to include in the next commit, then make the +commit:

$ git add a.txt    # updated file
+$ git add b.txt    # new file
+$ git rm c.txt     # old file
+$ git commit

Or, prepare and create the commit in one step:

$ git commit d.txt # use latest content only of d.txt
+$ git commit -a # use latest content of all tracked files

Merging

$ git merge test   # merge branch "test" into the current branch
+$ git pull git://example.com/project.git master
+                   # fetch and merge in remote branch
+$ git pull . test  # equivalent to git merge test

Sharing your changes

Importing or exporting patches:

$ git format-patch origin..HEAD # format a patch for each commit
+ # in HEAD but not in origin
+$ git am mbox # import patches from the mailbox "mbox"

Fetch a branch in a different git repository, then merge into the +current branch:

$ git pull git://example.com/project.git theirbranch

Store the fetched branch into a local branch before merging into the +current branch:

$ git pull git://example.com/project.git theirbranch:mybranch

After creating commits on a local branch, update the remote +branch with your commits:

$ git push ssh://example.com/project.git mybranch:theirbranch

When remote and local branch are both named "test":

$ git push ssh://example.com/project.git test

Shortcut version for a frequently used remote repository:

$ git remote add example ssh://example.com/project.git
+$ git push example test

Repository maintenance

Check for corruption:

$ git fsck

Recompress, remove unused cruft:

$ git gc

Appendix B. Notes and todo list for this manual

This is a work in progress.

The basic requirements: - It must be readable in order, from beginning to end, by someone intelligent with a basic grasp of the unix commandline, but without any special knowledge of git. If diff --git a/user-manual.txt b/user-manual.txt index 8d6688633..c4bff474d 100644 --- a/user-manual.txt +++ b/user-manual.txt @@ -1,18 +1,19 @@ Git User's Manual (for version 1.5.1 or newer) ______________________________________________ + +Git is a fast distributed revision control system. + This manual is designed to be readable by someone with basic unix command-line 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. +<> and <> 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 +regressions, and so on. -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 -software project, to search for regressions, and so on. - -Chapter 4 explains how to do development with git, and chapter 5 how -to share that development with others. +People needing to do actual development will also want to read +<> and <>. Further chapters cover more specialized topics. @@ -23,237 +24,12 @@ pages. For a command such as "git clone", just use $ man git-clone ------------------------------------------------ -[[git-quick-start]] -Git Quick Start -=============== - -This is a quick summary of the major commands; the following chapters -will explain how these work in more detail. - -[[quick-creating-a-new-repository]] -Creating a new repository -------------------------- - -From a tarball: - ------------------------------------------------ -$ tar xzf project.tar.gz -$ cd project -$ git init -Initialized empty Git repository in .git/ -$ git add . -$ git commit ------------------------------------------------ - -From a remote repository: - ------------------------------------------------ -$ git clone git://example.com/pub/project.git -$ cd project ------------------------------------------------ - -[[managing-branches]] -Managing branches ------------------ - ------------------------------------------------ -$ git branch # list all local branches in this repo -$ git checkout test # switch working directory to branch "test" -$ git branch new # create branch "new" starting at current HEAD -$ git branch -d new # delete branch "new" ------------------------------------------------ - -Instead of basing new branch on current HEAD (the default), use: - ------------------------------------------------ -$ git branch new test # branch named "test" -$ git branch new v2.6.15 # tag named v2.6.15 -$ git branch new HEAD^ # commit before the most recent -$ git branch new HEAD^^ # commit before that -$ git branch new test~10 # ten commits before tip of branch "test" ------------------------------------------------ - -Create and switch to a new branch at the same time: - ------------------------------------------------ -$ git checkout -b new v2.6.15 ------------------------------------------------ - -Update and examine branches from the repository you cloned from: - ------------------------------------------------ -$ git fetch # update -$ git branch -r # list - origin/master - origin/next - ... -$ git checkout -b masterwork origin/master ------------------------------------------------ - -Fetch a branch from a different repository, and give it a new -name in your repository: - ------------------------------------------------ -$ git fetch git://example.com/project.git theirbranch:mybranch -$ git fetch git://example.com/project.git v2.6.15:mybranch ------------------------------------------------ - -Keep a list of repositories you work with regularly: - ------------------------------------------------ -$ git remote add example git://example.com/project.git -$ git remote # list remote repositories -example -origin -$ git remote show example # get details -* remote example - URL: git://example.com/project.git - Tracked remote branches - master next ... -$ git fetch example # update branches from example -$ git branch -r # list all remote branches ------------------------------------------------ - - -[[exploring-history]] -Exploring history ------------------ - ------------------------------------------------ -$ gitk # visualize and browse history -$ git log # list all commits -$ git log src/ # ...modifying src/ -$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15 -$ git log master..test # ...in branch test, not in branch master -$ git log test..master # ...in branch master, but not in test -$ git log test...master # ...in one branch, not in both -$ git log -S'foo()' # ...where difference contain "foo()" -$ git log --since="2 weeks ago" -$ git log -p # show patches as well -$ git show # most recent commit -$ git diff v2.6.15..v2.6.16 # diff between two tagged versions -$ git diff v2.6.15..HEAD # diff with current head -$ git grep "foo()" # search working directory for "foo()" -$ git grep v2.6.15 "foo()" # search old tree for "foo()" -$ git show v2.6.15:a.txt # look at old version of a.txt ------------------------------------------------ - -Search for regressions: - ------------------------------------------------ -$ git bisect start -$ git bisect bad # current version is bad -$ git bisect good v2.6.13-rc2 # last known good revision -Bisecting: 675 revisions left to test after this - # test here, then: -$ git bisect good # if this revision is good, or -$ git bisect bad # if this revision is bad. - # repeat until done. ------------------------------------------------ - -[[making-changes]] -Making changes --------------- - -Make sure git knows who to blame: - ------------------------------------------------- -$ cat >>~/.gitconfig <<\EOF -[user] - name = Your Name Comes Here - email = you@yourdomain.example.com -EOF ------------------------------------------------- - -Select file contents to include in the next commit, then make the -commit: - ------------------------------------------------ -$ git add a.txt # updated file -$ git add b.txt # new file -$ git rm c.txt # old file -$ git commit ------------------------------------------------ - -Or, prepare and create the commit in one step: - ------------------------------------------------ -$ git commit d.txt # use latest content only of d.txt -$ git commit -a # use latest content of all tracked files ------------------------------------------------ - -[[merging]] -Merging -------- - ------------------------------------------------ -$ git merge test # merge branch "test" into the current branch -$ git pull git://example.com/project.git master - # fetch and merge in remote branch -$ git pull . test # equivalent to git merge test ------------------------------------------------ - -[[sharing-your-changes]] -Sharing your changes --------------------- - -Importing or exporting patches: - ------------------------------------------------ -$ git format-patch origin..HEAD # format a patch for each commit - # in HEAD but not in origin -$ git am mbox # import patches from the mailbox "mbox" ------------------------------------------------ - -Fetch a branch in a different git repository, then merge into the -current branch: - ------------------------------------------------ -$ git pull git://example.com/project.git theirbranch ------------------------------------------------ - -Store the fetched branch into a local branch before merging into the -current branch: - ------------------------------------------------ -$ git pull git://example.com/project.git theirbranch:mybranch ------------------------------------------------ - -After creating commits on a local branch, update the remote -branch with your commits: - ------------------------------------------------ -$ git push ssh://example.com/project.git mybranch:theirbranch ------------------------------------------------ - -When remote and local branch are both named "test": - ------------------------------------------------ -$ git push ssh://example.com/project.git test ------------------------------------------------ - -Shortcut version for a frequently used remote repository: - ------------------------------------------------ -$ git remote add example ssh://example.com/project.git -$ git push example test ------------------------------------------------ - -[[repository-maintenance]] -Repository maintenance ----------------------- - -Check for corruption: - ------------------------------------------------ -$ git fsck ------------------------------------------------ +See also <> for a brief overview of git commands, +without any explanation. -Recompress, remove unused cruft: +Also, see <> for ways that you can help make this manual more +complete. ------------------------------------------------ -$ git gc ------------------------------------------------ [[repositories-and-branches]] Repositories and Branches @@ -917,6 +693,25 @@ may be any path to a file tracked by git. Examples -------- +[[counting-commits-on-a-branch]] +Counting the number of commits on a branch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Suppose you want to know how many commits you've made on "mybranch" +since it diverged from "origin": + +------------------------------------------------- +$ git log --pretty=oneline origin..mybranch | wc -l +------------------------------------------------- + +Alternatively, you may often see this sort of thing done with the +lower-level command gitlink:git-rev-list[1], which just lists the SHA1's +of all the given commits: + +------------------------------------------------- +$ git rev-list origin..mybranch | wc -l +------------------------------------------------- + [[checking-for-equal-branches]] Check whether two branches point at the same history ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1035,24 +830,114 @@ available Which shows that e05db0fd is reachable from itself, from v1.5.0-rc1, and from v1.5.0-rc2, but not from v1.5.0-rc0. +[[showing-commits-unique-to-a-branch]] +Showing commits unique to a given branch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -[[Developing-with-git]] -Developing with git -=================== +Suppose you would like to see all the commits reachable from the branch +head named "master" but not from any other head in your repository. -[[telling-git-your-name]] -Telling git your name ---------------------- +We can list all the heads in this repository with +gitlink:git-show-ref[1]: -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: +------------------------------------------------- +$ git show-ref --heads +bf62196b5e363d73353a9dcf094c59595f3153b7 refs/heads/core-tutorial +db768d5504c1bb46f63ee9d6e1772bd047e05bf9 refs/heads/maint +a07157ac624b2524a059a3414e99f6f44bebc1e7 refs/heads/master +24dbc180ea14dc1aebe09f14c8ecf32010690627 refs/heads/tutorial-2 +1e87486ae06626c2f31eaa63d26fc0fd646c8af2 refs/heads/tutorial-fixes +------------------------------------------------- ------------------------------------------------- -[user] - name = Your Name Comes Here - email = you@yourdomain.example.com ------------------------------------------------- +We can get just the branch-head names, and remove "master", with +the help of the standard utilities cut and grep: + +------------------------------------------------- +$ git show-ref --heads | cut -d' ' -f2 | grep -v '^refs/heads/master' +refs/heads/core-tutorial +refs/heads/maint +refs/heads/tutorial-2 +refs/heads/tutorial-fixes +------------------------------------------------- + +And then we can ask to see all the commits reachable from master +but not from these other heads: + +------------------------------------------------- +$ gitk master --not $( git show-ref --heads | cut -d' ' -f2 | + grep -v '^refs/heads/master' ) +------------------------------------------------- + +Obviously, endless variations are possible; for example, to see all +commits reachable from some head but not from any tag in the repository: + +------------------------------------------------- +$ gitk ($ git show-ref --heads ) --not $( git show-ref --tags ) +------------------------------------------------- + +(See gitlink:git-rev-parse[1] for explanations of commit-selecting +syntax such as `--not`.) + +[[making-a-release]] +Creating a changelog and tarball for a software release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The gitlink:git-archive[1] command can create a tar or zip archive from +any version of a project; for example: + +------------------------------------------------- +$ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz +------------------------------------------------- + +will use HEAD to produce a tar archive in which each filename is +preceded by "prefix/". + +If you're releasing a new version of a software project, you may want +to simultaneously make a changelog to include in the release +announcement. + +Linus Torvalds, for example, makes new kernel releases by tagging them, +then running: + +------------------------------------------------- +$ release-script 2.6.12 2.6.13-rc6 2.6.13-rc7 +------------------------------------------------- + +where release-script is a shell script that looks like: + +------------------------------------------------- +#!/bin/sh +stable="$1" +last="$2" +new="$3" +echo "# git tag v$new" +echo "git archive --prefix=linux-$new/ v$new | gzip -9 > ../linux-$new.tar.gz" +echo "git diff v$stable v$new | gzip -9 > ../patch-$new.gz" +echo "git log --no-merges v$new ^v$last > ../ChangeLog-$new" +echo "git shortlog --no-merges v$new ^v$last > ../ShortLog" +echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new" +------------------------------------------------- + +and then he just cut-and-pastes the output commands after verifying that +they look OK. + +[[Developing-with-git]] +Developing with git +=================== + +[[telling-git-your-name]] +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 + email = you@yourdomain.example.com +------------------------------------------------ (See the "CONFIGURATION FILE" section of gitlink:git-config[1] for details on the configuration file.) @@ -1789,31 +1674,30 @@ The final result will be a series of commits, one for each patch in the original mailbox, with authorship and commit log message each taken from the message containing each patch. -[[setting-up-a-public-repository]] -Setting up a public repository ------------------------------- +[[public-repositories]] +Public git repositories +----------------------- -Another way to submit changes to a project is to simply tell the -maintainer of that project to pull from your repository, exactly as -you did in the section "<>". +Another way to submit changes to a project is to tell the maintainer of +that project to pull the changes from your repository using git-pull[1]. +In the section "<>" we described this as a way to get updates from the "main" +repository, but it works just as well in the other direction. -If you and maintainer both have accounts on the same machine, then -then you can just pull changes from each other's repositories -directly; note that all of the commands (gitlink:git-clone[1], -git-fetch[1], git-pull[1], etc.) that accept a URL as an argument -will also accept a local directory name; so, for example, you can -use +If you and the maintainer both have accounts on the same machine, then +you can just pull changes from each other's repositories directly; +commands that accepts repository URLs as arguments will also accept a +local directory name: ------------------------------------------------- $ git clone /path/to/repository $ git pull /path/to/other/repository ------------------------------------------------- -If this sort of setup is inconvenient or impossible, another (more -common) option is to set up a public repository on a public server. -This also allows you to cleanly separate private work in progress -from publicly visible work. +However, the more common way to do this is to maintain a separate public +repository (usually on a different host) for others to pull changes +from. This is usually more convenient, and allows you to cleanly +separate private work in progress from publicly visible work. You will continue to do your day-to-day work in your personal repository, but periodically "push" changes from your personal @@ -1832,32 +1716,52 @@ like this: | they push V their public repo <------------------- their repo -Now, assume your personal repository is in the directory ~/proj. We -first create a new clone of the repository: +[[setting-up-a-public-repository]] +Setting up a public repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assume your personal repository is in the directory ~/proj. We +first create a new clone of the repository and tell git-daemon that it +is meant to be public: ------------------------------------------------- $ git clone --bare ~/proj proj.git +$ touch proj.git/git-daemon-export-ok ------------------------------------------------- The resulting directory proj.git contains a "bare" git repository--it is -just the contents of the ".git" directory, without a checked-out copy of -a working directory. +just the contents of the ".git" directory, without any files checked out +around it. Next, copy proj.git to the server where you plan to host the public repository. You can use scp, rsync, or whatever is most convenient. -If somebody else maintains the public server, they may already have -set up a git service for you, and you may skip to the section +[[exporting-via-git]] +Exporting a git repository via the git protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the preferred method. + +If someone else administers the server, they should tell you what +directory to put the repository in, and what git:// url it will appear +at. You can then skip to the section "<>", below. -Otherwise, the following sections explain how to export your newly -created public repository: +Otherwise, all you need to do is start gitlink:git-daemon[1]; it will +listen on port 9418. By default, it will allow access to any directory +that looks like a git directory and contains the magic file +git-daemon-export-ok. Passing some directory paths as git-daemon +arguments will further restrict the exports to those paths. + +You can also run git-daemon as an inetd service; see the +gitlink:git-daemon[1] man page for details. (See especially the +examples section.) [[exporting-via-http]] Exporting a git repository via http ------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The git protocol gives better performance and reliability, but on a host with a web server set up, http exports may be simpler to set up. @@ -1889,20 +1793,11 @@ link:howto/setup-git-server-over-http.txt[setup-git-server-over-http] for a slightly more sophisticated setup using WebDAV which also allows pushing over http.) -[[exporting-via-git]] -Exporting a git repository via the git protocol ------------------------------------------------ - -This is the preferred method. - -For now, we refer you to the gitlink:git-daemon[1] man page for -instructions. (See especially the examples section.) - [[pushing-changes-to-a-public-repository]] Pushing changes to a public repository --------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Note that the two techniques outline above (exporting via +Note that the two techniques outlined above (exporting via <> or <>) allow other maintainers to fetch your latest changes, but they do not allow write access, which you will need to update the public repository with the @@ -1954,7 +1849,7 @@ details. [[setting-up-a-shared-repository]] 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 @@ -1963,8 +1858,8 @@ link:cvs-migration.html[git for CVS users] for instructions on how to set this up. [[setting-up-gitweb]] -Allow web browsing of a repository ----------------------------------- +Allowing 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 @@ -1974,7 +1869,302 @@ gitweb/INSTALL in the git source tree for instructions on setting it up. Examples -------- -TODO: topic branches, typical roles as in everyday.txt, ? +[[maintaining-topic-branches]] +Maintaining topic branches for a Linux subsystem maintainer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This describes how Tony Luck uses git in his role as maintainer of the +IA64 architecture for the Linux kernel. + +He uses two public branches: + + - A "test" tree into which patches are initially placed so that they + can get some exposure when integrated with other ongoing development. + This tree is available to Andrew for pulling into -mm whenever he + wants. + + - A "release" tree into which tested patches are moved for final sanity + checking, and as a vehicle to send them upstream to Linus (by sending + him a "please pull" request.) + +He also uses a set of temporary branches ("topic branches"), each +containing a logical grouping of patches. + +To set this up, first create your work tree by cloning Linus's public +tree: + +------------------------------------------------- +$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work +$ cd work +------------------------------------------------- + +Linus's tree will be stored in the remote branch named origin/master, +and can be updated using gitlink:git-fetch[1]; you can track other +public trees using gitlink:git-remote[1] to set up a "remote" and +git-fetch[1] to keep them up-to-date; see <>. + +Now create the branches in which you are going to work; these start out +at the current tip of origin/master branch, and should be set up (using +the --track option to gitlink:git-branch[1]) to merge changes in from +Linus by default. + +------------------------------------------------- +$ git branch --track test origin/master +$ git branch --track release origin/master +------------------------------------------------- + +These can be easily kept up to date using gitlink:git-pull[1] + +------------------------------------------------- +$ git checkout test && git pull +$ git checkout release && git pull +------------------------------------------------- + +Important note! If you have any local changes in these branches, then +this merge will create a commit object in the history (with no local +changes git will simply do a "Fast forward" merge). Many people dislike +the "noise" that this creates in the Linux history, so you should avoid +doing this capriciously in the "release" branch, as these noisy commits +will become part of the permanent history when you ask Linus to pull +from the release branch. + +A few configuration variables (see gitlink:git-config[1]) can +make it easy to push both branches to your public tree. (See +<>.) + +------------------------------------------------- +$ cat >> .git/config <&2 + exit 1 + ;; +esac +------------------------------------------------- + +------------------------------------------------- +==== merge script ==== +# Merge a branch into either the test or release branch + +pname=$0 + +usage() +{ + echo "Usage: $pname branch test|release" 1>&2 + exit 1 +} + +if [ ! -f .git/refs/heads/"$1" ] +then + echo "Can't see branch <$1>" 1>&2 + usage +fi + +case "$2" in +test|release) + if [ $(git log $2..$1 | wc -c) -eq 0 ] + then + echo $1 already merged into $2 1>&2 + exit 1 + fi + git checkout $2 && git pull . $1 + ;; +*) + usage + ;; +esac +------------------------------------------------- + +------------------------------------------------- +==== status script ==== +# report on status of my ia64 GIT tree + +gb=$(tput setab 2) +rb=$(tput setab 1) +restore=$(tput setab 9) + +if [ `git rev-list test..release | wc -c` -gt 0 ] +then + echo $rb Warning: commits in release that are not in test $restore + git log test..release +fi + +for branch in `ls .git/refs/heads` +do + if [ $branch = test -o $branch = release ] + then + continue + fi + + echo -n $gb ======= $branch ====== $restore " " + status= + for ref in test release origin/master + do + if [ `git rev-list $ref..$branch | wc -c` -gt 0 ] + then + status=$status${ref:0:1} + fi + done + case $status in + trl) + echo $rb Need to pull into test $restore + ;; + rl) + echo "In test" + ;; + l) + echo "Waiting for linus" + ;; + "") + echo $rb All done $restore + ;; + *) + echo $rb "<$status>" $restore + ;; + esac + git log origin/master..$branch | git shortlog +done +------------------------------------------------- [[cleaning-up-history]] @@ -3160,12 +3350,454 @@ confusing and scary messages, but it won't actually do anything bad. In contrast, running "git prune" while somebody is actively changing the repository is a *BAD* idea). +[[birdview-on-the-source-code]] +A birds-eye view of Git's source code +------------------------------------- + +It is not always easy for new developers to find their way through Git's +source code. This section gives you a little guidance to show where to +start. + +A good place to start is with the contents of the initial commit, with: + +---------------------------------------------------- +$ git checkout e83c5163 +---------------------------------------------------- + +The initial revision lays the foundation for almost everything git has +today, but is small enough to read in one sitting. + +Note that terminology has changed since that revision. For example, the +README in that revision uses the word "changeset" to describe what we +now call a <>. + +Also, we do not call it "cache" any more, but "index", however, the +file is still called `cache.h`. Remark: Not much reason to change it now, +especially since there is no good single name for it anyway, because it is +basically _the_ header file which is included by _all_ of Git's C sources. + +If you grasp the ideas in that initial commit, you should check out a +more recent version and skim `cache.h`, `object.h` and `commit.h`. + +In the early days, Git (in the tradition of UNIX) was a bunch of programs +which were extremely simple, and which you used in scripts, piping the +output of one into another. This turned out to be good for initial +development, since it was easier to test new things. However, recently +many of these parts have become builtins, and some of the core has been +"libified", i.e. put into libgit.a for performance, portability reasons, +and to avoid code duplication. + +By now, you know what the index is (and find the corresponding data +structures in `cache.h`), and that there are just a couple of object types +(blobs, trees, commits and tags) which inherit their common structure from +`struct object`, which is their first member (and thus, you can cast e.g. +`(struct object *)commit` to achieve the _same_ as `&commit->object`, i.e. +get at the object name and flags). + +Now is a good point to take a break to let this information sink in. + +Next step: get familiar with the object naming. Read <>. +There are quite a few ways to name an object (and not only revisions!). +All of these are handled in `sha1_name.c`. Just have a quick look at +the function `get_sha1()`. A lot of the special handling is done by +functions like `get_sha1_basic()` or the likes. + +This is just to get you into the groove for the most libified part of Git: +the revision walker. + +Basically, the initial version of `git log` was a shell script: + +---------------------------------------------------------------- +$ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \ + LESS=-S ${PAGER:-less} +---------------------------------------------------------------- + +What does this mean? + +`git-rev-list` is the original version of the revision walker, which +_always_ printed a list of revisions to stdout. It is still functional, +and needs to, since most new Git programs start out as scripts using +`git-rev-list`. + +`git-rev-parse` is not as important any more; it was only used to filter out +options that were relevant for the different plumbing commands that were +called by the script. + +Most of what `git-rev-list` did is contained in `revision.c` and +`revision.h`. It wraps the options in a struct named `rev_info`, which +controls how and what revisions are walked, and more. + +The original job of `git-rev-parse` is now taken by the function +`setup_revisions()`, which parses the revisions and the common command line +options for the revision walker. This information is stored in the struct +`rev_info` for later consumption. You can do your own command line option +parsing after calling `setup_revisions()`. After that, you have to call +`prepare_revision_walk()` for initialization, and then you can get the +commits one by one with the function `get_revision()`. + +If you are interested in more details of the revision walking process, +just have a look at the first implementation of `cmd_log()`; call +`git-show v1.3.0~155^2~4` and scroll down to that function (note that you +no longer need to call `setup_pager()` directly). + +Nowadays, `git log` is a builtin, which means that it is _contained_ in the +command `git`. The source side of a builtin is + +- a function called `cmd_`, typically defined in `builtin-.c`, + and declared in `builtin.h`, + +- an entry in the `commands[]` array in `git.c`, and + +- an entry in `BUILTIN_OBJECTS` in the `Makefile`. + +Sometimes, more than one builtin is contained in one source file. For +example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin-log.c`, +since they share quite a bit of code. In that case, the commands which are +_not_ named like the `.c` file in which they live have to be listed in +`BUILT_INS` in the `Makefile`. + +`git log` looks more complicated in C than it does in the original script, +but that allows for a much greater flexibility and performance. + +Here again it is a good point to take a pause. + +Lesson three is: study the code. Really, it is the best way to learn about +the organization of Git (after you know the basic concepts). + +So, think about something which you are interested in, say, "how can I +access a blob just knowing the object name of it?". The first step is to +find a Git command with which you can do it. In this example, it is either +`git show` or `git cat-file`. + +For the sake of clarity, let's stay with `git cat-file`, because it + +- is plumbing, and + +- was around even in the initial commit (it literally went only through + some 20 revisions as `cat-file.c`, was renamed to `builtin-cat-file.c` + when made a builtin, and then saw less than 10 versions). + +So, look into `builtin-cat-file.c`, search for `cmd_cat_file()` and look what +it does. + +------------------------------------------------------------------ + git_config(git_default_config); + if (argc != 3) + usage("git-cat-file [-t|-s|-e|-p|] "); + if (get_sha1(argv[2], sha1)) + die("Not a valid object name %s", argv[2]); +------------------------------------------------------------------ + +Let's skip over the obvious details; the only really interesting part +here is the call to `get_sha1()`. It tries to interpret `argv[2]` as an +object name, and if it refers to an object which is present in the current +repository, it writes the resulting SHA-1 into the variable `sha1`. + +Two things are interesting here: + +- `get_sha1()` returns 0 on _success_. This might surprise some new + Git hackers, but there is a long tradition in UNIX to return different + negative numbers in case of different errors -- and 0 on success. + +- the variable `sha1` in the function signature of `get_sha1()` is `unsigned + char \*`, but is actually expected to be a pointer to `unsigned + char[20]`. This variable will contain the 160-bit SHA-1 of the given + commit. Note that whenever a SHA-1 is passed as `unsigned char \*`, it + is the binary representation, as opposed to the ASCII representation in + hex characters, which is passed as `char *`. + +You will see both of these things throughout the code. + +Now, for the meat: + +----------------------------------------------------------------------------- + case 0: + buf = read_object_with_reference(sha1, argv[1], &size, NULL); +----------------------------------------------------------------------------- + +This is how you read a blob (actually, not only a blob, but any type of +object). To know how the function `read_object_with_reference()` actually +works, find the source code for it (something like `git grep +read_object_with | grep ":[a-z]"` in the git repository), and read +the source. + +To find out how the result can be used, just read on in `cmd_cat_file()`: + +----------------------------------- + write_or_die(1, buf, size); +----------------------------------- + +Sometimes, you do not know where to look for a feature. In many such cases, +it helps to search through the output of `git log`, and then `git show` the +corresponding commit. + +Example: If you know that there was some test case for `git bundle`, but +do not remember where it was (yes, you _could_ `git grep bundle t/`, but that +does not illustrate the point!): + +------------------------ +$ git log --no-merges t/ +------------------------ + +In the pager (`less`), just search for "bundle", go a few lines back, +and see that it is in commit 18449ab0... Now just copy this object name, +and paste it into the command line + +------------------- +$ git show 18449ab0 +------------------- + +Voila. + +Another example: Find out what to do in order to make some script a +builtin: + +------------------------------------------------- +$ git log --no-merges --diff-filter=A builtin-*.c +------------------------------------------------- + +You see, Git is actually the best tool to find out about the source of Git +itself! + [[glossary]] include::glossary.txt[] +[[git-quick-start]] +Appendix A: Git Quick Start +=========================== + +This is a quick summary of the major commands; the following chapters +will explain how these work in more detail. + +[[quick-creating-a-new-repository]] +Creating a new repository +------------------------- + +From a tarball: + +----------------------------------------------- +$ tar xzf project.tar.gz +$ cd project +$ git init +Initialized empty Git repository in .git/ +$ git add . +$ git commit +----------------------------------------------- + +From a remote repository: + +----------------------------------------------- +$ git clone git://example.com/pub/project.git +$ cd project +----------------------------------------------- + +[[managing-branches]] +Managing branches +----------------- + +----------------------------------------------- +$ git branch # list all local branches in this repo +$ git checkout test # switch working directory to branch "test" +$ git branch new # create branch "new" starting at current HEAD +$ git branch -d new # delete branch "new" +----------------------------------------------- + +Instead of basing new branch on current HEAD (the default), use: + +----------------------------------------------- +$ git branch new test # branch named "test" +$ git branch new v2.6.15 # tag named v2.6.15 +$ git branch new HEAD^ # commit before the most recent +$ git branch new HEAD^^ # commit before that +$ git branch new test~10 # ten commits before tip of branch "test" +----------------------------------------------- + +Create and switch to a new branch at the same time: + +----------------------------------------------- +$ git checkout -b new v2.6.15 +----------------------------------------------- + +Update and examine branches from the repository you cloned from: + +----------------------------------------------- +$ git fetch # update +$ git branch -r # list + origin/master + origin/next + ... +$ git checkout -b masterwork origin/master +----------------------------------------------- + +Fetch a branch from a different repository, and give it a new +name in your repository: + +----------------------------------------------- +$ git fetch git://example.com/project.git theirbranch:mybranch +$ git fetch git://example.com/project.git v2.6.15:mybranch +----------------------------------------------- + +Keep a list of repositories you work with regularly: + +----------------------------------------------- +$ git remote add example git://example.com/project.git +$ git remote # list remote repositories +example +origin +$ git remote show example # get details +* remote example + URL: git://example.com/project.git + Tracked remote branches + master next ... +$ git fetch example # update branches from example +$ git branch -r # list all remote branches +----------------------------------------------- + + +[[exploring-history]] +Exploring history +----------------- + +----------------------------------------------- +$ gitk # visualize and browse history +$ git log # list all commits +$ git log src/ # ...modifying src/ +$ git log v2.6.15..v2.6.16 # ...in v2.6.16, not in v2.6.15 +$ git log master..test # ...in branch test, not in branch master +$ git log test..master # ...in branch master, but not in test +$ git log test...master # ...in one branch, not in both +$ git log -S'foo()' # ...where difference contain "foo()" +$ git log --since="2 weeks ago" +$ git log -p # show patches as well +$ git show # most recent commit +$ git diff v2.6.15..v2.6.16 # diff between two tagged versions +$ git diff v2.6.15..HEAD # diff with current head +$ git grep "foo()" # search working directory for "foo()" +$ git grep v2.6.15 "foo()" # search old tree for "foo()" +$ git show v2.6.15:a.txt # look at old version of a.txt +----------------------------------------------- + +Search for regressions: + +----------------------------------------------- +$ git bisect start +$ git bisect bad # current version is bad +$ git bisect good v2.6.13-rc2 # last known good revision +Bisecting: 675 revisions left to test after this + # test here, then: +$ git bisect good # if this revision is good, or +$ git bisect bad # if this revision is bad. + # repeat until done. +----------------------------------------------- + +[[making-changes]] +Making changes +-------------- + +Make sure git knows who to blame: + +------------------------------------------------ +$ cat >>~/.gitconfig <<\EOF +[user] + name = Your Name Comes Here + email = you@yourdomain.example.com +EOF +------------------------------------------------ + +Select file contents to include in the next commit, then make the +commit: + +----------------------------------------------- +$ git add a.txt # updated file +$ git add b.txt # new file +$ git rm c.txt # old file +$ git commit +----------------------------------------------- + +Or, prepare and create the commit in one step: + +----------------------------------------------- +$ git commit d.txt # use latest content only of d.txt +$ git commit -a # use latest content of all tracked files +----------------------------------------------- + +[[merging]] +Merging +------- + +----------------------------------------------- +$ git merge test # merge branch "test" into the current branch +$ git pull git://example.com/project.git master + # fetch and merge in remote branch +$ git pull . test # equivalent to git merge test +----------------------------------------------- + +[[sharing-your-changes]] +Sharing your changes +-------------------- + +Importing or exporting patches: + +----------------------------------------------- +$ git format-patch origin..HEAD # format a patch for each commit + # in HEAD but not in origin +$ git am mbox # import patches from the mailbox "mbox" +----------------------------------------------- + +Fetch a branch in a different git repository, then merge into the +current branch: + +----------------------------------------------- +$ git pull git://example.com/project.git theirbranch +----------------------------------------------- + +Store the fetched branch into a local branch before merging into the +current branch: + +----------------------------------------------- +$ git pull git://example.com/project.git theirbranch:mybranch +----------------------------------------------- + +After creating commits on a local branch, update the remote +branch with your commits: + +----------------------------------------------- +$ git push ssh://example.com/project.git mybranch:theirbranch +----------------------------------------------- + +When remote and local branch are both named "test": + +----------------------------------------------- +$ git push ssh://example.com/project.git test +----------------------------------------------- + +Shortcut version for a frequently used remote repository: + +----------------------------------------------- +$ git remote add example ssh://example.com/project.git +$ git push example test +----------------------------------------------- + +[[repository-maintenance]] +Repository maintenance +---------------------- + +Check for corruption: + +----------------------------------------------- +$ git fsck +----------------------------------------------- + +Recompress, remove unused cruft: + +----------------------------------------------- +$ git gc +----------------------------------------------- + + [[todo]] -Notes and todo list for this manual -=================================== +Appendix B: Notes and todo list for this manual +=============================================== This is a work in progress. -- 2.26.2

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

Preface

Chapter 1. Git Quick Start

Creating a new repository

Managing branches

Exploring history

Making changes

Merging

Sharing your changes

Repository maintenance

Chapter 2. Repositories and Branches

How to get a git repository

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

Preface

Chapter 1. Repositories and Branches

How to get a git repository

Understanding history: commits, parents, and reachability

Chapter 3. Exploring git history

Chapter 2. Exploring git history

Examples

Check whether two branches point at the same history

Examples

Counting the number of commits on a branch

Check whether two branches point at the same history

Chapter 4. Developing with git

Telling git your name

Showing commits unique to a given branch

Creating a changelog and tarball for a software release

Chapter 3. Developing with git

Telling git your name

Checking out an old version of a file

Checking out an old version of a file

Chapter 5. Sharing development with others

Getting updates with git pull

Chapter 4. Sharing development with others

Getting updates with git pull

Setting up a public repository

Public git repositories

Setting up a public repository

Exporting a git repository via http

Exporting a git repository via the git protocol

Exporting a git repository via http

Exporting a git repository via the git protocol

Pushing changes to a public repository

Pushing changes to a public repository

Setting up a shared repository

Setting up a shared repository

Allow web browsing of a repository

Allowing web browsing of a repository

Examples

Chapter 6. Rewriting history and maintaining patch series

Examples

Maintaining topic branches for a Linux subsystem maintainer

Chapter 5. Rewriting history and maintaining patch series

Creating the perfect patch series

Chapter 7. Advanced branch management

Fetching individual branches

Chapter 6. Advanced branch management

Fetching individual branches

Chapter 8. Git internals

Chapter 7. Git internals

The Object Database

Dangling objects

Chapter 9. GIT Glossary

A birds-eye view of Git's source code

Chapter 8. GIT Glossary

Chapter 10. Notes and todo list for this manual

Appendix A. Git Quick Start

Creating a new repository

Managing branches

Exploring history

Making changes

Merging

Sharing your changes

Repository maintenance

Appendix B. Notes and todo list for this manual