Merge branch 'maint'

* maint:
  GIT 1.5.0.3
  glossary: Add definitions for dangling and unreachable objects
  user-manual: more detailed merge discussion
  user-manual: how to replace commits older than most recent
  user-manual: insert earlier of mention content-addressable architecture
  user-manual: ensure generated manual references stylesheet
  user-manual: reset to ORIG_HEAD not HEAD to undo merge
  Documentation: mention module option to git-cvsimport

Documentation/Makefile

@@ -105,8 +105,11 @@ clean:
 user-manual.xml: user-manual.txt user-manual.conf
 	$(ASCIIDOC) -b docbook -d book $<
 
+XSLT = http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
+XSLTOPTS = --nonet --xinclude --stringparam html.stylesheet docbook-xsl.css
+
 user-manual.html: user-manual.xml
-	xmlto html-nochunks $<
+	xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
 
 glossary.html : glossary.txt sort_glossary.pl
 	cat $< | \

Documentation/RelNotes-1.5.0.3.txt

@@ -1,4 +1,4 @@
-GIT v1.5.0.2 Release Notes
+GIT v1.5.0.3 Release Notes
 ==========================
 
 Fixes since v1.5.0.2
@@ -15,6 +15,10 @@ Fixes since v1.5.0.2
     path.  Earlier it started in the middle of the path, and
     incorrectly.
 
+  - 'git-merge' did not exit with non-zero status when the
+    working tree was dirty and cannot fast forward.  It does
+    now.
+
   - 'cvsexportcommit' does not lose yet-to-be-used message file.
 
   - int-vs-size_t typefix when running combined diff on files
@@ -38,18 +42,17 @@ Fixes since v1.5.0.2
   - 'git index-pack' did not protect itself from getting a short
     read out of pread(2).
 
+  - 'git http-push' had a few buffer overruns.
+
+  - Build dependency fixes to rebuild fetch.o when other headers
+    change.
+
 * Documentation updates
 
-  - options to 'git remote add' were described insufficiently.
+  - user-manual updates.
 
+  - Options to 'git remote add' were described insufficiently.
 
----
+  - Configuration format.suffix was not documented.
-exec >/var/tmp/1
-O=v1.5.0.2
-O=v1.5.0.2-16-gdb554bf
-echo O=`git describe maint`
-git shortlog --no-merges $O..maint
 
-# Local Variables:
+  - Other formatting and spelling fixes.
-# mode: text
-# End:

Documentation/cvs-migration.txt

@@ -109,7 +109,7 @@ sure it is in your path.  Then cd to a checked out CVS working directory
 of the project you are interested in and run gitlink:git-cvsimport[1]:
 
 -------------------------------------------
-$ git cvsimport -C <destination>
+$ git cvsimport -C <destination> <module>
 -------------------------------------------
 
 This puts a git archive of the named CVS module in the directory

Documentation/glossary.txt

@@ -73,6 +73,11 @@ DAG::
 	objects is acyclic (there is no chain which begins and ends with the
 	same object).
 
+dangling object::
+	An unreachable object which is not reachable even from other
+	unreachable objects; a dangling object has no references to it
+	from any reference or object in the repository.
+
 dircache::
 	You are *waaaaay* behind.
 
@@ -350,6 +355,10 @@ tag::
 unmerged index::
 	An index which contains unmerged index entries.
 
+unreachable object::
+	An object which is not reachable from a branch, tag, or any
+	other reference.
+
 working tree::
 	The set of files and directories currently being worked on,
 	i.e. you can work in your working tree without using git at all.

Documentation/user-manual.txt

@@ -391,15 +391,20 @@ index 8be626f..d7aac9d 100644
 As you can see, a commit shows who made the latest change, what they
 did, and why.
 
