git fetch documentation problem or bug

git fetch documentation problem or bug

[Angelo Borsotti]

Hello,

git fetch <repository> <refspec> does not create the remote refs in
the current (local)
repository, as shown by the following script:

git init remote
git clone remote local

# populate the remote repository with a commit
cd remote
touch f1
git add f1
git commit -m A

cd ../local
git fetch origin master
git branch -avv

No ref is created.

However, if a git fetch origin is executed, the refs are properly created:

git fetch origin
 * [new branch]      master     -> origin/master
  remotes/origin/master 8a9186d A

I have not seen any clue in the documentation that tells the user
about this difference. The user may (naively) think that git fetch
origin downloads all branches, while git fetch origin <branch>
downloads only <branch>, but it is not so.
I am wandering if this is a documentation problem or a bug.

-Angelo

Re: git fetch documentation problem or bug

[Junio C Hamano]

Angelo Borsotti <angelo.borsotti@gmail.com> writes:

> git fetch <repository> <refspec> does not create the remote refs in
> the current (local)
> repository...
> However, if a git fetch origin is executed, the refs are properly created:

Working as designed and documented.

 $ git fetch origin master

is giving the refspec "master" from the command line which is a
short-hand for "refs/heads/master".

When you run

 $ git fetch origin

configured refspec is looked up from your config (because you didn't
give any from the command line).  The default refspec in your config
is likely to be "refs/heads/*:refs/remotes/origin/*".

The former, "refs/heads/master" refspec, tells Git not to update the
remote tracking branch.  The latter has colon and right-hand-side of
the colon tells Git what to update with what was fetched.

It would hlep to read up on refspec by running "git fetch --help"
and looking for a string "colon".

Re: git fetch documentation problem or bug

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Angelo Borsotti <angelo.borsotti@gmail.com> writes:
>
>> git fetch <repository> <refspec> does not create the remote refs in
>> the current (local)
>> repository...
>> However, if a git fetch origin is executed, the refs are properly created:
>
> Working as designed and documented.
>
>  $ git fetch origin master
>
> is giving the refspec "master" from the command line which is a
> short-hand for "refs/heads/master".
>
> When you run
>
>  $ git fetch origin
>
> configured refspec is looked up from your config (because you didn't
> give any from the command line).  The default refspec in your config
> is likely to be "refs/heads/*:refs/remotes/origin/*".
>
> The former, "refs/heads/master" refspec, tells Git not to update the
> remote tracking branch.  The latter has colon and right-hand-side of
> the colon tells Git what to update with what was fetched.
>
> It would hlep to read up on refspec by running "git fetch --help"
> and looking for a string "colon".

Addendum.  Your claim

>> git fetch <repository> <refspec> does not create the remote refs in
>> the current (local)
>> repository...

is incorrect.  The behaviour depends on what <refspec> you give.

In other words, you can do this from the command line if you want
to do the update.

  $ git fetch origin master:refs/remotes/origin/master

Re: git fetch documentation problem or bug

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> In other words, you can do this from the command line if you want
> to do the update.
>
>   $ git fetch origin master:refs/remotes/origin/master

Now having said all that, we should probably revisit this and
possibly other issues and for the ones we can reach concensus, start
coding after 1.8.0 final.

A good place to start may be $gmane/167149, where I listed (among
other things that turned out to be undesirable, which are omitted in
this copy):

 * "git branch --set-upstream <name>" should not be about setting the
   upstream of <name> to the current branch.

   This has happened during 1.8.0 cycle [CMN].

 * "git push" default semantics will be "upstream" (renamed from
   "tracking"), not "matching".

   1.8.0 has the first step toward this [MM].

 * "git merge" without "what to merge" default to @{upstream}

   This is not acceptable for the default, but the users can ask for
   it with merge.defaultToUpstream since 1.7.5 era [JC]

 * Unify pathspec semantics

   This has happened and commands that used to take only path prefix
   style pathspecs now take globs as well [ND]

 * "git fetch $from $branch..." to update tracking branches

   This is the topic in this thread.

I personally do not think the downside of breaking backward
compatibility is too bad.  If we do this only when we already are
configured to keep remote tracking branch for branch $branch from
remote $from (it has to be given as a nickname, not URL that happens
to have an entry in the configuration), then a promiscuous fetch
that grabs from a URL (or a nickname that is configured not to keep
tracking branches) will not change any behaviour, and when you want
to keep your remote tracking branch intact while doing one-shot
fetch for whatever reason, you can say "git fetch $from $branch:" to
explicitly decline copying.

