Documentation: -merge and -pull: describe merge strategies.

[thirdparty/git.git] / Documentation / git-pull.txt

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index bae05dee99ebaa7866885d3d8a36cde81e5d700e..2f8a9ce2f25d784a598624884a4c941ecb48adac 100644 (file)
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -8,7 +8,7 @@ git-pull - Pull and merge from another repository.
 
 SYNOPSIS
 --------
-'git-pull' <repository> <refspec>...
+'git-pull' <options> <repository> <refspec>...
 
 
 DESCRIPTION
@@ -19,6 +19,9 @@ When only one ref is downloaded, runs 'git resolve' to merge it
 into the local HEAD.  Otherwise uses 'git octopus' to merge them
 into the local HEAD.
 
+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
 -------
@@ -29,6 +32,72 @@ include::pull-fetch-param.txt[]
        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[]
+
+
+MERGE STRATEGIES
+----------------
+
+resolve::
+       This can only resolve two heads (i.e. the current branch
+       and another branch you pulled from) using 3-way merge
+       algorithm.  It tries to carefully detect criss-cross
+       merge ambiguities and is considered generally safe and
+       fast.  This is the default merge strategy when pulling
+       one branch.
+
+recursive::
+       This can only resolve two heads using 3-way merge
+       algorithm.  When there are more than one common
+       ancestors that can be used for 3-way merge, it creates a
+       merged tree of the common ancestores and uses that as
+       the reference tree for the 3-way merge.  This has been
+       reported to result in fewer merge conflicts without
+       causing mis-merges by tests done on actual merge commits
+       taken from Linux 2.6 kernel development history.
+       Additionally this can detect and handle merges involving
+       renames.
+
+octopus::
+       This resolves more than two-head case, but refuses to do
+       complex merge that needs manual resolution.  It is
+       primarily meant to be used for bundling topic branch
+       heads together.  This is the default merge strategy when
+       pulling more than one branch.
+
+ours::
+       This resolves any number of heads, but the result of the
+       merge is always the current branch head.  It is meant to
+       be used to supersede old development history of side
+       branches.
+
+
+EXAMPLES
+--------
+
+git pull, git pull origin::
+       Fetch the default head from the repository you cloned
+       from and merge it into your current branch.
+
+git pull -s ours . obsolete::
+       Merge local branch `obsolete` into the current branch,
+       using `ours` merge strategy.
+
+git pull . fixes enhancements::
+       Bundle local branch `fixes` and `enhancements` on top of
+       the current branch, making an Octopus merge.
+
+git pull --no-commit . maint::
+       Merge local branch `maint` into the current branch, but
+       do not make a commit automatically.  This can be used
+       when you want to include further changes to the merge,
+       or want to write your own merge commit message.
++
+You should refrain from abusing this option to sneak substantial
+changes into a merge commit.  Small fixups like bumping
+release/version name would be acceptable.
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>