summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJonathan Nieder <jrnieder@gmail.com>2010-08-02 16:39:30 -0500
committerJunio C Hamano <gitster@pobox.com>2010-08-02 15:48:18 -0700
commit3f8fc184c0e2cdc90002cf9a5c11353fe623df23 (patch)
treef67fabc3e0cdb0e2194440e8b498e70f6ae2d27d /Documentation
parent64fdc08dac6694d1e754580e7acb82dfa4988bb9 (diff)
downloadgit-3f8fc184c0e2cdc90002cf9a5c11353fe623df23.tar.gz
Documentation: flesh out “git pull” description
The current description in the pull man page does not say much more than that “git pull” is fetch + merge. Though that is all a person needs to know in the end, it would be useful to summarize a bit about what those commands do for new readers. Most of this description is taken from the “git merge” docs. Now that we explain how to back out of a failed merge (reset --merge), we can tone down the warning against that a bit. Except, as Thomas noticed, there’s a risk with that because people might read this version of the manpage online and then conclude that it is safe to try a merge with uncommitted changes, only to find that their “git reset” doesn't support --merge yet. Or worse, verify that their git-reset has --merge by a quick test (1b5b465 is in 1.6.2) but then find that it does not help with backing out of a merge (e11d7b5 is only in 1.7.0!). So keep the warning. With clarifications from Ævar, Thomas, and Junio. Noticed-by: Geoff Russell <geoffrey.russell@gmail.com> Cc: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Cc: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/git-pull.txt65
1 files changed, 54 insertions, 11 deletions
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index ab4de10358..c50f7dcb89 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -8,29 +8,72 @@ git-pull - Fetch from and merge with another repository or a local branch
SYNOPSIS
--------
-'git pull' <options> <repository> <refspec>...
+'git pull' [options] [<repository> [<refspec>...]]
DESCRIPTION
-----------
-Runs 'git fetch' with the given parameters, and calls 'git merge'
-to merge the retrieved head(s) into the current branch.
-With `--rebase`, calls 'git rebase' instead of 'git merge'.
-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.
+Incorporates changes from a remote repository into the current
+branch. In its default mode, `git pull` is shorthand for
+`git fetch` followed by `git merge FETCH_HEAD`.
-Also note that options meant for 'git pull' itself and underlying
-'git merge' must be given before the options meant for 'git fetch'.
+More precisely, 'git pull' runs 'git fetch' with the given
+parameters and calls 'git merge' to merge the retrieved branch
+heads into the current branch.
+With `--rebase`, it runs 'git rebase' instead of 'git merge'.
-*Warning*: Running 'git pull' (actually, the underlying 'git merge')
+<repository> should be the name of a remote repository as
+passed to linkgit:git-fetch[1]. <refspec> can name an
+arbitrary remote ref (for example, the name of a tag) or even
+a collection of refs with corresponding remote tracking branches
+(e.g., refs/heads/*:refs/remotes/origin/*), but usually it is
+the name of a branch in the remote repository.
+
+Default values for <repository> and <branch> are read from the
+"remote" and "merge" configuration for the current branch
+as set by linkgit:git-branch[1] `--track`.
+
+Assume the following history exists and the current branch is
+"`master`":
+
+------------
+ A---B---C master on origin
+ /
+ D---E---F---G master
+------------
+
+Then "`git pull`" will fetch and replay the changes from the remote
+`master` branch since it diverged from the local `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 remotes/origin/master
+ / \
+ D---E---F---G---H master
+------------
+
+See linkgit:git-merge[1] for details, including how conflicts
+are presented and handled.
+
+In git 1.7.0 or later, to cancel a conflicting merge, use
+`git reset --merge`. *Warning*: In older versions of git, running 'git pull'
with uncommitted changes is discouraged: while possible, it leaves you
-in a state that is hard to back out of in the case of a conflict.
+in a state that may be hard to back out of in the case of a conflict.
+
+If any of the remote changes overlap with local uncommitted changes,
+the merge will be automatically cancelled and the work tree untouched.
+It is generally best to get any local changes in working order before
+pulling or stash them away with linkgit:git-stash[1].
OPTIONS
-------
+Options meant for 'git pull' itself and the underlying 'git merge'
+must be given before the options meant for 'git fetch'.
+
-q::
--quiet::
This is passed to both underlying git-fetch to squelch reporting of