[PATCH] fix shell command line in example

[PATCH] fix shell command line in example

[Joey Hess]

The comma was probably intended to be a semicolon so that the
two commands can be run by cut-n-paste.

Signed-off-by: Joey Hess <joey@kitenet.net>
---
 Documentation/git-pull.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 0f18ec8..628695d 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -194,7 +194,7 @@ EXAMPLES
   current branch:
 +
 ------------------------------------------------
-$ git pull, git pull origin
+$ git pull; git pull origin
 ------------------------------------------------
 +
 Normally the branch merged in is the HEAD of the remote repository,
-- 
1.7.7.3

Re: [PATCH] fix shell command line in example

[Thomas Rast]

Joey Hess <joey@kitenet.net> writes:

> The comma was probably intended to be a semicolon so that the
> two commands can be run by cut-n-paste.
[...]
>  ------------------------------------------------
> -$ git pull, git pull origin
> +$ git pull; git pull origin
>  ------------------------------------------------

Would it ever make sense to run the two in sequence?

But upon closer reading, it seems to be a pretty terrible example
anyway.  It reads:

  * Update the remote-tracking branches for the repository
    you cloned from, then merge one of them into your
    current branch:
  +
  ------------------------------------------------
  $ git pull, git pull origin
  ------------------------------------------------
  +
  Normally the branch merged in is the HEAD of the remote repository,
  but the choice is determined by the branch.<name>.remote and
  branch.<name>.merge options; see linkgit:git-config[1] for details.

But that "normally" is no longer true: with default configs, the user
would only ever have branches with tracking already set up.  So
*normally*, 'git pull' will merge the @{upstream}.

'git pull origin' is even worse: with tracking configured, it goes out
of its way to verify that the specified remote (origin) is actually what
HEAD tracks[*].  So 'git pull origin' with default configs means "please
pull, but double-check me on the choice of remote".  Do we want to give
that to a user as the second example?

So I'm thinking it should just read

  * Update the upstream origin of the current branch, then merge the
    tracked branch into the current one:
  +
  --------------------------------------------------
  $ git pull
  --------------------------------------------------

modulo avoiding confusion around upstream/tracking.


[*] a8c9bef (pull: improve advice for unconfigured error case,
2009-10-05) has a long explanation on the subject.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH] fix shell command line in example

[Joey Hess]

[-- Attachment #1: Type: text/plain, Size: 929 bytes --]

Thomas Rast wrote:
>   * Update the upstream origin of the current branch, then merge the
>     tracked branch into the current one:
>   +
>   --------------------------------------------------
>   $ git pull
>   --------------------------------------------------
> 
> modulo avoiding confusion around upstream/tracking.

I support having a simple "git pull" example; I think it's the first
thing users should be reaching for, followed perhaps by "git pull foo bar"
when they have multiple remotes. 

Still, an example of pulling all tracking branches from a remote and
merging in the right one for the currently checked out branch would be
good to have, that's also a common need when using git without a
centralized origin. AFAICS, there's no way to do all that in a single
git pull command? My feeling was that this sort of scenario was what
the example was trying to do (rather badly).

-- 
see shy jo

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 828 bytes --]