user-manual: more detailed merge discussion

Add more details on conflict, including brief discussion of file stages.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
Signed-off-by: Junio C Hamano <junkio@cox.net>

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index b80300e37487a5db415875052fc1ebfdad42e15d..a5e7b536f2bbb3355f9fa198a369c4c8c595e76d 100644 (file)
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1168,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
 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
 -------------------------------------------------
 
 
 -------------------------------------------------
 $ 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
 
 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
 
 -------------------------------------------------
 $ git diff


@@ -1200,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.
 
 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
-of file.txt and two previous versions: one version from HEAD, and one
-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,
-and the second for differences between the second parent and the
-working directory copy.  Thus after resolving the conflict in the
-obvious way, the diff will look like:
+During the merge, the index holds three versions of each file.  Each of
+these three "file stages" represents a different version of the file:
+
+-------------------------------------------------
+$ git show :1:file.txt # the file in a common ancestor of both branches
+$ git show :2:file.txt # the version from HEAD, but including any
+                       # nonconflicting changes from MERGE_HEAD
+$ 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
 
 -------------------------------------------------
 $ git diff


@@ -1225,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.
 
 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
 
 -------------------------------------------------
 $ git log --merge

+$ gitk --merge

 -------------------------------------------------
 
 -------------------------------------------------
 

-This will list all commits which exist only on HEAD or on MERGE_HEAD,
-and which touch an unmerged file.
+These will display all commits which exist only on HEAD or on
+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 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 different stages of that file will be "collapsed", after which
+git-diff will (by default) no longer show diffs for that file.

 
 [[undoing-a-merge]]
 undoing a merge
 
 [[undoing-a-merge]]
 undoing a merge


@@ -2988,11 +3045,6 @@ provides.
 Simplify beginning by suggesting disconnected head instead of
 temporary branch creation?
 
 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?
 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?