From: Thomas Rast <trast@student.ethz.ch>
Date: Fri, 23 Dec 2011 16:56:48 GMT
Subject: Re: [PATCH] fix shell command line in example
Message-ID: <8739cbi5v3.fsf@thomas.inf.ethz.ch>
In-Reply-To: <20111223164128.GA21918@gnu.kitenet.net>

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