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

* '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

Documentation/glossary.txt

@@ -2,12 +2,12 @@ GIT Glossary
 ============
 
 [[def_alternate_object_database]]alternate object database::
-	Via the alternates mechanism, a <<def_repository,repository>> can
+	Via the alternates mechanism, a <<def_repository,repository>>
-	inherit part of its <<def_object_database,object database>> from another
+	can inherit part of its <<def_object_database,object database>>
-	<<def_object_database,object database>>, which is called "alternate".
+	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
+	A "branch" is an active line of development.  The most recent
-	particular <<def_revision,revision>>, which is called the
+	<<def_commit,commit>> on a branch is referred to as the tip of
-	branch <<def_head,head>>. The heads
+	that branch.  The tip of the branch is referenced by a branch
-	are stored in `$GIT_DIR/refs/heads/`.
+	<<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
+	As a noun: A single point in the
-	<<def_index,index>> in the <<def_object_database,object database>>. The
+	git history; the entire history of a project is represented as a
-	result is a <<def_revision,revision>>. As a noun: Short hand for
+	set of interrelated commits.  The word "commit" is often
-	<<def_commit_object,commit object>>.
+	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
+	branch's <<def_head_ref,head ref>> from a remote
-	<<def_repository,repository>>, to find out which objects are missing
+	<<def_repository,repository>>, to find out which objects are
-	from the local <<def_object_database,object database>>, and to get them,
+	missing from the local <<def_object_database,object database>>,
-	too.
+	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
+	A named reference to the <<def_commit,commit>> at the tip of a
-	corresponding <<def_commit_object,commit object>>.
+	<<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
+	A synonym for <<def_head,head>>.
-	abbreviated to "<<def_head,head>>". Head refs are stored in
-	`$GIT_DIR/refs/heads/`.
 
 [[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,
+	<<def_index,index>>. An index entry can be unmerged, if a
-	if a <<def_merge,merge>> was started, but not yet finished (i.e. if the
+	<<def_merge,merge>> was started, but not yet finished (i.e. if
-	<<def_index,index>> contains multiple versions of that file).
+	the index contains multiple versions of that file).
 
 [[def_master]]master::
-	The default development <<def_branch,branch>>. Whenever you create a git
+	The default development <<def_branch,branch>>. Whenever you
-	<<def_repository,repository>>, a <<def_branch,branch>> named
+	create a git <<def_repository,repository>>, a branch named
-	"<<def_master,master>>" is created, and becomes the active
+	"master" is created, and becomes the active branch. In most
-	<<def_branch,branch>>. In most cases, this contains the local
+	cases, this contains the local development, though that is
-	development, though that is purely conventional and not required.
+	purely by convention and is not required.
 
 [[def_merge]]merge::
-	To <<def_merge,merge>> branches means to try to accumulate the changes
+	As a verb: To bring the contents of another
-	since a common ancestor and apply them to the first
+	<<def_branch,branch>> (possibly from an external
-	<<def_branch,branch>>. An automatic <<def_merge,merge>> uses heuristics
+	<<def_repository,repository>>) into the current branch.  In the
-	to accomplish that. Evidently, an automatic <<def_merge,merge>> can
+	case where the merged-in branch is from a different repository,
-	fail.
+	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
+	find out if it is an ancestor to the branch's local
-	<<def_head_ref,head ref>> is a direct, and in that case, putting all
+	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
+	head ref, and which are missing from the remote
-	<<def_repository,repository>>, into 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
+	head ref. If the remote <<def_head,head>> is not an
-	ancestor to the local <<def_head,head>>, the <<def_push,push>> fails.
+	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
+	"reachable" from that commit. More
-	generally, one <<def_object,object>> is <<def_reachable,reachable>> from
+	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>>
+	<<def_push,push>> to describe the mapping between remote
-	and local <<def_ref,ref>>. They are combined with a colon in the format
+	<<def_ref,ref>> and local ref. They are combined with a colon in
-	<src>:<dst>, preceded by an optional plus sign, +. For example: `git
+	the format <src>:<dst>, preceded by an optional plus sign, +.
-	fetch $URL refs/heads/master:refs/heads/origin` means
+	For example: `git fetch $URL
-	"grab the master <<def_branch,branch>> <<def_head,head>>
+	refs/heads/master:refs/heads/origin` means "grab the master
-	from the $URL and store it as my origin
+	<<def_branch,branch>> <<def_head,head>> from the $URL and store
-	<<def_branch,branch>> <<def_head,head>>". And `git <<def_push,push>>
+	it as my origin branch head". And `git push
-	$URL refs/heads/master:refs/heads/to-upstream` means
+	$URL refs/heads/master:refs/heads/to-upstream` means "publish my
-	"publish my master <<def_branch,branch>>
+	master branch head as to-upstream branch at $URL". See also
-	<<def_head,head>> as to-upstream <<def_branch,branch>> at $URL". See
+	gitlink:git-push[1]
-	also gitlink:git-push[1]
 
 [[def_repository]]repository::
-	A collection of refs together with an <<def_object_database,object
+	A collection of refs together with an
-	database>> containing all objects which are <<def_reachable,reachable>>
+	<<def_object_database,object database>> containing all objects
-	from the refs, possibly accompanied by meta data from one or more
+	which are <<def_reachable,reachable>> from the refs, possibly
-	porcelains. A <<def_repository,repository>> can share an
+	accompanied by meta data from one or more porcelains. A
-	<<def_object_database,object database>> with other repositories.
+	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
+	Symbolic reference: instead of containing the <<def_SHA1,SHA1>>
-	itself, it is of the format 'ref: refs/some/thing' and when
+	id itself, it is of the format 'ref: refs/some/thing' and when
-	referenced, it recursively dereferences to this reference. 'HEAD' is a
+	referenced, it recursively dereferences to this reference.
-	prime example of a <<def_symref,symref>>. Symbolic references are
+	'<<def_HEAD,HEAD>>' is a prime example of a symref. Symbolic
-	manipulated with the gitlink:git-symbolic-ref[1] command.
+	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
+	another <<def_repository,repository>>. A tracking
-	branch>> should not contain direct modifications or have local commits
+	branch should not contain direct modifications or have local commits
-	made to it. A <<def_tracking_branch,tracking branch>> can usually be
+	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
+	object>> together with the dependent blob and tree objects
-	(i.e. a stored representation of a <<def_working_tree,working tree>>).
+	(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
+	object>> pointing to a tag or commit or tree object.
-	<<def_tree_object,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
+	The tree of actual checked out files.  The working tree is
-	work in your <<def_working_tree,working tree>> without using git at all.
+	normally equal to the <<def_HEAD,HEAD>> plus any local changes
+	that you have made but not yet committed.

Documentation/howto/dangling-objects.txt

@@ -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
-

Documentation/howto/isolate-bugs-with-bisect.txt

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

Documentation/howto/make-dist.txt

@@ -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
-

Documentation/howto/using-topic-branches.txt

@@ -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