From d504f6975d34025ed3b5478b657789410b52cdb1 Mon Sep 17 00:00:00 2001 From: Clemens Buchacher Date: Wed, 21 Oct 2009 19:21:23 +0200 Subject: [PATCH] modernize fetch/merge/pull examples The "git pull" documentation has examples which follow an outdated style. Update the examples to use "git merge" where appropriate and move the examples to the corresponding manpages. Furthermore, - show that pull is equivalent to fetch and merge, which is still a frequently asked question, - explain the default fetch refspec. Signed-off-by: Clemens Buchacher Signed-off-by: Junio C Hamano --- Documentation/git-fetch.txt | 29 ++++++++++++++++++++++ Documentation/git-merge.txt | 33 +++++++++++++++++++++++++ Documentation/git-pull.txt | 49 +++---------------------------------- 3 files changed, 66 insertions(+), 45 deletions(-) diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index d3164c5c88..f2483d624e 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -37,6 +37,35 @@ include::pull-fetch-param.txt[] include::urls-remotes.txt[] + +EXAMPLES +-------- + +* Update the remote-tracking branches: ++ +------------------------------------------------ +$ git fetch origin +------------------------------------------------ ++ +The above command copies all branches from the remote refs/heads/ +namespace and stores them to the local refs/remotes/origin/ namespace, +unless the branch..fetch option is used to specify a non-default +refspec. + +* Using refspecs explicitly: ++ +------------------------------------------------ +$ git fetch origin +pu:pu maint:tmp +------------------------------------------------ ++ +This updates (or creates, as necessary) branches `pu` and `tmp` in +the local repository by fetching from the branches (respectively) +`pu` and `maint` from the remote repository. ++ +The `pu` branch will be updated even if it is does not fast-forward, +because it is prefixed with a plus sign; `tmp` will not be. + + SEE ALSO -------- linkgit:git-pull[1] diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index d05f324462..e886c2ef54 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -212,6 +212,39 @@ You can work through the conflict with a number of tools: common ancestor, 'git show :2:filename' shows the HEAD version and 'git show :3:filename' shows the remote version. + +EXAMPLES +-------- + +* Merge branches `fixes` and `enhancements` on top of + the current branch, making an octopus merge: ++ +------------------------------------------------ +$ git merge fixes enhancements +------------------------------------------------ + +* Merge branch `obsolete` into the current branch, using `ours` + merge strategy: ++ +------------------------------------------------ +$ git merge -s ours obsolete +------------------------------------------------ + +* Merge branch `maint` into the current branch, but do not make + a new commit automatically: ++ +------------------------------------------------ +$ git merge --no-commit maint +------------------------------------------------ ++ +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. + + SEE ALSO -------- linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 7578623edb..de2bcd63bb 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -131,54 +131,13 @@ $ git pull origin next ------------------------------------------------ + This leaves a copy of `next` temporarily in FETCH_HEAD, but -does not update any remote-tracking branches. - -* Bundle local branch `fixes` and `enhancements` on top of - the current branch, making an Octopus merge: +does not update any remote-tracking branches. Using remote-tracking +branches, the same can be done by invoking fetch and merge: + ------------------------------------------------ -$ git pull . fixes enhancements +$ git fetch origin +$ git merge origin/next ------------------------------------------------ -+ -This `git pull .` syntax is equivalent to `git merge`. - -* Merge local branch `obsolete` into the current branch, using `ours` - merge strategy: -+ ------------------------------------------------- -$ git pull -s ours . obsolete ------------------------------------------------- - -* Merge local branch `maint` into the current branch, but do not make - a commit automatically: -+ ------------------------------------------------- -$ git pull --no-commit . maint ------------------------------------------------- -+ -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. - -* Command line pull of multiple branches from one repository: -+ ------------------------------------------------- -$ git checkout master -$ git fetch origin +pu:pu maint:tmp -$ git pull . tmp ------------------------------------------------- -+ -This updates (or creates, as necessary) branches `pu` and `tmp` in -the local repository by fetching from the branches (respectively) -`pu` and `maint` from the remote repository. -+ -The `pu` branch will be updated even if it is does not fast-forward; -the others will not be. -+ -The final command then merges the newly fetched `tmp` into master. If you tried a pull which resulted in a complex conflicts and