Re: [PATCH] Correct git-pull documentation

Jay Soffian [off-list ref] writes:

The --rebase option was documented in the wrong place (under MERGE
STRATEGIES instead of OPTIONS). Noted the branch.<name>.rebase
option and clarified the use '.' in a few places. Switched
"git-<command>" to "git command".

Clarifying that --rebase is not a strategy is a good
improvement.  Thanks.

I am not sure if this special case deserves mentioning here.

-In order to determine what URL to use to fetch from, the value
-of the configuration `remote.<origin>.url` is consulted
-and if there is not any such variable, the value on `URL: ` line
-in `$GIT_DIR/remotes/<origin>` file is used.
+Unless pulling from the local repository, a URL must be determined
+for the origin. This is done by first consulting
+`remote.<origin>.url`. If there is not any such variable, the value
+on `URL: ` line in `$GIT_DIR/remotes/<origin>` file is used.

Likewise.

Likewise.  That is a very roundabout way to say "git rebase
master".  It happens to work as a logical consequence of two
facts (1) that you can pull from any remote and (2) that "." is
a valid remote that names local.  I am personally happy that the
command works consistently, but I think we should rather teach
people the more natural way to do their rebase in our
documentation.

The fact that we earlier talked about "git pull ." does not
justify this addition.  Even though "git pull ." is also a
roundabout way, it used to be the only way (we did not have the
"git merge" callable as the top-level command) and there are
existing documents that show the "git pull ." form out there on
the web, and that is the primary reason we mention this ancient
form, so that people who saw such an ancient notation can find
out what it is about in our documentation.  Some people still
prefer it from pure inertia, and we have no reason to deprecate
it, but I do not think it is something we should advertise as
the first class interface.

On Feb 16, 2008 4:31 AM, Junio C Hamano [off-list ref] wrote:

Jay Soffian [off-list ref] writes:

quoted

The --rebase option was documented in the wrong place (under MERGE
STRATEGIES instead of OPTIONS). Noted the branch.<name>.rebase
option and clarified the use '.' in a few places. Switched
"git-<command>" to "git command".

Clarifying that --rebase is not a strategy is a good
improvement.  Thanks.

quoted

@@ -55,12 +57,13 @@ Often people use `git pull` without giving any parameter.
 Traditionally, this has been equivalent to saying `git pull
 origin`.  However, when configuration `branch.<name>.remote` is
 present while on branch `<name>`, that value is used instead of
-`origin`.
+`origin`. (`branch.<name>.remote` may be set to `.` to pull from
+the local repository by default.)

I am not sure if this special case deserves mentioning here.

Sigh, this is getting a bit frustrating. Yes you can use "fetch + merge" or
"fetch + rebase", but what I'm trying to get at here is that if the user
configures their branch appropriately, they can just use "git pull" and it
will just Do The Right Thing. But for that to work, the user has to know to
set branch.<name>.remote to "." and the git-pull documentation seems like the
right place to mention it.

quoted

-In order to determine what URL to use to fetch from, the value
-of the configuration `remote.<origin>.url` is consulted
-and if there is not any such variable, the value on `URL: ` line
-in `$GIT_DIR/remotes/<origin>` file is used.
+Unless pulling from the local repository, a URL must be determined
+for the origin. This is done by first consulting
+`remote.<origin>.url`. If there is not any such variable, the value
+on `URL: ` line in `$GIT_DIR/remotes/<origin>` file is used.

Likewise.

Likewise what? All I did was clarify the existing paragraph which was wrong in
the case where remote is set to "."

quoted

@@ -138,6 +141,9 @@ 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.

+git pull --rebase . master::
+     This syntax is equivalent to calling `git rebase master`; see
+     linkgit:git-rebase[1] for details.

Likewise.  That is a very roundabout way to say "git rebase
master".  It happens to work as a logical consequence of two
facts (1) that you can pull from any remote and (2) that "." is
a valid remote that names local.  I am personally happy that the
command works consistently, but I think we should rather teach
people the more natural way to do their rebase in our
documentation.

The fact that we earlier talked about "git pull ." does not
justify this addition.  Even though "git pull ." is also a
roundabout way, it used to be the only way (we did not have the
"git merge" callable as the top-level command) and there are
existing documents that show the "git pull ." form out there on
the web, and that is the primary reason we mention this ancient
form, so that people who saw such an ancient notation can find
out what it is about in our documentation.  Some people still
prefer it from pure inertia, and we have no reason to deprecate
it, but I do not think it is something we should advertise as
the first class interface.

I want to be able to use "git pull" (w/o any options) and have it figure out
based on my configuration what to do with the current branch, be it:

1. merge another local branch.
1. rebase from another local branch.
3. fetch+merge from remote.
4. fetch+rebase from remote.

And in fact, I can. But to do so, I have to know that "." means local, so why
not advertise that fact in git-pull?

j.