-Every commit has a 40-hexdigit id, sometimes called the "object name"
+Every commit has a 40-hexdigit id, sometimes called the "object name" or the
-or the "SHA1 id", shown on the first line of the "git show" output.
+"SHA1 id", shown on the first line of the "git show" output.  You can usually
-You can usually refer to a commit by a shorter name, such as a tag or a
+refer to a commit by a shorter name, such as a tag or a branch name, but this
-branch name, but this longer name can also be useful.  Most
+longer name can also be useful.  Most importantly, it is a globally unique
-importantly, it is a globally unique name for this commit: so if you
+name for this commit: so if you tell somebody else the object name (for
-tell somebody else the object name (for example in email), then you are
+example in email), then you are guaranteed that name will refer to the same
-guaranteed that name will refer to the same commit in their repository
+commit in their repository that it does in yours (assuming their repository
-that it does in yours (assuming their repository has that commit at
+has that commit at all).  Since the object name is computed as a hash over the
-all).
+contents of the commit, you are guaranteed that the commit can never change
+without its name also changing.
+
+In fact, in <<git-internals>> we shall see that everything stored in git
+history, including file data and directory contents, is stored in an object
+with a name that is a hash of its contents.
 
 Understanding history: commits, parents, and reachability
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1163,18 +1168,46 @@ the working tree in a special state that gives you all the
 information you need to help resolve the merge.
 
 Files with conflicts are marked specially in the index, so until you
-resolve the problem and update the index, git commit will fail:
+resolve the problem and update the index, gitlink:git-commit[1] will
+fail:
 
 -------------------------------------------------
 $ git commit
 file.txt: needs merge
 -------------------------------------------------
 
-Also, git status will list those files as "unmerged".
+Also, gitlink:git-status[1] will list those files as "unmerged", and the
+files with conflicts will have conflict markers added, like this:
+
+-------------------------------------------------
+<<<<<<< HEAD:file.txt
+Hello world
+=======
+Goodbye
+>>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
+-------------------------------------------------
+
+All you need to do is edit the files to resolve the conflicts, and then
+
+-------------------------------------------------
+$ git add file.txt
+$ git commit
+-------------------------------------------------
+
+Note that the commit message will already be filled in for you with
+some information about the merge.  Normally you can just use this
+default message unchanged, but you may add additional commentary of
+your own if desired.
+
+The above is all you need to know to resolve a simple merge.  But git
+also provides more information to help resolve conflicts:
+
+Getting conflict-resolution help during a merge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 All of the changes that git was able to merge automatically are
 already added to the index file, so gitlink:git-diff[1] shows only
-the conflicts.  Also, it uses a somewhat unusual syntax:
+the conflicts.  It uses an unusual syntax:
 
 -------------------------------------------------
 $ git diff
@@ -1195,14 +1228,32 @@ conflict will have two parents instead of the usual one: one parent
 will be HEAD, the tip of the current branch; the other will be the
 tip of the other branch, which is stored temporarily in MERGE_HEAD.
 
-The diff above shows the differences between the working-tree version
+During the merge, the index holds three versions of each file.  Each of
-of file.txt and two previous versions: one version from HEAD, and one
+these three "file stages" represents a different version of the file:
-from MERGE_HEAD.  So instead of preceding each line by a single "+"
+
-or "-", it now uses two columns: the first column is used for
+-------------------------------------------------
-differences between the first parent and the working directory copy,
+$ git show :1:file.txt	# the file in a common ancestor of both branches
-and the second for differences between the second parent and the
+$ git show :2:file.txt	# the version from HEAD, but including any
-working directory copy.  Thus after resolving the conflict in the
+			# nonconflicting changes from MERGE_HEAD
-obvious way, the diff will look like:
+$ git show :3:file.txt	# the version from MERGE_HEAD, but including any
+			# nonconflicting changes from HEAD.
+-------------------------------------------------
+
+Since the stage 2 and stage 3 versions have already been updated with
+nonconflicting changes, the only remaining differences between them are
+the important ones; thus gitlink:git-diff[1] can use the information in
+the index to show only those conflicts.
+
+The diff above shows the differences between the working-tree version of
+file.txt and the stage 2 and stage 3 versions.  So instead of preceding
+each line by a single "+" or "-", it now uses two columns: the first
+column is used for differences between the first parent and the working
+directory copy, and the second for differences between the second parent
+and the working directory copy.  (See the "COMBINED DIFF FORMAT" section
+of gitlink:git-diff-files[1] for a details of the format.)
+
+After resolving the conflict in the obvious way (but before updating the
+index), the diff will look like:
 
 -------------------------------------------------
 $ git diff
@@ -1220,26 +1271,37 @@ This shows that our resolved version deleted "Hello world" from the
 first parent, deleted "Goodbye" from the second parent, and added
 "Goodbye world", which was previously absent from both.
 
