Re: [PATCH] Clarify that '--tags' fetches tags only

Michael Witten [off-list ref] writes:

On Wed, Sep 21, 2011 at 23:52, Anatol Pomozov [off-list ref] wrote:

quoted

+       linkgit:git-config[1]. Note that if this option is specified
+       then only tags are fetched, refs under refs/heads/* stay unchanged.

Note that if this option is specified, then only tags
are fetched; refs under refs/heads/* are not changed.

Can we improve the wording without singling out refs/heads/* specifically?

I think the updated wording is not desirable for two reasons.

For one thing, for the most newbies, I think refs/remotes/origin/* (not
refs/heads/*) would be the hierarchy that they may expect to get updated
and surprised.

When you give --tags (or any other refspec for that matter; --tags is
merely a short-hand for "refs/tags/*:refs/tags/*") explicitly from the
command line, you are overriding the refspecs configured for the remote,
and all the refs that are _not_ covered by the refspec you gave from the
command line will stay unchanged, not just refs/heads/* but refs under
other hierarchies (like refs/remotes/* and refs/notes/*). 

Once the reader understands that the command line _overrides_ the
configured fetch refspecs, everything else should fall naturally into
place without further explanation.  For example,

	$ git pull origin frotz

would internally invoke "git fetch origin another_branch", and it would
not update any refs for the _same exact reason_ [*1*].  You are giving a
refspec from the command line (in this case, "grab refs/heads/frotz, but
do not store it anywhere"), and it overrides the usual fetch refspec that
may update "+refs/heads/*:refs/remotes/origin/*" (grab all refs at the
origin under refs/heads/ hierarchy, and store in refs/remotes/origin).


[Footnote]

*1* The merging of the result would update the current branch but that is
a natural consequence of "a pull integrates by running either a merge or a
rebase after running a fetch".

On Thu, Sep 22, 2011 at 00:49, Junio C Hamano [off-list ref] wrote:

--tags is merely a short-hand for "refs/tags/*:refs/tags/*")
explicitly from the command line

[Disclaimer: I don't know the code or the semantics]

Why not just use that explanation?

  This option is merely a short-hand for writing
  the refspec `refs/tags/*:refs/tags/*'; consequently,
  using this option overrides any default refspec that
  would be used if no refspec were provided on the
  command line. That is,

    git fetch --tags origin frotz

  is equivalent to:

    git fetch origin frotz 'refs/tags/*:refs/tags/*'

In fact, if the command line parsing performed by `git fetch'
is reasonably intelligent, then it might be worthwhile
to relocate `--tags' in the example:

  That is,

    git fetch origin frotz --tags

  is equivalent to:

    git fetch origin frotz 'refs/tags/*:refs/tags/*'

On Thu, Sep 22, 2011 at 02:01, Michael Witten [off-list ref] wrote:

On Thu, Sep 22, 2011 at 00:49, Junio C Hamano [off-list ref] wrote:

quoted

--tags is merely a short-hand for "refs/tags/*:refs/tags/*")
explicitly from the command line

[Disclaimer: I don't know the code or the semantics]

Why not just use that explanation?

 This option is merely a short-hand for writing
 the refspec `refs/tags/*:refs/tags/*'; consequently,
 using this option overrides any default refspec that
 would be used if no refspec were provided on the
 command line. That is,

   git fetch --tags origin frotz

 is equivalent to:

   git fetch origin frotz 'refs/tags/*:refs/tags/*'

In fact, if the command line parsing performed by `git fetch'
is reasonably intelligent, then it might be worthwhile
to relocate `--tags' in the example:

 That is,

   git fetch origin frotz --tags

 is equivalent to:

   git fetch origin frotz 'refs/tags/*:refs/tags/*'

Maybe this is less confusing for the example:

  That is,

    git fetch origin --tags
    git fetch origin frotz --tags bar

  are equivalent to:

    git fetch origin 'refs/tags/*:refs/tags/*'
    git fetch origin frotz 'refs/tags/*:refs/tags/*' bar

On 22 September 2011 12:07, Michael Witten [off-list ref] wrote:

On Thu, Sep 22, 2011 at 02:01, Michael Witten [off-list ref] wrote:

quoted

On Thu, Sep 22, 2011 at 00:49, Junio C Hamano [off-list ref] wrote:

quoted

--tags is merely a short-hand for "refs/tags/*:refs/tags/*")
explicitly from the command line

[Disclaimer: I don't know the code or the semantics]

Why not just use that explanation?

 This option is merely a short-hand for writing
 the refspec `refs/tags/*:refs/tags/*'; consequently,
 using this option overrides any default refspec that
 would be used if no refspec were provided on the
 command line. That is,

   git fetch --tags origin frotz

 is equivalent to:

   git fetch origin frotz 'refs/tags/*:refs/tags/*'

In fact, if the command line parsing performed by `git fetch'
is reasonably intelligent, then it might be worthwhile
to relocate `--tags' in the example:

 That is,

   git fetch origin frotz --tags

 is equivalent to:

   git fetch origin frotz 'refs/tags/*:refs/tags/*'

Maybe this is less confusing for the example:

 That is,

   git fetch origin --tags
   git fetch origin frotz --tags bar

 are equivalent to:

   git fetch origin 'refs/tags/*:refs/tags/*'
   git fetch origin frotz 'refs/tags/*:refs/tags/*' bar

This will only help people who understand that tags are just refs
stored in refs/tags, and who understand the 'ref:ref' syntax. I think
it is a good example to have, but people can understand the process
and results of 'pulling/fetching a tag' without necessarily needing to
know that tags are stored somewhere, or knowing the exact fetch
mechanism. If these need to be documented, it should be in the
appropriate place (which I don't think is here).

I think we are skirting around the real issue, and that is that
pulling tags will often grab objects that are *meant* to be on a
remote branch (from the user's perspective) but that appear to be
hanging because the remote branch ref was not updated at the same
time. Perhaps an example or explanation of why this is the case would
be more useful?

Maybe:

Note that if this option is specified, then only tags
are fetched. No other refs, such as a remote tracking
branch, will be updated, even if it has been updated
on the remote end.

extra info on how this option is merely a short-hand for writing the
refspec `refs/tags/*:refs/tags/* could go here


Regards,
Andrew

On Thu, Sep 22, 2011 at 03:13, Andrew Ardill [off-list ref] wrote:

On 22 September 2011 12:07, Michael Witten [off-list ref] wrote:

quoted

On Thu, Sep 22, 2011 at 02:01, Michael Witten [off-list ref] wrote:

quoted

On Thu, Sep 22, 2011 at 00:49, Junio C Hamano [off-list ref] wrote:

quoted

--tags is merely a short-hand for "refs/tags/*:refs/tags/*")
explicitly from the command line

[Disclaimer: I don't know the code or the semantics]

Why not just use that explanation?

 This option is merely a short-hand for writing
 the refspec `refs/tags/*:refs/tags/*'; consequently,
 using this option overrides any default refspec that
 would be used if no refspec were provided on the
 command line. That is,

   git fetch --tags origin frotz

 is equivalent to:

   git fetch origin frotz 'refs/tags/*:refs/tags/*'

In fact, if the command line parsing performed by `git fetch'
is reasonably intelligent, then it might be worthwhile
to relocate `--tags' in the example:

 That is,

   git fetch origin frotz --tags

 is equivalent to:

   git fetch origin frotz 'refs/tags/*:refs/tags/*'

Maybe this is less confusing for the example:

 That is,

   git fetch origin --tags
   git fetch origin frotz --tags bar

 are equivalent to:

   git fetch origin 'refs/tags/*:refs/tags/*'
   git fetch origin frotz 'refs/tags/*:refs/tags/*' bar

This will only help people who understand that tags are just refs
stored in refs/tags, and who understand the 'ref:ref' syntax. I think
it is a good example to have, but people can understand the process
and results of 'pulling/fetching a tag' without necessarily needing to
know that tags are stored somewhere, or knowing the exact fetch
mechanism. If these need to be documented, it should be in the
appropriate place (which I don't think is here).

I think we are skirting around the real issue, and that is that
pulling tags will often grab objects that are *meant* to be on a
remote branch (from the user's perspective) but that appear to be
hanging because the remote branch ref was not updated at the same
time. Perhaps an example or explanation of why this is the case would
be more useful?

Maybe:

Note that if this option is specified, then only tags
are fetched. No other refs, such as a remote tracking
branch, will be updated, even if it has been updated
on the remote end.

extra info on how this option is merely a short-hand for writing the
refspec `refs/tags/*:refs/tags/* could go here

Junio just explained why your description is inadequate and confusing.

There's so much confusion around git exactly because people are always
trying to hide just WTF is going on (especially by using TERRIBLE
terms like `branch'; see my numerous discussions).

If I were a newbie and were to read the text that I just proferred as
a clarification of --tags, then I would next look up just WTF a
refspec is, and then a branch, and then...

You see? That's exactly how it should work. People should be given
descriptions that arm them with the terms necessary to look up more
information. We need to stop writing documentation for that
hypothetical idiot who doesn't know his ass from his own face. We need
to cater to those people who intend to read documentation for the
purpose of understanding the system---not for the purpose of gettin'
shit dun with any half-baked notion that is good enough for the most
simplistic situation.

I'm sending in a patch presently.

See the discussion starting here:

  [PATCH] Clarify that '--tags' fetches tags only
  Message-ID: [off-list ref]
  http://thread.gmane.org/gmane.comp.version-control.git/180636

Suggested-by: Anatol Pomozov <redacted>
Signed-off-by: Michael Witten <redacted>
---
 Documentation/fetch-options.txt |   21 ++++++++++++++++++---
 1 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 39d326a..fb743fa 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt

@@ -61,9 +61,24 @@ ifndef::git-pull[]
 	objects reachable from the branch heads that are being
 	tracked will not be fetched by this mechanism.  This
 	flag lets all tags and their associated objects be
-	downloaded. The default behavior for a remote may be
-	specified with the remote.<name>.tagopt setting. See
-	linkgit:git-config[1].
+	downloaded.
++
+This option is merely a short-hand for writing the
+refspec `refs/tags/\*:refs/tags/\*'; consequently,
+using this option overrides any default refspec that
+would be used if no refspec were provided on the
+command line. That is,
++
+	git fetch origin --tags
+	git fetch origin frotz --tags bar
++
+are equivalent to:
++	
+	git fetch origin 'refs/tags/*:refs/tags/*'
+	git fetch origin frotz 'refs/tags/*:refs/tags/*' bar
++
+The default behavior for a remote may be specified with
+the remote.<name>.tagopt setting. See linkgit:git-config[1].
 
 --recurse-submodules[=yes|on-demand|no]::
 	This option controls if and under what conditions new commits of

-- 
1.7.6.409.ge7a85

On Thu, Sep 22, 2011 at 03:39, Michael Witten [off-list ref] wrote:

...
+This option is merely a short-hand for writing the
...

Junio, make that `shorthand', if you please.