Merge branch 'master'

Documentation/Makefile

@@ -49,22 +49,25 @@ install: man
 	$(INSTALL) $(DOC_MAN1) $(DESTDIR)/$(man1)
 	$(INSTALL) $(DOC_MAN7) $(DESTDIR)/$(man7)
 
-# 'include' dependencies
-$(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \
-	diff-format.txt diff-options.txt
-$(patsubst %.txt,%.html,$(wildcard git-diff-*.txt)): \
-	diff-format.txt diff-options.txt
 
-$(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt
+#
-$(patsubst %,%.html,git-fetch git-pull git-push): pull-fetch-param.txt
+# Determine "include::" file references in asciidoc files.
+#
+TEXTFILES = $(wildcard *.txt)
+DEPFILES = $(TEXTFILES:%.txt=%.dep)
 
-$(patsubst %,%.1,git-merge git-pull): merge-pull-opts.txt
+%.dep : %.txt
-$(patsubst %,%.html,git-merge git-pull): merge-pull-opts.txt
+	@rm -f $@
+	@$(foreach dep, $(shell grep include:: $< | sed -e 's/include::/ /' -e 's/\[\]//'), \
+		echo $(<:%.txt=%.html) $(<:%.txt=%.1) : $(dep) >> $@; )
+
+-include $(DEPFILES)
 
 git.7: ../README
 
+
 clean:
-	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html
+	rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html *.dep
 
 %.html : %.txt
 	asciidoc -b xhtml11 -d manpage -f asciidoc.conf $<

Documentation/fetch-options.txt

@@ -0,0 +1,14 @@
+-a, \--append::
+	Append ref names and object names of fetched refs to the
+	existing contents of `.git/FETCH_HEAD`.  Without this
+	option old data in `.git/FETCH_HEAD` will be overwritten.
+
+-f, \--force::
+
+-t, \--tags::
+
+-u, \--update-head-ok::
+	By default `git-fetch` refuses to update the head which
+	corresponds to the current branch.  This flag disables the
+	check.  Note that fetching into the current branch will not
+	update the index and working directory, so use it with care.

Documentation/git-fetch.txt

@@ -8,7 +8,7 @@ git-fetch - Download objects and a head from another repository.
 
 SYNOPSIS
 --------
-'git-fetch' <repository> <refspec>...
+'git-fetch' <options> <repository> <refspec>...
 
 
 DESCRIPTION
@@ -17,24 +17,16 @@ Fetches named heads or tags from another repository, along with
 the objects necessary to complete them.
 
 The ref names and their object names of fetched refs are stored
-in $GIT_DIR/FETCH_HEAD.  This information is left for a later merge
+in `.git/FETCH_HEAD`.  This information is left for a later merge
 operation done by "git resolve" or "git octopus".
 
 
 OPTIONS
 -------
-include::pull-fetch-param.txt[]
+include::fetch-options.txt[]
 
--a, \--append::
+include::pull-fetch-param.txt[]
-	Append ref names and object names of fetched refs to the
-	existing contents of $GIT_DIR/FETCH_HEAD.  Without this
-	option old data in $GIT_DIR/FETCH_HEAD will be overwritten.
 
--u, \--update-head-ok::
-	By default 'git-fetch' refuses to update the head which
-	corresponds to the current branch.  This flag disables the
-	check.  Note that fetching into the current branch will not
-	update the index and working directory, so use it with care.
 
 
 SEE ALSO

Documentation/git-merge.txt

@@ -19,7 +19,7 @@ which drives multiple merge strategy scripts.
 
 OPTIONS
 -------
-include::merge-pull-opts.txt[]
+include::merge-options.txt[]
 
 <msg>::
 	The commit message to be used for the merge commit (in case

Documentation/git-pull.txt

@@ -20,21 +20,18 @@ Note that you can use `.` (current directory) as the
 <repository> to pull from the local repository -- this is useful
 when merging local branches into the current branch.
 
+
 OPTIONS
 -------
-include::pull-fetch-param.txt[]
+include::merge-options.txt[]
 
--a, \--append::
+include::fetch-options.txt[]
-	Append ref names and object names of fetched refs to the
-	existing contents of `$GIT_DIR/FETCH_HEAD`.  Without this
-	option old data in `$GIT_DIR/FETCH_HEAD` will be overwritten.
 
-include::merge-pull-opts.txt[]
+include::pull-fetch-param.txt[]
 
 include::merge-strategies.txt[]
 
 
-
 EXAMPLES
 --------
 
@@ -72,7 +69,7 @@ $ git fetch origin master:origin +pu:pu maint:maint
 $ git pull . origin
 ------------------------------------------------
 +
-Here, a typical `$GIT_DIR/remotes/origin` file from a
+Here, a typical `.git/remotes/origin` file from a
 `git-clone` operation is used in combination with
 command line options to `git-fetch` to first update
 multiple branches of the local repository and then
@@ -85,7 +82,7 @@ known to have already obtained and made available
 all the necessary objects.
 
 
-Pull of multiple branches from one repository using `$GIT_DIR/remotes` file::
+Pull of multiple branches from one repository using `.git/remotes` file::
 +
 ------------------------------------------------
 $ cat .git/remotes/origin
@@ -98,7 +95,7 @@ $ git checkout master
 $ git pull origin
 ------------------------------------------------
 +
-Here, a typical `$GIT_DIR/remotes/origin` file from a
+Here, a typical `.git/remotes/origin` file from a
 `git-clone` operation has been hand-modified to include
 the branch-mapping of additional remote and local
 heads directly.  A single `git-pull` operation while

Documentation/merge-options.txt

@@ -0,0 +1,16 @@
+-n, \--no-summary::
+	Do not show diffstat at the end of the merge.
+
+--no-commit::
+	Perform the merge but pretend the merge failed and do
+	not autocommit, to give the user a chance to inspect and
+	further tweak the merge result before committing.
+
+
+-s <strategy>, \--strategy=<strategy>::
+	Use the given merge strategy; can be supplied more than
+	once to specify them in the order they should be tried.
+	If there is no `-s` option, a built-in list of strategies
+	is used instead (`git-merge-resolve` when merging a single
+	head, `git-merge-octopus` otherwise).
+

Documentation/merge-pull-opts.txt

@@ -1,14 +0,0 @@
--n, --no-summary::
-	Do not show diffstat at the end of the merge.
-
---no-commit::
-	Perform the merge but pretend the merge failed and do
-	not autocommit, to give the user a chance to inspect and
-	further tweak the merge result before committing.
-
--s <strategy>::
-	use that merge strategy; can be given more than once to
-	specify them in the order they should be tried.  If
-	there is no `-s` option, built-in list of strategies is
-	used instead (`git-merge-resolve` when merging a single
-	head, `git-merge-octopus` otherwise).

Documentation/tutorial.txt

@@ -301,7 +301,7 @@ all with a sequence of simple shell commands:
 ------------------------------------------------
 tree=$(git-write-tree)
 commit=$(echo 'Initial commit' | git-commit-tree $tree)
-git-update-ref HEAD $(commit)
+git-update-ref HEAD $commit
 ------------------------------------------------
 
 which will say:
@@ -836,14 +836,14 @@ source.
 Anyway, let's exit `gitk` (`^Q` or the File menu), and decide that we want
 to merge the work we did on the `mybranch` branch into the `master`
 branch (which is currently our `HEAD` too). To do that, there's a nice
-script called `git resolve`, which wants to know which branches you want
+script called `git merge`, which wants to know which branches you want
 to resolve and what the merge is all about:
 
 ------------
-git resolve HEAD mybranch "Merge work in mybranch"
+git merge "Merge work in mybranch" HEAD mybranch
 ------------
 
-where the third argument is going to be used as the commit message if
+where the first argument is going to be used as the commit message if
 the merge can be resolved automatically.
 
 Now, in this case we've intentionally created a situation where the
@@ -851,12 +851,14 @@ merge will need to be fixed up by hand, though, so git will do as much
 of it as it can automatically (which in this case is just merge the `example`
 file, which had no differences in the `mybranch` branch), and say:
 
-	Simple merge failed, trying Automatic merge
+	Trying really trivial in-index merge...
-	Auto-merging hello.
+	fatal: Merge requires file-level merging
+	Nope.
+	...
 	merge: warning: conflicts during merge
 	ERROR: Merge conflict in hello.
 	fatal: merge program failed
-	Automatic merge failed, fix up by hand
+	Automatic merge failed/prevented; fix up by hand
 
 which is way too verbose, but it basically tells you that it failed the
 really trivial merge ("Simple merge") and did an "Automatic merge"
@@ -928,7 +930,7 @@ resolve to get the "upstream changes" back to your branch.
 
 ------------
 git checkout mybranch
-git resolve HEAD master "Merge upstream changes."
+git merge "Merge upstream changes." HEAD master
 ------------
 
 This outputs something like this (the actual commit object names
@@ -1103,6 +1105,155 @@ the above are equivalent to:
 . `git pull http://www.kernel.org/pub/.../jgarzik/netdev-2.6.git e100`
 
 
+How does the merge work?
+------------------------
+
+We said this tutorial shows what plumbing does to help you cope
+with the porcelain that isn't flushing, but we so far did not
+talk about how the merge really works.  If you are following
+this tutorial the first time, I'd suggest to skip to "Publishing
+your work" section and come back here later.
+
+OK, still with me?  To give us an example to look at, let's go
+back to the earlier repository with "hello" and "example" file,
+and bring ourselves back to the pre-merge state:
+
+------------
+$ git show-branch --more=3 master mybranch
+! [master] Merge work in mybranch
+ * [mybranch] Merge work in mybranch
+--
+++ [master] Merge work in mybranch
+++ [master^2] Some work.
+++ [master^] Some fun.
+------------
+
+Remember, before running `git merge`, our `master` head was at
+"Some fun." commit, while our `mybranch` head was at "Some
+work." commit.
+
+------------
+$ git checkout mybranch
+$ git reset --hard master^2
+$ git checkout master
+$ git reset --hard master^
+------------
+
+After rewinding, the commit structure should look like this:
+
+------------
+$ git show-branch
+* [master] Some fun.
+ ! [mybranch] Some work.
+--
+ + [mybranch] Some work.
++  [master] Some fun.
+++ [mybranch^] New day.
+------------
+
+Now we are ready to experiment with the merge by hand.
+
+`git merge` command, when merging two branches, uses 3-way merge
+algorithm.  First, it finds the common ancestor between them.
+The command it uses is `git-merge-base`:
+
+------------
+$ mb=$(git-merge-base HEAD mybranch)
+------------
+
+The command writes the commit object name of the common ancestor
+to the standard output, so we captured its output to a variable,
+because we will be using it in the next step.  BTW, the common
+ancestor commit is the "New day." commit in this case.  You can
+tell it by:
+
+------------
+$ git-name-rev $mb
+my-first-tag
+------------
+
+After finding out a common ancestor commit, the second step is
+this:
+
+------------
+$ git-read-tree -m -u $mb HEAD mybranch
+------------
+
+This is the same `git-read-tree` command we have already seen,
+but it takes three trees, unlike previous examples.  This reads
+the contents of each tree into different 'stage' in the index
+file (the first tree goes to stage 1, the second stage 2,
+etc.).  After reading three trees into three stages, the paths
+that are the same in all three stages are 'collapsed' into stage
+0.  Also paths that are the same in two of three stages are
+collapsed into stage 0, taking the SHA1 from either stage 2 or
+stage 3, whichever is different from stage 1 (i.e. only one side
+changed from the common ancestor).
+
+After 'collapsing' operation, paths that are different in three
+trees are left in non-zero stages.  At this point, you can
+inspect the index file with this command:
+
+------------
+$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0	example
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1	hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2	hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello
+------------
+
+In our example of only two files, we did not have unchanged
+files so only 'example' resulted in collapsing, but in real-life
+large projects, only small number of files change in one commit,
+and this 'collapsing' tends to trivially merge most of the paths
+fairly quickly, leaving only the real changes in non-zero stages.
+
+To look at only non-zero stages, use `\--unmerged` flag:
+
+------------
+$ git-ls-files --unmerged
+100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1	hello
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2	hello
+100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello
+------------
+
+The next step of merging is to merge these three versions of the
+file, using 3-way merge.  This is done by giving
+`git-merge-one-file` command as one of the arguments to
+`git-merge-index` command:
+
+------------
+$ git-merge-index git-merge-one-file hello
+Auto-merging hello.
+merge: warning: conflicts during merge
+ERROR: Merge conflict in hello.
+fatal: merge program failed
+------------
+
+`git-merge-one-file` script is called with parameters to
+describe those three versions, and is responsible to leave the
+merge results in the working tree and register it in the index
+file.  It is a fairly straightforward shell script, and
+eventually calls `merge` program from RCS suite to perform the
+file-level 3-way merge.  In this case, `merge` detects
+conflicts, and the merge result with conflict marks is left in
+the working tree, while the index file is updated with the
+version from the current branch (this is to make `git diff`
+useful after this step).  This can be seen if you run `ls-files
+--stage` again at this point:
+
+------------
+$ git-ls-files --stage
+100644 7f8b141b65fdcee47321e399a2598a235a032422 0	example
+100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 0	hello
+------------
+
+As you can see, there is no unmerged paths in the index file.
+This is the state of the index file and the working file after
+`git merge` returns control back to you, leaving the conflicting
+merge for you to resolve.
+
+
 Publishing your work
 --------------------
 

git-format-patch.sh

@@ -8,6 +8,7 @@
 usage () {
     echo >&2 "usage: $0"' [-n] [-o dir | --stdout] [--keep-subject] [--mbox]
     [--check] [--signoff] [-<diff options>...]
+    [--help]
     ( from..to ... | upstream [ our-head ] )
 
 Prepare each commit with its patch since our-head forked from upstream,
@@ -63,6 +64,9 @@ do
     --output-directo|--output-director|--output-directory)
     case "$#" in 1) usage ;; esac; shift
     outdir="$1" ;;
+    -h|--h|--he|--hel|--help)
+        usage
+	;;
     -*' '* | -*"$LF"* | -*'	'*)
 	# Ignore diff option that has whitespace for now.
 	;;

git-pull.sh

@@ -7,7 +7,14 @@
 . git-sh-setup || die "Not a git archive"
 
 usage () {
-    die "git pull [-n] [--no-commit] [-s strategy]... <repo> <head>..."
+    echo >&2 "usage: $0"' [-n] [--no-commit] [--no-summary] [--help]
+    [-s strategy]...
+    [<fetch-options>]
+    <repo> <head>...
+
+Fetch one or more remote refs and merge it/them into the current HEAD.
+'
+    exit 1
 }
 
 strategy_args= no_summary= no_commit=
@@ -33,6 +40,9 @@ do
 		esac
 		strategy_args="${strategy_args}-s $strategy "
 		;;
+	-h|--h|--he|--hel|--help)
+		usage
+		;;
 	-*)
 		# Pass thru anything that is meant for fetch.
 		break