Merge branch 'maint'

* maint:
  Have sample update hook not refuse deleting a branch through push.
  variable $projectdesc needs to be set before checking against unchanged default.
  Update git-annotate/git-blame documentation
  Update git-apply documentation
  Update git-applymbox documentation
  Update git-am documentation
  user-manual: use detached head when rewriting history
  user-manual: start revising "internals" chapter
  user-manual: detached HEAD
  user-manual: fix discussion of default clone
  Documentation: clarify track/no-track option.
  Documentation: clarify git-checkout -f, minor editing
  Documentation: minor edits of git-lost-found manpage

Documentation/blame-options.txt

@@ -0,0 +1,67 @@
+-b::
+	Show blank SHA-1 for boundary commits.  This can also
+	be controlled via the `blame.blankboundary` config option.
+
+--root::
+	Do not treat root commits as boundaries.  This can also be
+	controlled via the `blame.showroot` config option.
+
+--show-stats::
+	Include additional statistics at the end of blame output.
+
+-L n,m::
+	Annotate only the specified line range (lines count from 1).
+
+-l::
+	Show long rev (Default: off).
+
+-t::
+	Show raw timestamp (Default: off).
+
+-S <revs-file>::
+	Use revs from revs-file instead of calling gitlink:git-rev-list[1].
+
+-p, --porcelain::
+	Show in a format designed for machine consumption.
+
+--incremental::
+	Show the result incrementally in a format designed for
+	machine consumption.
+
+--contents <file>::
+	When <rev> is not specified, the command annotates the
+	changes starting backwards from the working tree copy.
+	This flag makes the command pretend as if the working
+	tree copy has the contents of he named file (specify
+	`-` to make the command read from the standard input).
+
+-M|<num>|::
+	Detect moving lines in the file as well.  When a commit
+	moves a block of lines in a file (e.g. the original file
+	has A and then B, and the commit changes it to B and
+	then A), traditional 'blame' algorithm typically blames
+	the lines that were moved up (i.e. B) to the parent and
+	assigns blame to the lines that were moved down (i.e. A)
+	to the child commit.  With this option, both groups of lines
+	are blamed on the parent.
+
+	<num> is optional but it is the lower bound on the number of
+	alphanumeric characters that git must detect as moving
+	within a file for it to associate those lines with the parent
+	commit.
+
+-C|<num>|::
+	In addition to `-M`, detect lines copied from other
+	files that were modified in the same commit.  This is
+	useful when you reorganize your program and move code
+	around across files.  When this option is given twice,
+	the command looks for copies from all other files in the
+	parent for the commit that creates the file in addition.
+
+	<num> is optional but it is the lower bound on the number of
+	alphanumeric characters that git must detect as moving
+	between files for it to associate those lines with the parent
+	commit.
+
+-h, --help::
+	Show help message.

Documentation/git-am.txt

@@ -26,18 +26,18 @@ OPTIONS
 	The list of mailbox files to read patches from. If you do not
 	supply this argument, reads from the standard input.
 
---signoff::
+-s, --signoff::
 	Add `Signed-off-by:` line to the commit message, using
 	the committer identity of yourself.
 
---dotest=<dir>::
+-d=<dir>, --dotest=<dir>::
 	Instead of `.dotest` directory, use <dir> as a working
 	area to store extracted patches.
 
---keep::
+-k, --keep::
 	Pass `-k` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 
