From: J. Bruce Fields <bfields@xxxxxxxxxxxxxx> Update examples. I'm not sure if the last two examples are really useful any more. Signed-off-by: J. Bruce Fields <bfields@xxxxxxxxxxxxxx> --- Documentation/git-pull.txt | 75 +++++++++++++++++++++++++------------------ 1 files changed, 44 insertions(+), 31 deletions(-) diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 2a5aea7..5b9ff96 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -37,8 +37,15 @@ EXAMPLES -------- git pull, git pull origin:: - Fetch the default head from the repository you cloned - from and merge it into your current branch. + Update the remote tracking brances for the repository + you cloned from, then merge one of them into your + current branch. Normally the branch merged in is + the HEAD of the remote repository, when your master + branch is checked out. When on another branch, + the (alphabetically) first branch from the remote + repository is merged in. These defaults can be modified + using the branch and remote sections of the repository + configuration; see gitlink:git-repo-config[1] for details. git pull -s ours . obsolete:: Merge local branch `obsolete` into the current branch, @@ -58,51 +65,57 @@ 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. -Command line pull of multiple branches from one repository:: +Pull of multiple branches from one repository using default configuration:: + ------------------------------------------------ -$ cat .git/remotes/origin -URL: git://git.kernel.org/pub/scm/git/git.git -Pull: master:origin - +$ git repo-config -l +... +remote.origin.url=git://git.kernel.org/pub/scm/git/git.git +remote.origin.fetch=+refs/heads/*:refs/remotes/foo/* +branch.master.remote=origin +branch.master.merge=refs/heads/master $ git checkout master -$ git fetch origin master:origin +pu:pu maint:maint -$ git pull . origin +$ git fetch origin +$ git pull . origin/master ------------------------------------------------ + -Here, a typical `.git/remotes/origin` file from a +Here, a typical configuration created by the `git-clone` operation is used in combination with -command line options to `git-fetch` to first update -multiple branches of the local repository and then -to merge the remote `origin` branch into the local -`master` branch. The local `pu` branch is updated -even if it does not result in a fast forward update. +`git-fetch` to update all of the remote tracking +branches for `origin` (the remote repository which +you originally cloned from). Thanks to the "+" on +the `remote.origin.fetch` line, the tracking branches +will all be updated even if they do not result in a +fast forward update. ++ +The `git pull` command then merges the newly +fetched origin/master into the local `master` branch. Here, the pull can obtain its objects from the local repository using `.`, as the previous `git-fetch` is known to have already obtained and made available all the necessary objects. ++ +Note that given the configuration above, a simple +`git pull` would have the same result as the above +sequence of fetch and pull. -Pull of multiple branches from one repository using `.git/remotes` file:: +Commandline pull of multiple branches from one repository:: + ------------------------------------------------ -$ cat .git/remotes/origin -URL: git://git.kernel.org/pub/scm/git/git.git -Pull: master:origin -Pull: +pu:pu -Pull: maint:maint - $ git checkout master -$ git pull origin +$ git fetch origin master:origin +pu:pu maint:maint +$ git pull . origin ------------------------------------------------ + -Here, a typical `.git/remotes/origin` file from a -`git-clone` operation has been hand-modified to include -the branch-mapping of additional remote and local -heads directly. A single `git-pull` operation while -in the `master` branch will fetch multiple heads and -merge the remote `origin` head into the current, -local `master` branch. +Assuming the same configuration as above, this overrides +the default fetch behavior, updating (or creating, as +necessary) branches "origin", "pu", and "maint" in the +local repository by fetching from the branches (respectively) +"master", "pu", and "maint" from the remote repository. ++ +The "pu" branch will be updated even if it is does not +fast-foward; the others will not be. If you tried a pull which resulted in a complex conflicts and @@ -112,7 +125,7 @@ gitlink:git-reset[1]. SEE ALSO -------- -gitlink:git-fetch[1], gitlink:git-merge[1] +gitlink:git-fetch[1], gitlink:git-merge[1], gitlink:git-repo-config[1] Author -- 1.5.0.rc0.gac28 - 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