Hi Geoff, Geoff Russell wrote: > There are notes on the "git pull" man page about not working on a remote branch > but having a local branch with a different name and merging the remote branch. > Why is this necessary? The "git pull" man page is very unclear, I agree. Especially when starting out, I would recommend looking at the User’s Manual (and the other resources the git(1) man page recommends). In this case, the section to look at would be Chapter 4, on Sharing development with others[1]. Thanks for noticing. Jonathan [1] http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#sharing-development -- 8< -- Subject: pull documentation: Flesh out 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. Cc: Thomas Rast <trast@xxxxxxxxxxxxxxx> Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx> --- Documentation/git-pull.txt | 61 +++++++++++++++++++++++++++++++++++-------- 1 files changed, 49 insertions(+), 12 deletions(-) diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index ab4de10..8803680 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -8,29 +8,66 @@ git-pull - Fetch from and merge with another repository or a local branch SYNOPSIS -------- -'git pull' <options> <repository> <refspec>... +'git pull' <options> <repository> <branch>... 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, a `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') -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. +<repository> should be the name of a remote repository as +passed to linkgit:git-fetch[1]. <branch> can be an +arbitrary refspec (for example, the name of a tag), 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. To cancel a conflicting merge, +use `git reset --merge`. + +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 -- 1.7.1 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html