---utf8::
+-u, --utf8::
 	Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 	The proposed commit log message taken from the e-mail
 	are re-coded into UTF-8 encoding (configuration variable
@@ -48,14 +48,14 @@ This was optional in prior versions of git, but now it is the
 default.   You could use `--no-utf8` to override this.
 
 --no-utf8::
-	Do not pass `-u` flag to `git-mailinfo` (see
+	Pass `-n` flag to `git-mailinfo` (see
 	gitlink:git-mailinfo[1]).
 
---binary::
+-b, --binary::
 	Pass `--allow-binary-replacement` flag to `git-apply`
 	(see gitlink:git-apply[1]).
 
---3way::
+-3, --3way::
 	When the patch does not apply cleanly, fall back on
 	3-way merge, if the patch records the identity of blobs
 	it is supposed to apply to, and we have those blobs
@@ -73,10 +73,10 @@ default.   You could use `--no-utf8` to override this.
 	These flags are passed to the `git-apply` program that applies
 	the patch.
 
---interactive::
+-i, --interactive::
 	Run interactively, just like git-applymbox.
 
---resolved::
+-r, --resolved::
 	After a patch failure (e.g. attempting to apply
 	conflicting patch), the user has applied it by hand and
 	the index file stores the result of the application.
@@ -84,6 +84,13 @@ default.   You could use `--no-utf8` to override this.
 	extracted from the e-mail message and the current index
 	file, and continue.
 
+--resolvemsg=<msg>::
+	When a patch failure occurs, <msg> will be printed
+	to the screen before exiting.  This overrides the
+	standard message informing you to use `--resolved`
+	or `--skip` to handle the failure.  This is solely
+	for internal use between `git-rebase` and `git-am`.
+
 DISCUSSION
 ----------
 

Documentation/git-annotate.txt

@@ -16,20 +16,7 @@ which introduced the line. Optionally annotate from a given revision.
 
 OPTIONS
 -------
--l, --long::
+include::blame-options.txt[]
-	Show long rev (Defaults off).
-
--t, --time::
-	Show raw timestamp (Defaults off).
-
--r, --rename::
-	Follow renames (Defaults on).
-
--S, --rev-file <revs-file>::
-	Use revs from revs-file instead of calling git-rev-list.
-
--h, --help::
-	Show help message.
 
 SEE ALSO
 --------

Documentation/git-apply.txt

@@ -9,11 +9,12 @@ git-apply - Apply a patch on a git index file and a working tree
 SYNOPSIS
 --------
 [verse]
-'git-apply' [--stat] [--numstat] [--summary] [--check] [--index] [--apply]
+'git-apply' [--stat] [--numstat] [--summary] [--check] [--index]
-	  [--no-add] [--index-info] [--allow-binary-replacement | --binary]
+	  [--apply] [--no-add] [--index-info] [-R | --reverse]
-	  [-R | --reverse] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof]
+	  [--allow-binary-replacement | --binary] [--reject] [-z]
-	  [--whitespace=<nowarn|warn|error|error-all|strip>] [--exclude=PATH]
+	  [-pNUM] [-CNUM] [--inaccurate-eof] [--cached]
-	  [--cached] [--verbose] [<patch>...]
+	  [--whitespace=<nowarn|warn|error|error-all|strip>]
+	  [--exclude=PATH] [--verbose] [<patch>...]
 
 DESCRIPTION
 -----------
@@ -158,7 +159,7 @@ discouraged.
 	correctly. This option adds support for applying such patches by
 	working around this bug.
 
---verbose::
+-v, --verbose::
 	Report progress to stderr. By default, only a message about the
 	current patch being applied will be printed. This option will cause
 	additional information to be reported.

Documentation/git-applymbox.txt

@@ -42,14 +42,20 @@ OPTIONS
 	and the current tree.
 
 -u::
-	The commit log message, author name and author email are
+	Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
-	taken from the e-mail, and after minimally decoding MIME
+	The proposed commit log message taken from the e-mail
-	transfer encoding, re-coded in UTF-8 by transliterating
+	are re-coded into UTF-8 encoding (configuration variable
-	them.  This used to be optional but now it is the default.
+	`i18n.commitencoding` can be used to specify project's
+	preferred encoding if it is not UTF-8).  This used to be
+	optional but now it is the default.
 +
 Note that the patch is always used as-is without charset
 conversion, even with this flag.
 
+-n::
+	Pass `-n` flag to `git-mailinfo` (see
+	gitlink:git-mailinfo[1]).
+
 -c .dotest/<num>::
 	When the patch contained in an e-mail does not cleanly
 	apply, the command exits with an error message. The

Documentation/git-blame.txt

@@ -8,8 +8,9 @@ git-blame - Show what revision and author last modified each line of a file
 SYNOPSIS
 --------
 [verse]
-'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>]
+'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m]
-            [-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file>
+            [-S <revs-file>] [-M] [-C] [-C] [--since=<date>]
+            [<rev> | --contents <file>] [--] <file>
 
 DESCRIPTION
 -----------
@@ -37,20 +38,19 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
 
 OPTIONS
 -------
--c, --compatibility::
+include::blame-options.txt[]
+
+-c::
 	Use the same output mode as gitlink:git-annotate[1] (Default: off).
 
--L n,m::
+--score-debug::
-	Annotate only the specified line range (lines count from 1).
+	Include debugging information related to the movement of
-
+	lines between files (see `-C`) and lines moved within a
--l, --long::
+	file (see `-M`).  The first number listed is the score.
-	Show long rev (Default: off).
+	This is the number of alphanumeric characters detected
-
+	to be moved between or within files.  This must be above
--t, --time::
+	a certain threshold for git-blame to consider those lines
-	Show raw timestamp (Default: off).
+	of code to have been moved.
-
--S, --rev-file <revs-file>::
-	Use revs from revs-file instead of calling gitlink:git-rev-list[1].
 
 -f, --show-name::
 	Show filename in the original commit.  By default
@@ -60,42 +60,6 @@ OPTIONS
 -n, --show-number::
 	Show line number in the original commit (Default: off).
 
--p, --porcelain::
-	Show in a format designed for machine consumption.
-
---incremental::
-	Show the result incrementally in a format designed for
-	machine consumption.
-
---contents <file>::
-	When <rev> is not specified, the command annotates the
-	changes starting backwards from the working tree copy.
-	This flag makes the command pretend as if the working
-	tree copy has the contents of he named file (specify
-	`-` to make the command read from the standard input).
-
--M::
-	Detect moving lines in the file as well.  When a commit
-	moves a block of lines in a file (e.g. the original file
-	has A and then B, and the commit changes it to B and
-	then A), traditional 'blame' algorithm typically blames
-	the lines that were moved up (i.e. B) to the parent and
-	assigns blame to the lines that were moved down (i.e. A)
-	to the child commit.  With this option, both groups of
-	lines are blamed on the parent.
-
--C::
-	In addition to `-M`, detect lines copied from other
-	files that were modified in the same commit.  This is
-	useful when you reorganize your program and move code
-	around across files.  When this option is given twice,
-	the command looks for copies from all other files in the
-	parent for the commit that creates the file in addition.
-
--h, --help::
-	Show help message.
-
-
 THE PORCELAIN FORMAT
 --------------------
 

Documentation/git-checkout.txt

@@ -23,9 +23,9 @@ options, which will be passed to `git branch`.
 
 When <paths> are given, this command does *not* switch
 branches.  It updates the named paths in the working tree from
-the index file (i.e. it runs `git-checkout-index -f -u`), or a
+the index file (i.e. it runs `git-checkout-index -f -u`), or
-named commit.  In
+from a named commit.  In
-this case, `-f` and `-b` options are meaningless and giving
+this case, the `-f` and `-b` options are meaningless and giving
 either of them results in an error.  <tree-ish> argument can be
 used to specify a specific tree-ish (i.e. commit, tag or tree)
 to update the index for the given paths before updating the
@@ -38,7 +38,8 @@ OPTIONS
 	Quiet, supress feedback messages.
 
 -f::
-	Force a re-read of everything.
+	Proceed even if the index or the working tree differs
+	from HEAD.  This is used to throw away local changes.
 
 -b::
 	Create a new branch named <new_branch> and start it at
@@ -48,13 +49,17 @@ OPTIONS
 
 --track::
 	When -b is given and a branch is created off a remote branch,
-	setup so that git-pull will automatically retrieve data from
+	set up configuration so that git-pull will automatically
-	the remote branch.
+	retrieve data from the remote branch.  Set the
+	branch.autosetupmerge configuration variable to true if you
+	want git-checkout and git-branch to always behave as if
+	'--track' were given.
 
 --no-track::
 	When -b is given and a branch is created off a remote branch,
-	force that git-pull will automatically retrieve data from
+	set up configuration so that git-pull will not retrieve data
-	the remote branch independent of the configuration settings.
+	from the remote branch, ignoring the branch.autosetupmerge
+	configuration variable.
 
 -l::
 	Create the new branch's ref log.  This activates recording of

Documentation/git-lost-found.txt

@@ -12,23 +12,22 @@ SYNOPSIS
 DESCRIPTION
 -----------
 Finds dangling commits and tags from the object database, and
-creates refs to them in .git/lost-found/ directory.  Commits and
+creates refs to them in the .git/lost-found/ directory.  Commits and
-tags that dereference to commits go to .git/lost-found/commit
+tags that dereference to commits are stored in .git/lost-found/commit,
-and others are stored in .git/lost-found/other directory.
+and other objects are stored in .git/lost-found/other.
 
 
 OUTPUT
 ------
-One line description from the commit and tag found along with
+Prints to standard output the object names and one-line descriptions
-their object name are printed on the standard output.
+of any commits or tags found.
-
 
 EXAMPLE
 -------
 
-Suppose you run 'git tag -f' and mistyped the tag to overwrite.
+Suppose you run 'git tag -f' and mistype the tag to overwrite.
 The ref to your tag is overwritten, but until you run 'git
-prune', it is still there.
+prune', the tag itself is still there.
 
 ------------
 $ git lost-found
@@ -36,15 +35,15 @@ $ git lost-found
 ...
 ------------
 
-Also you can use gitk to browse how they relate to each other
+Also you can use gitk to browse how any tags found relate to each
-and existing (probably old) tags.
+other.
 
 ------------
 $ gitk $(cd .git/lost-found/commit && echo ??*)
 ------------
 
-After making sure that it is the object you are looking for, you
+After making sure you know which the object is the tag you are looking
-can reconnect it to your regular .git/refs hierarchy.
+for, you can reconnect it to your regular .git/refs hierarchy.
 
 ------------
 $ git cat-file -t 1ef2b196

Documentation/user-manual.txt

@@ -298,9 +298,9 @@ $ git branch
 * master
 ------------------------------------------------
 
-A freshly cloned repository contains a single branch head, named
+A freshly cloned repository contains a single branch head, by default
-"master", and working directory is initialized to the state of
+named "master", with the working directory initialized to the state of
-the project referred to by "master".
+the project referred to by that branch head.
 
 Most projects also use <<def_tag,tags>>.  Tags, like heads, are
 references into the project's history, and can be listed using the
@@ -495,8 +495,49 @@ git checkout -b <new> <start-point>::
 	create a new branch <new> referencing <start-point>, and
 	check it out.
 
-It is also useful to know that the special symbol "HEAD" can always
+The special symbol "HEAD" can always be used to refer to the current
-be used to refer to the current branch.
+branch.  In fact, git uses a file named "HEAD" in the .git directory to
+remember which branch is current:
+
+------------------------------------------------
+$ cat .git/HEAD
+ref: refs/heads/master
+------------------------------------------------
+
+[[detached-head]]
+Examining an old version without creating a new branch
+------------------------------------------------------
+
+The git-checkout command normally expects a branch head, but will also
+accept an arbitrary commit; for example, you can check out the commit
+referenced by a tag:
+
+------------------------------------------------
+$ git checkout v2.6.17
+Note: moving to "v2.6.17" which isn't a local branch
+If you want to create a new branch from this checkout, you may do so
+(now or later) by using -b with the checkout command again. Example:
+  git checkout -b <new_branch_name>
+HEAD is now at 427abfa... Linux v2.6.17
+------------------------------------------------
+
+The HEAD then refers to the SHA1 of the commit instead of to a branch,
+and git branch shows that you are no longer on a branch:
+
+------------------------------------------------
+$ cat .git/HEAD
+427abfa28afedffadfca9dd8b067eb6d36bac53f
+git branch
+* (no branch)
+  master
+------------------------------------------------
+
+In this case we say that the HEAD is "detached".
+
+This can be an easy way to check out a particular version without having
+to make up a name for a new branch.  However, keep in mind that when you
+switch away from the (for example, by checking out something else), you
+can lose track of what the HEAD used to point to.
 
 Examining branches from a remote repository
 -------------------------------------------
@@ -2015,22 +2056,22 @@ $ git tag bad mywork~5
 
 (Either gitk or git-log may be useful for finding the commit.)
 
-Then check out a new branch at that commit, edit it, and rebase the rest of
+Then check out that commit, edit it, and rebase the rest of the series
-the series on top of it:
+on top of it (note that we could check out the commit on a temporary
+branch, but instead we're using a <<detached-head,detached head>>):
 
 -------------------------------------------------
-$ git checkout -b TMP bad
+$ git checkout bad
 $ # make changes here and update the index
 $ git commit --amend
-$ git rebase --onto TMP bad mywork
+$ git rebase --onto HEAD bad mywork
 -------------------------------------------------
 
-When you're done, you'll be left with mywork checked out, with the top patches
+When you're done, you'll be left with mywork checked out, with the top
-on mywork reapplied on top of the modified commit you created in TMP.  You can
+patches on mywork reapplied on top of your modified commit.  You can
 then clean up with
 
 -------------------------------------------------
-$ git branch -d TMP
 $ git tag -d bad
 -------------------------------------------------
 
@@ -2275,8 +2316,8 @@ options mentioned above.
 Git internals
 =============
 
-There are two object abstractions: the "object database", and the
+Git depends on two fundamental abstractions: the "object database", and
-"current directory cache" aka "index".
+the "current directory cache" aka "index".
 
 The Object Database
 -------------------
@@ -2291,22 +2332,23 @@ All objects have a statically determined "type" aka "tag", which is
 determined at object creation time, and which identifies the format of
 the object (i.e. how it is used, and how it can refer to other
 objects).  There are currently four different object types: "blob",
-"tree", "commit" and "tag".
+"tree", "commit", and "tag".
 
-A "blob" object cannot refer to any other object, and is, like the type
+A <<def_blob_object,"blob" object>> cannot refer to any other object,
-implies, a pure storage object containing some user data.  It is used to
+and is, as the name implies, a pure storage object containing some
-actually store the file data, i.e. a blob object is associated with some
+user data.  It is used to actually store the file data, i.e. a blob
-particular version of some file. 
+object is associated with some particular version of some file.
 
-A "tree" object is an object that ties one or more "blob" objects into a
+A <<def_tree_object,"tree" object>> is an object that ties one or more
-directory structure. In addition, a tree object can refer to other tree
+"blob" objects into a directory structure. In addition, a tree object
-objects, thus creating a directory hierarchy. 
+can refer to other tree objects, thus creating a directory hierarchy.
 
-A "commit" object ties such directory hierarchies together into
+A <<def_commit_object,"commit" object>> ties such directory hierarchies
-a DAG of revisions - each "commit" is associated with exactly one tree
+together into a <<def_DAG,directed acyclic graph>> of revisions - each
-(the directory hierarchy at the time of the commit). In addition, a
+"commit" is associated with exactly one tree (the directory hierarchy at
-"commit" refers to one or more "parent" commit objects that describe the
+the time of the commit). In addition, a "commit" refers to one or more
-history of how we arrived at that directory hierarchy.
+"parent" commit objects that describe the history of how we arrived at
+that directory hierarchy.
 
 As a special case, a commit object with no parents is called the "root"
 object, and is the point of an initial project commit.  Each project
@@ -2316,9 +2358,10 @@ has two or more separate roots as its ultimate parents, that's probably
 just going to confuse people.  So aim for the notion of "one root object
 per project", even if git itself does not enforce that. 
 
-A "tag" object symbolically identifies and can be used to sign other
+A <<def_tag_object,"tag" object>> symbolically identifies and can be
-objects. It contains the identifier and type of another object, a
+used to sign other objects. It contains the identifier and type of
-symbolic name (of course!) and, optionally, a signature.
+another object, a symbolic name (of course!) and, optionally, a
+signature.
 
 Regardless of object type, all objects share the following
 characteristics: they are all deflated with zlib, and have a header

builtin-blame.c

@@ -19,11 +19,11 @@
 
 static char blame_usage[] =
 "git-blame [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--contents <filename>] [--incremental] [commit] [--] file\n"
-"  -c, --compatibility Use the same output mode as git-annotate (Default: off)\n"
+"  -c                  Use the same output mode as git-annotate (Default: off)\n"
 "  -b                  Show blank SHA-1 for boundary commits (Default: off)\n"
-"  -l, --long          Show long commit SHA1 (Default: off)\n"
+"  -l                  Show long commit SHA1 (Default: off)\n"
 "  --root              Do not treat root commits as boundaries (Default: off)\n"
-"  -t, --time          Show raw timestamp (Default: off)\n"
+"  -t                  Show raw timestamp (Default: off)\n"
 "  -f, --show-name     Show original filename (Default: auto)\n"
 "  -n, --show-number   Show original linenumber (Default: off)\n"
 "  -p, --porcelain     Show in a format designed for machine consumption\n"

templates/hooks--update

@@ -34,13 +34,19 @@ fi
 allowunannotated=$(git-repo-config --bool hooks.allowunannotated)
 
 # check for no description
+projectdesc=$(sed -e '1p' "$GIT_DIR/description")
 if [ -z "$projectdesc" -o "$projectdesc" = "Unnamed repository; edit this file to name it for gitweb" ]; then
 	echo "*** Project description file hasn't been set" >&2
 	exit 1
 fi
 
 # --- Check types
-newrev_type=$(git-cat-file -t $newrev)
+# if $newrev is 0000...0000, it's a commit to delete a branch
+if [ -z "${newrev##0*}" ]; then
+	newrev_type=commit
+else
+	newrev_type=$(git-cat-file -t $newrev)
+fi
 
 case "$refname","$newrev_type" in
 	refs/tags/*,commit)