mirror/git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-11-18 16:43:49 +01:00
Code

Merge branch 'maint' of git://linux-nfs.org/~bfields/git into maint

Browse Source 
* 'maint' of git://linux-nfs.org/~bfields/git:
  user-manual: reorganize public git repo discussion
  user-manual: listing commits reachable from some refs not others
  user-manual: introduce git
  user-manual: add a "counting commits" example
  user-manual: move howto/using-topic-branches into manual
  user-manual: move howto/make-dist.txt into user manual
  Documentation: remove howto's now incorporated into manual
  user-manual: move quick-start to an appendix
  glossary: expand and clarify some definitions, prune cross-references
  user-manual: revise birdseye-view chapter
  Add a birdview-on-the-source-code section to the user manual
This commit is contained in:
Junio C Hamano 2007-05-18 17:13:47 -07:00
commit cecb98a9c3
6 changed files with 1046 additions and 896 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
Documentation/glossary.txt
View File

@ -2,12 +2,12 @@ GIT Glossary
============
[[def_alternate_object_database]]alternate object database::
Via the alternates mechanism, a <<def_repository,repository>> can
inherit part of its <<def_object_database,object database>> from another
<<def_object_database,object database>>, which is called "alternate".
Via the alternates mechanism, a <<def_repository,repository>>
can inherit part of its <<def_object_database,object database>>
from another object database, which is called "alternate".
[[def_bare_repository]]bare repository::
A <<def_bare_repository,bare repository>> is normally an appropriately
A bare repository is normally an appropriately
named <<def_directory,directory>> with a `.git` suffix that does not
have a locally checked-out copy of any of the files under
<<def_revision,revision>> control. That is, all of the `git`
@ -21,10 +21,15 @@ GIT Glossary
Untyped <<def_object,object>>, e.g. the contents of a file.
[[def_branch]]branch::
A non-cyclical graph of revisions, i.e. the complete history of a
particular <<def_revision,revision>>, which is called the
branch <<def_head,head>>. The heads
are stored in `$GIT_DIR/refs/heads/`.
A "branch" is an active line of development. The most recent
<<def_commit,commit>> on a branch is referred to as the tip of
that branch. The tip of the branch is referenced by a branch
<<def_head,head>>, which moves forward as additional development
is done on the branch. A single git
<<def_repository,repository>> can track an arbitrary number of
branches, but your <<def_working_tree,working tree>> is
associated with just one of them (the "current" or "checked out"
branch), and <<def_HEAD,HEAD>> points to that branch.
[[def_cache]]cache::
Obsolete for: <<def_index,index>>.
@ -50,18 +55,25 @@ GIT Glossary
as a new series of changes on top of different codebase. In GIT, this is
performed by "git cherry-pick" command to extract the change introduced
by an existing <<def_commit,commit>> and to record it based on the tip
of the current <<def_branch,branch>> as a new <<def_commit,commit>>.
of the current <<def_branch,branch>> as a new commit.
[[def_clean]]clean::
A <<def_working_tree,working tree>> is <<def_clean,clean>>, if it
A <<def_working_tree,working tree>> is clean, if it
corresponds to the <<def_revision,revision>> referenced by the current
<<def_head,head>>. Also see "<<def_dirty,dirty>>".
[[def_commit]]commit::
As a verb: The action of storing the current state of the
<<def_index,index>> in the <<def_object_database,object database>>. The
result is a <<def_revision,revision>>. As a noun: Short hand for
<<def_commit_object,commit object>>.
As a noun: A single point in the
git history; the entire history of a project is represented as a
set of interrelated commits. The word "commit" is often
used by git in the same places other revision control systems
use the words "revision" or "version". Also used as a short
hand for <<def_commit_object,commit object>>.
+
As a verb: The action of storing a new snapshot of the project's
state in the git history, by creating a new commit representing the current
state of the <<def_index,index>> and advancing <<def_HEAD,HEAD>>
to point at the new commit.
[[def_commit_object]]commit object::
An <<def_object,object>> which contains the information about a
@ -77,16 +89,22 @@ GIT Glossary
[[def_DAG]]DAG::
Directed acyclic graph. The <<def_commit,commit>> objects form a
directed acyclic graph, because they have parents (directed), and the
graph of <<def_commit,commit>> objects is acyclic (there is no
graph of commit objects is acyclic (there is no
<<def_chain,chain>> which begins and ends with the same
<<def_object,object>>).
[[def_dangling_object]]dangling object::
An <<def_unreachable_object,unreachable object>> which is not
<<def_reachable,reachable>> even from other unreachable objects; a
<<def_dangling_object,dangling object>> has no references to it from any
dangling object has no references to it from any
reference or <<def_object,object>> in the <<def_repository,repository>>.
[[def_detached_HEAD]]detached HEAD::
Normally the <<def_HEAD,HEAD>> stores the name of a
<<def_branch,branch>>. However, git also allows you to check
out an arbitrary commit that isn't necessarily the tip of any
particular branch. In this case HEAD is said to be "detached".
[[def_dircache]]dircache::
You are *waaaaay* behind.
@ -94,7 +112,7 @@ GIT Glossary
The list you get with "ls" :-)
[[def_dirty]]dirty::
A <<def_working_tree,working tree>> is said to be <<def_dirty,dirty>> if
A <<def_working_tree,working tree>> is said to be "dirty" if
it contains modifications which have not been committed to the current
<<def_branch,branch>>.
@ -109,16 +127,16 @@ GIT Glossary
<<def_branch,branch>>'s changes that happen to be a descendant of what
you have. In such these cases, you do not make a new <<def_merge,merge>>
<<def_commit,commit>> but instead just update to his
<<def_revision,revision>>. This will happen frequently on a
revision. This will happen frequently on a
<<def_tracking_branch,tracking branch>> of a remote
<<def_repository,repository>>.
[[def_fetch]]fetch::
Fetching a <<def_branch,branch>> means to get the
<<def_branch,branch>>'s <<def_head_ref,head ref>> from a remote
<<def_repository,repository>>, to find out which objects are missing
from the local <<def_object_database,object database>>, and to get them,
too.
branch's <<def_head_ref,head ref>> from a remote
<<def_repository,repository>>, to find out which objects are
missing from the local <<def_object_database,object database>>,
and to get them, too. See also gitlink:git-fetch[1].
[[def_file_system]]file system::
Linus Torvalds originally designed git to be a user space file system,
@ -132,61 +150,83 @@ GIT Glossary
Grafts enables two otherwise different lines of development to be joined
together by recording fake ancestry information for commits. This way
you can make git pretend the set of parents a <<def_commit,commit>> has
is different from what was recorded when the <<def_commit,commit>> was
is different from what was recorded when the commit was
created. Configured via the `.git/info/grafts` file.
[[def_hash]]hash::
In git's context, synonym to <<def_object_name,object name>>.
[[def_head]]head::
The top of a <<def_branch,branch>>. It contains a <<def_ref,ref>> to the
corresponding <<def_commit_object,commit object>>.
A named reference to the <<def_commit,commit>> at the tip of a
<<def_branch,branch>>. Heads are stored in
`$GIT_DIR/refs/heads/`, except when using packed refs. (See
gitlink:git-pack-refs[1].)
[[def_HEAD]]HEAD::
The current branch. In more detail: Your <<def_working_tree,
working tree>> is normally derived from the state of the tree
referred to by HEAD. HEAD is a reference to one of the
<<def_head,heads>> in your repository, except when using a
<<def_detached_HEAD,detached HEAD>>, in which case it may
reference an arbitrary commit.
[[def_head_ref]]head ref::
A <<def_ref,ref>> pointing to a <<def_head,head>>. Often, this is
abbreviated to "<<def_head,head>>". Head refs are stored in
`$GIT_DIR/refs/heads/`.
A synonym for <<def_head,head>>.
[[def_hook]]hook::
During the normal execution of several git commands, call-outs are made
to optional scripts that allow a developer to add functionality or
checking. Typically, the hooks allow for a command to be pre-verified
and potentially aborted, and allow for a post-notification after the
operation is done. The <<def_hook,hook>> scripts are found in the
operation is done. The hook scripts are found in the
`$GIT_DIR/hooks/` <<def_directory,directory>>, and are enabled by simply
making them executable.
[[def_index]]index::
A collection of files with stat information, whose contents are stored
as objects. The <<def_index,index>> is a stored version of your working
as objects. The index is a stored version of your working
<<def_tree,tree>>. Truth be told, it can also contain a second, and even
a third version of a <<def_working_tree,working tree>>, which are used
when merging.
[[def_index_entry]]index entry::
The information regarding a particular file, stored in the
<<def_index,index>>. An <<def_index_entry,index entry>> can be unmerged,
if a <<def_merge,merge>> was started, but not yet finished (i.e. if the
<<def_index,index>> contains multiple versions of that file).
<<def_index,index>>. An index entry can be unmerged, if a
<<def_merge,merge>> was started, but not yet finished (i.e. if
the index contains multiple versions of that file).
[[def_master]]master::
The default development <<def_branch,branch>>. Whenever you create a git
<<def_repository,repository>>, a <<def_branch,branch>> named
"<<def_master,master>>" is created, and becomes the active
<<def_branch,branch>>. In most cases, this contains the local
development, though that is purely conventional and not required.
The default development <<def_branch,branch>>. Whenever you
create a git <<def_repository,repository>>, a branch named
"master" is created, and becomes the active branch. In most
cases, this contains the local development, though that is
purely by convention and is not required.
[[def_merge]]merge::
To <<def_merge,merge>> branches means to try to accumulate the changes
since a common ancestor and apply them to the first
<<def_branch,branch>>. An automatic <<def_merge,merge>> uses heuristics
to accomplish that. Evidently, an automatic <<def_merge,merge>> can
fail.
As a verb: To bring the contents of another
<<def_branch,branch>> (possibly from an external
<<def_repository,repository>>) into the current branch. In the
case where the merged-in branch is from a different repository,
this is done by first <<def_fetch,fetching>> the remote branch
and then merging the result into the current branch. This
combination of fetch and merge operations is called a
<<def_pull,pull>>. Merging is performed by an automatic process
that identifies changes made since the branches diverged, and
then applies all those changes together. In cases where changes
conflict, manual intervention may be required to complete the
merge.
+
As a noun: unless it is a <<def_fast_forward,fast forward>>, a
successful merge results in the creation of a new <<def_commit,commit>>
representing the result of the merge, and having as
<<def_parent,parents>> the tips of the merged <<def_branch,branches>>.
This commit is referred to as a "merge commit", or sometimes just a
"merge".
[[def_object]]object::
The unit of storage in git. It is uniquely identified by the
<<def_SHA1,SHA1>> of its contents. Consequently, an
<<def_object,object>> can not be changed.
object can not be changed.
[[def_object_database]]object database::
Stores a set of "objects", and an individual <<def_object,object>> is
@ -198,9 +238,9 @@ GIT Glossary
[[def_object_name]]object name::
The unique identifier of an <<def_object,object>>. The <<def_hash,hash>>
of the <<def_object,object>>'s contents using the Secure Hash Algorithm
of the object's contents using the Secure Hash Algorithm
1 and usually represented by the 40 character hexadecimal encoding of
the <<def_hash,hash>> of the <<def_object,object>> (possibly followed by
the <<def_hash,hash>> of the object (possibly followed by
a white space).
[[def_object_type]]object type::
@ -215,7 +255,7 @@ GIT Glossary
[[def_origin]]origin::
The default upstream <<def_repository,repository>>. Most projects have
at least one upstream project which they track. By default
'<<def_origin,origin>>' is used for that purpose. New upstream updates
'origin' is used for that purpose. New upstream updates
will be fetched into remote tracking branches named
origin/name-of-upstream-branch, which you can see using
"git <<def_branch,branch>> -r".
@ -227,7 +267,7 @@ GIT Glossary
[[def_pack_index]]pack index::
The list of identifiers, and other information, of the objects in a
<<def_pack,pack>>, to assist in efficiently accessing the contents of a
<<def_pack,pack>>.
pack.
[[def_parent]]parent::
A <<def_commit_object,commit object>> contains a (possibly empty) list
@ -247,29 +287,29 @@ GIT Glossary
[[def_porcelain]]porcelain::
Cute name for programs and program suites depending on
<<def_core_git,core git>>, presenting a high level access to
<<def_core_git,core git>>. Porcelains expose more of a <<def_SCM,SCM>>
core git. Porcelains expose more of a <<def_SCM,SCM>>
interface than the <<def_plumbing,plumbing>>.
[[def_pull]]pull::
Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and
<<def_merge,merge>> it.
<<def_merge,merge>> it. See also gitlink:git-pull[1].
[[def_push]]push::
Pushing a <<def_branch,branch>> means to get the <<def_branch,branch>>'s
Pushing a <<def_branch,branch>> means to get the branch's
<<def_head_ref,head ref>> from a remote <<def_repository,repository>>,
find out if it is an ancestor to the <<def_branch,branch>>'s local
<<def_head_ref,head ref>> is a direct, and in that case, putting all
find out if it is an ancestor to the branch's local
head ref is a direct, and in that case, putting all
objects, which are <<def_reachable,reachable>> from the local
<<def_head_ref,head ref>>, and which are missing from the remote
<<def_repository,repository>>, into the remote
head ref, and which are missing from the remote
repository, into the remote
<<def_object_database,object database>>, and updating the remote
<<def_head_ref,head ref>>. If the remote <<def_head,head>> is not an
ancestor to the local <<def_head,head>>, the <<def_push,push>> fails.
head ref. If the remote <<def_head,head>> is not an
ancestor to the local head, the push fails.
[[def_reachable]]reachable::
All of the ancestors of a given <<def_commit,commit>> are said to be
<<def_reachable,reachable>> from that <<def_commit,commit>>. More
generally, one <<def_object,object>> is <<def_reachable,reachable>> from
"reachable" from that commit. More
generally, one <<def_object,object>> is reachable from
another if we can reach the one from the other by a <<def_chain,chain>>
that follows <<def_tag,tags>> to whatever they tag,
<<def_commit_object,commits>> to their parents or trees, and
@ -288,24 +328,23 @@ GIT Glossary
[[def_refspec]]refspec::
A <<def_refspec,refspec>> is used by <<def_fetch,fetch>> and
<<def_push,push>> to describe the mapping between remote <<def_ref,ref>>
and local <<def_ref,ref>>. They are combined with a colon in the format
<src>:<dst>, preceded by an optional plus sign, +. For example: `git
fetch $URL refs/heads/master:refs/heads/origin` means
"grab the master <<def_branch,branch>> <<def_head,head>>
from the $URL and store it as my origin
<<def_branch,branch>> <<def_head,head>>". And `git <<def_push,push>>
$URL refs/heads/master:refs/heads/to-upstream` means
"publish my master <<def_branch,branch>>
<<def_head,head>> as to-upstream <<def_branch,branch>> at $URL". See
also gitlink:git-push[1]
<<def_push,push>> to describe the mapping between remote
<<def_ref,ref>> and local ref. They are combined with a colon in
the format <src>:<dst>, preceded by an optional plus sign, +.
For example: `git fetch $URL
refs/heads/master:refs/heads/origin` means "grab the master
<<def_branch,branch>> <<def_head,head>> from the $URL and store
it as my origin branch head". And `git push
$URL refs/heads/master:refs/heads/to-upstream` means "publish my
master branch head as to-upstream branch at $URL". See also
gitlink:git-push[1]
[[def_repository]]repository::
A collection of refs together with an <<def_object_database,object
database>> containing all objects which are <<def_reachable,reachable>>
from the refs, possibly accompanied by meta data from one or more
porcelains. A <<def_repository,repository>> can share an
<<def_object_database,object database>> with other repositories.
A collection of refs together with an
<<def_object_database,object database>> containing all objects
which are <<def_reachable,reachable>> from the refs, possibly
accompanied by meta data from one or more porcelains. A
repository can share an object database with other repositories.
[[def_resolve]]resolve::
The action of fixing up manually what a failed automatic
@ -327,36 +366,37 @@ GIT Glossary
Synonym for <<def_object_name,object name>>.
[[def_shallow_repository]]shallow repository::
A <<def_shallow_repository,shallow repository>> has an incomplete
A shallow repository has an incomplete
history some of whose commits have parents cauterized away (in other
words, git is told to pretend that these commits do not have the
parents, even though they are recorded in the <<def_commit_object,commit
object>>). This is sometimes useful when you are interested only in the
recent history of a project even though the real history recorded in the
upstream is much larger. A <<def_shallow_repository,shallow repository>>
upstream is much larger. A shallow repository
is created by giving the `--depth` option to gitlink:git-clone[1], and
its history can be later deepened with gitlink:git-fetch[1].
[[def_symref]]symref::
Symbolic reference: instead of containing the <<def_SHA1,SHA1>> id
itself, it is of the format 'ref: refs/some/thing' and when
referenced, it recursively dereferences to this reference. 'HEAD' is a
prime example of a <<def_symref,symref>>. Symbolic references are
manipulated with the gitlink:git-symbolic-ref[1] command.
Symbolic reference: instead of containing the <<def_SHA1,SHA1>>
id itself, it is of the format 'ref: refs/some/thing' and when
referenced, it recursively dereferences to this reference.
'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic
references are manipulated with the gitlink:git-symbolic-ref[1]
command.
[[def_tag]]tag::
A <<def_ref,ref>> pointing to a <<def_tag,tag>> or
A <<def_ref,ref>> pointing to a tag or
<<def_commit_object,commit object>>. In contrast to a <<def_head,head>>,
a tag is not changed by a <<def_commit,commit>>. Tags (not
<<def_tag_object,tag objects>>) are stored in `$GIT_DIR/refs/tags/`. A
git tag has nothing to do with a Lisp tag (which would be
called an <<def_object_type,object type>> in git's context). A
tag is most typically used to mark a particular point in the
<<def_commit,commit>> ancestry <<def_chain,chain>>.
commit ancestry <<def_chain,chain>>.
[[def_tag_object]]tag object::
An <<def_object,object>> containing a <<def_ref,ref>> pointing to
another <<def_object,object>>, which can contain a message just like a
another object, which can contain a message just like a
<<def_commit_object,commit object>>. It can also contain a (PGP)
signature, in which case it is called a "signed <<def_tag_object,tag
object>>".
@ -370,16 +410,16 @@ GIT Glossary
[[def_tracking_branch]]tracking branch::
A regular git <<def_branch,branch>> that is used to follow changes from
another <<def_repository,repository>>. A <<def_tracking_branch,tracking
branch>> should not contain direct modifications or have local commits
made to it. A <<def_tracking_branch,tracking branch>> can usually be
another <<def_repository,repository>>. A tracking
branch should not contain direct modifications or have local commits
made to it. A tracking branch can usually be
identified as the right-hand-side <<def_ref,ref>> in a Pull:
<<def_refspec,refspec>>.
[[def_tree]]tree::
Either a <<def_working_tree,working tree>>, or a <<def_tree_object,tree
object>> together with the dependent blob and <<def_tree,tree>> objects
(i.e. a stored representation of a <<def_working_tree,working tree>>).
object>> together with the dependent blob and tree objects
(i.e. a stored representation of a working tree).
[[def_tree_object]]tree object::
An <<def_object,object>> containing a list of file names and modes along
@ -389,8 +429,7 @@ GIT Glossary
[[def_tree-ish]]tree-ish::
A <<def_ref,ref>> pointing to either a <<def_commit_object,commit
object>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag
object>> pointing to a <<def_tag,tag>> or <<def_commit,commit>> or
<<def_tree_object,tree object>>.
object>> pointing to a tag or commit or tree object.
[[def_unmerged_index]]unmerged index::
An <<def_index,index>> which contains unmerged
@ -401,5 +440,6 @@ GIT Glossary
<<def_branch,branch>>, <<def_tag,tag>>, or any other reference.
[[def_working_tree]]working tree::
The set of files and directories currently being worked on, i.e. you can
work in your <<def_working_tree,working tree>> without using git at all.
The tree of actual checked out files. The working tree is
normally equal to the <<def_HEAD,HEAD>> plus any local changes
that you have made but not yet committed.

109
Documentation/howto/dangling-objects.txt
View File

@ -1,109 +0,0 @@
From: Linus Torvalds <torvalds@linux-foundation.org>
Subject: Re: Question about fsck-objects output
Date: Thu, 25 Jan 2007 12:01:06 -0800 (PST)
Message-ID: <Pine.LNX.4.64.0701251144290.25027@woody.linux-foundation.org>
Archived-At: <http://permalink.gmane.org/gmane.comp.version-control.git/37754>
Abstract: Linus describes what dangling objects are, when they
are left behind, and how to view their relationship with branch
heads in gitk
On Thu, 25 Jan 2007, Larry Streepy wrote:
> Sorry to ask such a basic question, but I can't quite decipher the output of
> fsck-objects. When I run it, I get this:
>
> git fsck-objects
> dangling commit 2213f6d4dd39ca8baebd0427723723e63208521b
> dangling commit f0d4e00196bd5ee54463e9ea7a0f0e8303da767f
> dangling blob 6a6d0b01b3e96d49a8f2c7addd4ef8c3bd1f5761
>
>
> Even after a "repack -a -d" they still exist. The man page has a short
> explanation, but, at least for me, it wasn't fully enlightening. :-)
>
> The man page says that dangling commits could be "root" commits, but since my
> repo started as a clone of another repo, I don't see how I could have any root
> commits. Also, the page doesn't really describe what a dangling blob is.
>
> So, can someone explain what these artifacts are and if they are a problem
> that I should be worried about?
The most common situation is that you've rebased a branch (or you have
pulled from somebody else who rebased a branch, like the "pu" branch in
the git.git archive itself).
What happens is that the old head of the original branch still exists, as
does obviously everything it pointed to. The branch pointer itself just
doesn't, since you replaced it with another one.
However, there are certainly other situations too that cause dangling
objects. For example, the "dangling blob" situation you have tends to be
because you did a "git add" of a file, but then, before you actually
committed it and made it part of the bigger picture, you changed something
else in that file and committed that *updated* thing - the old state that
you added originally ends up not being pointed to by any commit/tree, so
it's now a dangling blob object.
Similarly, when the "recursive" merge strategy runs, and finds that there
are criss-cross merges and thus more than one merge base (which is fairly
unusual, but it does happen), it will generate one temporary midway tree
(or possibly even more, if you had lots of criss-crossing merges and
more than two merge bases) as a temporary internal merge base, and again,
those are real objects, but the end result will not end up pointing to
them, so they end up "dangling" in your repository.
Generally, dangling objects aren't anything to worry about. They can even
be very useful: if you screw something up, the dangling objects can be how
you recover your old tree (say, you did a rebase, and realized that you
really didn't want to - you can look at what dangling objects you have,
and decide to reset your head to some old dangling state).
For commits, the most useful thing to do with dangling objects tends to be
to do a simple
gitk <dangling-commit-sha-goes-here> --not --all
which means exactly what it sounds like: it says that you want to see the
commit history that is described by the dangling commit(s), but you do NOT
want to see the history that is described by all your branches and tags
(which are the things you normally reach). That basically shows you in a
nice way what the danglign commit was (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 has gotten
dropped - rebasing will do that).
For blobs and trees, you can't do the same, but you can examine them. You
can just do
git show <dangling-blob/tree-sha-goes-here>
to show what the contents of the blob were (or, for a tree, basically what
the "ls" for that directory was), and that may give you some idea of what
the operation was that left that dangling object.
Usually, dangling blobs and trees aren't very interesting. They're almost
always the result of either being a half-way mergebase (the blob will
often even have the conflict markers from a merge in it, if you have had
conflicting merges that you fixed up by hand), or simply because you
interrupted a "git fetch" with ^C or something like that, leaving _some_
of the new objects in the object database, but just dangling and useless.
Anyway, once you are sure that you're not interested in any dangling
state, you can just prune all unreachable objects:
git prune
and they'll be gone. But you should only run "git prune" on a quiescent
repository - it's kind of like doing a filesystem fsck recovery: you don't
want to do that while the filesystem is mounted.
(The same is true of "git-fsck-objects" itself, btw - but since
git-fsck-objects never actually *changes* the repository, it just reports
on what it found, git-fsck-objects itself is never "dangerous" to run.
Running it while somebody is actually changing the repository can cause
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).
Linus

65
Documentation/howto/isolate-bugs-with-bisect.txt
View File

@ -1,65 +0,0 @@
From: Linus Torvalds <torvalds () osdl ! org>
To: git@vger.kernel.org
Date: 2005-11-08 1:31:34
Subject: Real-life kernel debugging scenario
Abstract: Short-n-sweet, Linus tells us how to leverage `git-bisect` to perform
bug isolation on a repository where "good" and "bad" revisions are known
in order to identify a suspect commit.
How To Use git-bisect To Isolate a Bogus Commit
===============================================
The way to use "git bisect" couldn't be easier.
Figure out what the oldest bad state you know about is (that's usually the
head of "master", since that's what you just tried to boot and failed at).
Also, figure out the most recent known-good commit (usually the _previous_
kernel you ran: and if you've only done a single "pull" in between, it
will be ORIG_HEAD).
Then do
git bisect start
git bisect bad master <- mark "master" as the bad state
git bisect good ORIG_HEAD <- mark ORIG_HEAD as good (or
whatever other known-good
thing you booted last)
and at this point "git bisect" will churn for a while, and tell you what
the mid-point between those two commits are, and check that state out as
the head of the new "bisect" branch.
Compile and reboot.
If it's good, just do
git bisect good <- mark current head as good
otherwise, reboot into a good kernel instead, and do (surprise surprise,
git really is very intuitive):
git bisect bad <- mark current head as bad
and whatever you do, git will select a new half-way point. Do this for a
while, until git tells you exactly which commit was the first bad commit.
That's your culprit.
It really works wonderfully well, except for the case where there was
_another_ commit that broke something in between, like introduced some
stupid compile error. In that case you should not mark that commit good or
bad: you should try to find another commit close-by, and do a "git reset
--hard <newcommit>" to try out _that_ commit instead, and then test that
instead (and mark it good or bad).
You can do "git bisect visualize" while you do all this to see what's
going on by starting up gitk on the bisection range.
Finally, once you've figured out exactly which commit was bad, you can
then go back to the master branch, and try reverting just that commit:
git checkout master
git revert <bad-commit-id>
to verify that the top-of-kernel works with that single commit reverted.

52
Documentation/howto/make-dist.txt
View File

@ -1,52 +0,0 @@
Date: Fri, 12 Aug 2005 22:39:48 -0700 (PDT)
From: Linus Torvalds <torvalds@osdl.org>
To: Dave Jones <davej@redhat.com>
cc: git@vger.kernel.org
Subject: Re: Fwd: Re: git checkout -f branch doesn't remove extra files
Abstract: In this article, Linus talks about building a tarball,
incremental patch, and ChangeLog, given a base release and two
rc releases, following the convention of giving the patch from
the base release and the latest rc, with ChangeLog between the
last rc and the latest rc.
On Sat, 13 Aug 2005, Dave Jones wrote:
>
> > Git actually has a _lot_ of nifty tools. I didn't realize that people
> > didn't know about such basic stuff as "git-tar-tree" and "git-ls-files".
>
> Maybe its because things are moving so fast :) Or maybe I just wasn't
> paying attention on that day. (I even read the git changes via RSS,
> so I should have no excuse).
Well, git-tar-tree has been there since late April - it's actually one of
those really early commands. I'm pretty sure the RSS feed came later ;)
I use it all the time in doing releases, it's a lot faster than creating a
tar tree by reading the filesystem (even if you don't have to check things
out). A hidden pearl.
This is my crappy "release-script":
[torvalds@g5 ~]$ cat bin/release-script
#!/bin/sh
stable="$1"
last="$2"
new="$3"
echo "# git-tag v$new"
echo "git-tar-tree v$new linux-$new | gzip -9 > ../linux-$new.tar.gz"
echo "git-diff-tree -p v$stable v$new | gzip -9 > ../patch-$new.gz"
echo "git-rev-list --pretty v$new ^v$last > ../ChangeLog-$new"
echo "git-rev-list --pretty=short v$new ^v$last | git-shortlog > ../ShortLog"
echo "git-diff-tree -p v$last v$new | git-apply --stat > ../diffstat-$new"
and when I want to do a new kernel release I literally first tag it, and
then do
release-script 2.6.12 2.6.13-rc6 2.6.13-rc7
and check that things look sane, and then just cut-and-paste the commands.
Yeah, it's stupid.
Linus

296
Documentation/howto/using-topic-branches.txt
View File

@ -1,296 +0,0 @@
Date: Mon, 15 Aug 2005 12:17:41 -0700
From: tony.luck@intel.com
Subject: Some tutorial text (was git/cogito workshop/bof at linuxconf au?)
Abstract: In this article, Tony Luck discusses how he uses GIT
as a Linux subsystem maintainer.
Here's something that I've been putting together on how I'm using
GIT as a Linux subsystem maintainer.
-Tony
Last updated w.r.t. GIT 1.1
Linux subsystem maintenance using GIT
-------------------------------------
My requirements here are to be able to create two public trees:
1) 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.
2) 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.)
Note that the period of time that each patch spends in the "test" tree
is dependent on the complexity of the change. Since GIT does not support
cherry picking, it is not practical to simply apply all patches to the
test tree and then pull to the release tree as that would leave trivial
patches blocked in the test tree waiting for complex changes to accumulate
enough test time to graduate.
Back in the BitKeeper days I achieved this by creating small forests of
temporary trees, one tree for each logical grouping of patches, and then
pulling changes from these trees first to the test tree, and then to the
release tree. At first I replicated this in GIT, but then I realised
that I could so this far more efficiently using branches inside a single
GIT repository.
So here is the step-by-step guide how this all works for me.
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
Change directory into the cloned tree you just created
$ cd work
Set up a remotes file so that you can fetch the latest from Linus' master
branch into a local branch named "linus":
$ cat > .git/remotes/linus
URL: git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
Pull: master:linus
^D
and create the linus branch:
$ git branch linus
The "linus" branch will be used to track the upstream kernel. To update it,
you simply run:
$ git fetch linus
you can do this frequently (and it should be safe to do so with pending
work in your tree, but perhaps not if you are in mid-merge).
If you need to keep track of other public trees, you can add remote branches
for them too:
$ git branch another
$ cat > .git/remotes/another
URL: ... insert URL here ...
Pull: name-of-branch-in-this-remote-tree:another
^D
and run:
$ git fetch another
Now create the branches in which you are going to work, these start
out at the current tip of the linus branch.
$ git branch test linus
$ git branch release linus
These can be easily kept up to date by merging from the "linus" branch:
$ git checkout test && git merge "Auto-update from upstream" test linus
$ git checkout release && git merge "Auto-update from upstream" release linus
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.
Set up so that you can push upstream to your public tree (you need to
log-in to the remote system and create an empty tree there before the
first push).
$ cat > .git/remotes/mytree
URL: master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
Push: release
Push: test
^D
and the push both the test and release trees using:
$ git push mytree
or push just one of the test and release branches using:
$ git push mytree test
or
$ 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 the
linus branch:
$ git checkout -b speed-up-spinlocks linus
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 merge "Pull speed-up-spinlock changes" test 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 merge "Pull speed-up-spinlock changes" release 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-whatchanged branchname ^linus | git-shortlog
To see whether it has already been merged into the test or release branches
use:
$ git-rev-list branchname ^test
or
$ git-rev-list branchname ^release
[If this branch has not yet been merged you will see a set of SHA1 values
for the commits, 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 "linus" branch)
the branch for this change is no longer needed. You detect this when the
output from:
$ git-rev-list branchname ^linus
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-whatchanged -p release ^linus | diffstat -p1
and
$ git-whatchanged release ^linus | git-shortlog
Here are some of the scripts that I use to simplify all this even further.
==== update script ====
# Update a branch in my GIT tree. If the branch to be updated
# is "linus", then pull from kernel.org. Otherwise merge local
# linus branch into test|release branch
case "$1" in
test|release)
git checkout $1 && git merge "Auto-update from upstream" $1 linus
;;
linus)
before=$(cat .git/refs/heads/linus)
git fetch linus
after=$(cat .git/refs/heads/linus)
if [ $before != $after ]
then
git-whatchanged $after ^$before | git-shortlog
fi
;;
*)
echo "Usage: $0 linus|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-rev-list $1 ^$2 | wc -c) -eq 0 ]
then
echo $1 already merged into $2 1>&2
exit 1
fi
git checkout $2 && git merge "Pull $1 into $2 branch" $2 $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 release ^test | wc -c` -gt 0 ]
then
echo $rb Warning: commits in release that are not in test $restore
git-whatchanged release ^test
fi
for branch in `ls .git/refs/heads`
do
if [ $branch = linus -o $branch = test -o $branch = release ]
then
continue
fi
echo -n $gb ======= $branch ====== $restore " "
status=
for ref in test release linus
do
if [ `git-rev-list $branch ^$ref | 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-whatchanged $branch ^linus | git-shortlog
done

1192
Documentation/user-manual.txt
View File

@ -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.
<<repositories-and-branches>> and <<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.
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
<<Developing-with-git>> and <<sharing-development>>.
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
===============
See also <<git-quick-start>> for a brief overview of git commands,
without any explanation.
This is a quick summary of the major commands; the following chapters
will explain how these work in more detail.
Also, see <<todo>> for ways that you can help make this manual more
complete.
[[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
-----------------------------------------------
[[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,6 +830,96 @@ 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
gitlink: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 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
@ -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 "<<getting-updates-with-git-pull, Getting
updates with git pull>>".
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, 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 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
"<<pushing-changes-to-a-public-repository,Pushing changes to a public
repository>>", 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
<<exporting-via-http,http>> or <<exporting-via-git,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
@ -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.txt[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 <<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 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
<<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
gitlink:git-push[1]:
-------------------------------------------------
$ git push mytree
-------------------------------------------------
or push just one of the test and release branches using:
-------------------------------------------------
$ git push mytree test
-------------------------------------------------
or
-------------------------------------------------
$ 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
-------------------------------------------------
or
-------------------------------------------------
$ 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
-------------------------------------------------
[[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 <<def_commit_object,commit>>.
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 <<naming-commits>>.
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_<bla>`, typically defined in `builtin-<bla>.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|<type>] <sha1>");
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.