Skip to contentSkip to conversation

fix shell command line in example

PATCH In review Joey Hess 2 participants 3 messages Jun 15, 2016 Documentation

lore
Share & tools
lore

Joey Hess

author
#0 lore raw

PATCH 1/1 fix shell command line in example

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

---
 Documentation/git-pull.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)
Documentation/git-pull.txt +1 -1
index 0f18ec8..628695d 100644
@@ -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,
Signature · 1 line
1.7.7.3
#1 lore raw
Quoted 2 lines · Joey Hess

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

[...]

Quoted 4 lines

------------------------------------------------
-$ 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.

Signature · 2 lines
Thomas Rast
trast@{inf,student}.ethz.ch
author
#2 lore raw
Quoted 8 lines · Thomas Rast

* 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).

Signature · 1 line
see shy jo