Re: git fetch documentation problem or bug

[Nguyen Thai Ngoc Duy]

On Tue, Oct 9, 2012 at 6:33 AM, Junio C Hamano <gitster@pobox.com> wrote:
>  * Unify pathspec semantics
>
>    This has happened and commands that used to take only path prefix
>    style pathspecs now take globs as well [ND]

I've been thinking about it lately and will probably restart soon with
a different approach. Still need to think about git-rm and git-mv as
they also accept directories (i.e. not exactly pathspec by
definition).
-- 
Duy

Re: git fetch documentation problem or bug

[Drew Northup]

On Mon, Oct 8, 2012 at 7:33 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> In other words, you can do this from the command line if you want
>> to do the update.
>>
>>   $ git fetch origin master:refs/remotes/origin/master
>
> Now having said all that, we should probably revisit this and
> possibly other issues and for the ones we can reach concensus, start
> coding after 1.8.0 final.

>  * "git fetch $from $branch..." to update tracking branches
>
>    This is the topic in this thread.
>
> I personally do not think the downside of breaking backward
> compatibility is too bad.  If we do this only when we already are
> configured to keep remote tracking branch for branch $branch from
> remote $from (it has to be given as a nickname, not URL that happens
> to have an entry in the configuration), then a promiscuous fetch
> that grabs from a URL (or a nickname that is configured not to keep
> tracking branches) will not change any behaviour, and when you want
> to keep your remote tracking branch intact while doing one-shot
> fetch for whatever reason, you can say "git fetch $from $branch:" to
> explicitly decline copying.

How are we supposed to remember those are different?

"git fetch $from $branch..."
VS
"git fetch $from $branch:"

I strongly prefer EXPLICITLY setting tracking than expecting some
extreme syntactic nuance to quietly do it for me now and confuse the
heck out of me later.

-- 
-Drew Northup
--------------------------------------------------------------
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: git fetch documentation problem or bug

[Junio C Hamano]

Drew Northup <n1xim.email@gmail.com> writes:

> On Mon, Oct 8, 2012 at 7:33 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>
>> I personally do not think the downside of breaking backward
>> compatibility is too bad.  If we do this only when we already are
>> configured to keep remote tracking branch for branch $branch from
>> remote $from (it has to be given as a nickname, not URL that happens
>> to have an entry in the configuration), then a promiscuous fetch
>> that grabs from a URL (or a nickname that is configured not to keep
>> tracking branches) will not change any behaviour, and when you want
>> to keep your remote tracking branch intact while doing one-shot
>> fetch for whatever reason, you can say "git fetch $from $branch:" to
>> explicitly decline copying.
>
> How are we supposed to remember those are different?
>
> "git fetch $from $branch..."
> VS
> "git fetch $from $branch:"

I do not know what you meant by the three dots, but you are supposed
to know what you meant by $branch... whatever it is.  It is what you
wrote, not I did ;-)

Let me clarify what is in the message you are responding to.

	git fetch $from $branch

(no colon in $branch part anywhere) traditionally meant a short-hand
of saying

	git fetch $from $branch:

I.e. "fetch $branch and store in FETCH_HEAD but not anywhere else".

The hypothesized change is to make it a short-hand of saying

	git fetch $from $branch:refs/remotes/$from/$branch

when "git fetch $from" is already configured to store the result
there. 

Without [remote "$from"] fetch = refs/heads/*:refs/remotes/$from/*
configured, it will still mean "git fetch $from $branch:".

And for the record, I am *not* enthused about such a change.  I am
only saying that, seeing that many new people seem to wish the
command behaved that way, such a change would not hurt existing
users too much.  Switching the meaning of shorthand (i.e. a piece of
refspec that does not have any colon) from "just fetch but do not
store" from "fetch and store in the remote tracking ref if it is
configured to do so without command override" is still a backward
incompatible change.

> I strongly prefer EXPLICITLY setting tracking than expecting some
> extreme syntactic nuance to quietly do it for me now and confuse the
> heck out of me later.

This is not about your preference.  This is about what happens when
you say something on the command line to override your explicit
setting you have in $GIT_DIR/config

	[remote "$from"] fetch = ...