Documentation: improve "add", "pull" and "format-patch" examples
[gitweb.git] / Documentation / git-merge.txt
index 912ef29efce71d944af59588c6493591efc96bfc..c136b1069230af55b62ba95a1b40bdcc019b7b42 100644 (file)
@@ -11,26 +11,27 @@ SYNOPSIS
 [verse]
 'git-merge' [-n] [--summary] [--no-commit] [--squash] [-s <strategy>]...
        [-m <msg>] <remote> <remote>...
+'git-merge' <msg> HEAD <remote>...
 
 DESCRIPTION
 -----------
 This is the top-level interface to the merge machinery
 which drives multiple merge strategy scripts.
 
+The second syntax (<msg> `HEAD` <remote>) is supported for
+historical reasons.  Do not use it from the command line or in
+new scripts.  It is the same as `git merge -m <msg> <remote>`.
+
 
 OPTIONS
 -------
 include::merge-options.txt[]
 
-<msg>::
+-m <msg>::
        The commit message to be used for the merge commit (in case
        it is created). The `git-fmt-merge-msg` script can be used
        to give a good default for automated `git-merge` invocations.
 
-<head>::
-       Our branch head commit.  This has to be `HEAD`, so new
-       syntax does not require it
-
 <remote>::
        Other branch head merged into our branch.  You need at
        least one <remote>.  Specifying more than one <remote>
@@ -41,27 +42,47 @@ include::merge-strategies.txt[]
 
 If you tried a merge which resulted in a complex conflicts and
 would want to start over, you can recover with
-gitlink:git-reset[1].
+linkgit:git-reset[1].
+
+CONFIGURATION
+-------------
+
+merge.summary::
+       Whether to include summaries of merged commits in newly
+       created merge commit. False by default.
+
+merge.verbosity::
+       Controls the amount of output shown by the recursive merge
+       strategy.  Level 0 outputs nothing except a final error
+       message if conflicts were detected. Level 1 outputs only
+       conflicts, 2 outputs conflicts and file changes.  Level 5 and
+       above outputs debugging information.  The default is level 2.
+       Can be overridden by 'GIT_MERGE_VERBOSITY' environment variable.
 
+branch.<name>.mergeoptions::
+       Sets default options for merging into branch <name>. The syntax and
+       supported options are equal to that of git-merge, but option values
+       containing whitespace characters are currently not supported.
 
 HOW MERGE WORKS
 ---------------
 
 A merge is always between the current `HEAD` and one or more
-remote branch heads, and the index file must exactly match the
+commits (usually, branch head or tag), and the index file must
+exactly match the
 tree of `HEAD` commit (i.e. the contents of the last commit) when
 it happens.  In other words, `git-diff --cached HEAD` must
 report no changes.
 
 [NOTE]
-This is a bit of lie.  In certain special cases, your index are
-allowed to be different from the tree of `HEAD` commit.  The most
+This is a bit of a lie.  In certain special cases, your index is
+allowed to be different from the tree of the `HEAD` commit.  The most
 notable case is when your `HEAD` commit is already ahead of what
 is being merged, in which case your index can have arbitrary
-difference from your `HEAD` commit.  Otherwise, your index entries
-are allowed have differences from your `HEAD` commit that match
-the result of trivial merge (e.g. you received the same patch
-from external source to produce the same result as what you are
+differences from your `HEAD` commit.  Also, your index entries
+may have differences from your `HEAD` commit that match
+the result of trivial merge (e.g. you received the same patch
+from an external source to produce the same result as what you are
 merging).  For example, if a path did not exist in the common
 ancestor and your head commit but exists in the tree you are
 merging into your repository, and if you already happen to have
@@ -92,11 +113,11 @@ pull after you are done and ready.
 
 When things cleanly merge, these things happen:
 
-1. the results are updated both in the index file and in your
-   working tree,
-2. index file is written out as a tree,
-3. the tree gets committed, and 
-4. the `HEAD` pointer gets advanced.
+1. The results are updated both in the index file and in your
+   working tree;
+2. Index file is written out as a tree;
+3. The tree gets committed; and
+4. The `HEAD` pointer gets advanced.
 
 Because of 2., we require that the original state of the index
 file to match exactly the current `HEAD` commit; otherwise we
@@ -143,7 +164,8 @@ After seeing a conflict, you can do two things:
 
 SEE ALSO
 --------
-gitlink:git-fmt-merge-msg[1], gitlink:git-pull[1]
+linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
+linkgit:gitattributes[5]
 
 
 Author
@@ -157,4 +179,4 @@ Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT
 ---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[7] suite