Documentation: merge: add an overview

jrn · trast · commit b40bb374a618 · 2010-01-24T13:57:42.000+01:00
The reader unfamiliar with the concepts of branching and merging
would have been completely lost.  Try to help him with a diagram.

Signed-off-by: Jonathan Nieder &lt;jrnieder@gmail.com&gt;
Signed-off-by: Thomas Rast &lt;trast@student.ethz.ch&gt;
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
@@ -15,8 +15,32 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Merges the history specified by <commit> into HEAD, optionally using a
-specific merge strategy.
+Incorporates changes from the named commits (since the time their
+histories diverged from the current branch) into the current
+branch.  This command is used by 'git pull' to incorporate changes
+from another repository and can be used by hand to merge changes
+from one branch into another.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+	  A---B---C topic
+	 /
+    D---E---F---G master
+------------
+
+Then "`git merge topic`" will replay the changes made on the
+`topic` branch since it diverged from `master` (i.e., `E`) until
+its current commit (`C`) on top of `master`, and record the result
+in a new commit along with the names of the two parent commits and
+a log message from the user describing the changes.
+
+------------
+	  A---B---C topic
+	 /         \
+    D---E---F---G---H master
+------------
 
 The second syntax (<msg> `HEAD` <commit>...) is supported for
 historical reasons.  Do not use it from the command line or in
