Re: [PATCH] fix shell command line in example

Joey Hess <joey@kitenet.net> writes:

[...]

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.