-The gitlink:git-log[1] command also provides special help for merges:
+Some special diff options allow diffing the working directory against
+any of these stages:
+
+-------------------------------------------------
+$ git diff -1 file.txt		# diff against stage 1
+$ git diff --base file.txt	# same as the above
+$ git diff -2 file.txt		# diff against stage 2
+$ git diff --ours file.txt	# same as the above
+$ git diff -3 file.txt		# diff against stage 3
+$ git diff --theirs file.txt	# same as the above.
+-------------------------------------------------
+
+The gitlink:git-log[1] and gitk[1] commands also provide special help
+for merges:
 
 -------------------------------------------------
 $ git log --merge
+$ gitk --merge
 -------------------------------------------------
 
-This will list all commits which exist only on HEAD or on MERGE_HEAD,
+These will display all commits which exist only on HEAD or on
-and which touch an unmerged file.
+MERGE_HEAD, and which touch an unmerged file.
 
-We can now add the resolved version to the index and commit:
+Each time you resolve the conflicts in a file and update the index:
 
 -------------------------------------------------
 $ git add file.txt
-$ git commit
 -------------------------------------------------
 
-Note that the commit message will already be filled in for you with
+the different stages of that file will be "collapsed", after which
-some information about the merge.  Normally you can just use this
+git-diff will (by default) no longer show diffs for that file.
-default message unchanged, but you may add additional commentary of
-your own if desired.
 
 [[undoing-a-merge]]
 undoing a merge
@@ -1255,7 +1317,7 @@ $ git reset --hard HEAD
 Or, if you've already commited the merge that you want to throw away,
 
 -------------------------------------------------
-$ git reset --hard HEAD^
+$ git reset --hard ORIG_HEAD
 -------------------------------------------------
 
 However, this last command can be dangerous in some cases--never
@@ -1328,6 +1390,7 @@ with the changes to be reverted, then you will be asked to fix
 conflicts manually, just as in the case of <<resolving-a-merge,
 resolving a merge>>.
 
+[[fixing-a-mistake-by-editing-history]]
 Fixing a mistake by editing history
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1930,6 +1993,51 @@ return mywork to the state it had before you started the rebase:
 $ git rebase --abort
 -------------------------------------------------
 
+Modifying a single commit
+-------------------------
+
+We saw in <<fixing-a-mistake-by-editing-history>> that you can replace the
+most recent commit using
+
+-------------------------------------------------
+$ git commit --amend
+-------------------------------------------------
+
+which will replace the old commit by a new commit incorporating your
+changes, giving you a chance to edit the old commit message first.
+
+You can also use a combination of this and gitlink:git-rebase[1] to edit
+commits further back in your history.  First, tag the problematic commit with
+
+-------------------------------------------------
+$ 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
+the series on top of it:
+
+-------------------------------------------------
+$ git checkout -b TMP bad
+$ # make changes here and update the index
+$ git commit --amend
+$ git rebase --onto TMP bad mywork
+-------------------------------------------------
+
+When you're done, you'll be left with mywork checked out, with the top patches
+on mywork reapplied on top of the modified commit you created in TMP.  You can
+then clean up with
+
+-------------------------------------------------
+$ git branch -d TMP
+$ git tag -d bad
+-------------------------------------------------
+
+Note that the immutable nature of git history means that you haven't really
+"modified" existing commits; instead, you have replaced the old commits with
+new commits having new object names.
+
 Reordering or selecting from a patch series
 -------------------------------------------
 
@@ -2155,6 +2263,7 @@ See gitlink:git-config[1] for more details on the configuration
 options mentioned above.
 
 
+[[git-internals]]
 Git internals
 =============
 
@@ -2936,11 +3045,6 @@ provides.
 Simplify beginning by suggesting disconnected head instead of
 temporary branch creation?
 
-Explain how to refer to file stages in the "how to resolve a merge"
-section: diff -1, -2, -3, --ours, --theirs :1:/path notation.  The
-"git ls-files --unmerged --stage" thing is sorta useful too,
-actually.  And note gitk --merge.
-
 Add more good examples.  Entire sections of just cookbook examples
 might be a good idea; maybe make an "advanced examples" section a
 standard end-of-chapter section?