patchClarify that '--tags' fetches tags only

---
 Documentation/fetch-options.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

On Fri, 2011-09-02 at 14:04 -0700, Anatol Pomozov wrote:

Anatol, Looks like a sane change to me. You might want to check Documentation/SubmittingPatches in the git repository if you want Junio to include your patch. It is probably also worth CC-ing those whom did the previous work on that documentation and the tags code to make sure your change is correct.

'git fetch --tags' fetches tags only and leaves heads untouched. Many people are confused by the fact that 'git fetch --tags' does not fetch heads.

Signed-off-by: Anatol Pomozov <anatol.pomozov@gmail.com>
---
 Documentation/fetch-options.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

On Wed, Sep 21, 2011 at 23:52, Anatol Pomozov <anatol.pomozov@gmail.com> wrote:

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

Michael Witten <mfwitten@gmail.com> writes:

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 <gitster@pobox.com> wrote:

[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 <mfwitten@gmail.com> wrote:

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 <mfwitten@gmail.com> wrote:

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 <andrew.ardill@gmail.com> wrote:

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: <1314997486-29996-1-git-send-email-anatol.pomozov@gmail.com>
  http://thread.gmane.org/gmane.comp.version-control.git/180636

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

On Thu, Sep 22, 2011 at 03:39, Michael Witten <mfwitten@gmail.com> wrote:

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

Michael Witten <mfwitten@gmail.com> writes:

I do agree with you that it is a futile exercise to sweep fundamental concepts under the rug, fearing that they are too detailed and too hard for the casual readers. By understanding how simple the fundamental concepts and rules are, readers can have a coherent and clear mental model of the world and synthesize these fundamental rules to understand more complex operations the Porcelain commands offer to help every day tasks.

I however do not think, and I certainly did not mean, that the description of "--tags" option is necessarily the place we should bombard a new user with the term refspec and "refs/tags/*:refs/tags/*" syntax.

I expect the readers to, and I hope the documentation to help them to, understand the following three basic facts and rules before diving into descriptions of individual options, such as the paragraph we are discussing:

 * "git fetch" command serves two purposes:

   (1) It transfers objects the repository the command is invoked in does
   not have from the remote repository. The objects transferred are the
   commits that are necessary to complete the ancestry chain of _some_
   history, and data (i.e. trees and blobs) associated to use these
   commits.

   (2) It optionally can update the local refs (e.g. branches and tags)
   with copies of the refs taken from the remote repository.

 * In the above, the user needs to tell the command two things. One is
   "where the remote repository is". The other is "what refs to fetch and
   (optionally) how to store them". The latter "what to fetch" also
   determines what that "_some_ history" above is (i.e. everything
   reachable from the refs that are fetched).

 * "What to fetch and how to store" have a default, recorded in the
   repository configuration file, that is used when the user does not give
   that information to the command from the command line. If the user does
   give that information from the command line, that default is not used
   at all. IOW, the command line overrides the default.

With that understanding, the _only_ thing that "--tags" description needs to talk about is that it is an explicit way to give that "what to fetch and how to store" information from the command line. It instructs the command to fetch all the tags from the remote repository and store them locally.

If the logic flow of the document presents the list of options before helping the readers understand the above basic facts and rules, then I think _that_ is the problem with the document we need to be addressing, not the description of an individual option such as "--tags".

On Wed, 21 Sep 2011 21:28:15 -0700, Junio C Hamano wrote:

For at least the near term, this patch may do a pretty good job of achieving those goals without having to change too much; I do some careful maneuvering to avoid mentioning refspecs until quite late in the description.

8<-----------8<-----------8<-----------8<-----------8<-----------8<-----------

See the discussion starting here:

  [PATCH] Clarify that '--tags' fetches tags only
  Message-ID: <1314997486-29996-1-git-send-email-anatol.pomozov@gmail.com>
  http://thread.gmane.org/gmane.comp.version-control.git/180636

Suggested-by: Anatol Pomozov <anatol.pomozov@gmail.com>
Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/fetch-options.txt |   31 +++++++++++++++++++++++--------
 1 files changed, 23 insertions(+), 8 deletions(-)

Michael Witten <mfwitten@gmail.com> writes:

It is a good practice to point to earlier discussions while polishing patch, and it also is good to include pointers in the commit log message as a supporting material (additional reading), but that is _NOT_ a substitute for a properly written commit log message. You need to state what problem you are trying to fix and how the proposed patch fixes it.

I would suggest clarifying the beginning of "git fetch --help" like the attached patch. With that knowledge at hand, the readers do not need the fuzzy "Most of ... are fetched" (leaving them wondering "what about the rest, and how that Most is determined?"); we only need to say something like "fetch all the tags from the remote and store them locally".

 Documentation/git-fetch.txt |   21 ++++++++++-----------
 1 files changed, 10 insertions(+), 11 deletions(-)

On Thu, Sep 22, 2011 at 17:10, Junio C Hamano <gitster@pobox.com> wrote:

The only problem is that none of what you say seems to be true.

  * The glossary very distinctly differentiates the
    term `branch' from `branch head'.

  * From skimming the code, it would seem that remote-tracking
    branch [*heads*] are not at all the determining factor for
    whether tags are automatically fetched. Rather, the
    determining factor is much more relaxed: Tags are fetched
    when a refspec's <dst> field is non-empty; it just so
    happens that a <dst> is usually non-empty because at least
    one remote-tracking branch [*head*] is being updated, but
    keep in mind that the branch being updated need not be
    considered a remote-tracking branch.

On Thu, Sep 22, 2011 at 17:35, Michael Witten <mfwitten@gmail.com> wrote:

DAMNIT

That last bit should use the world `head':

  but keep in mind that the branch *head* being updated
  need not be considered a remote-tracking branch [*head*].

Michael Witten <mfwitten@gmail.com> writes:

No matter what you do, please do not introduce a bad example that violates the usual command line syntax convention to have subcommand (e.g. fetch), options meant for the subcommand (e.g. --tags) and then other arguments.

On Wed, 21 Sep 2011 21:00:51 -0700, Junio C Hamano wrote:

Too bad; I think it really supplements the description well.

In any case:

  * The example has been changed as per your wish.
  * `short-hand' has been changed to `shorthand'.
  * Trailing whitespace has been removed from a line.

8<-----------8<-----------8<-----------8<-----------8<-----------8<-----------

See the discussion starting here:

  [PATCH] Clarify that '--tags' fetches tags only
  Message-ID: <1314997486-29996-1-git-send-email-anatol.pomozov@gmail.com>
  http://thread.gmane.org/gmane.comp.version-control.git/180636

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

On Wednesday, September 21, 2011 04:52:56 PM Anatol Pomozov wrote:

I like this clarification. It would be better placed before the note about the tagopt setting, as it clarifies the statement before that ("This flag lets all tags and their associated objects be downloaded.")

In fact, the optimal solution might be to rework that sentence with the clarification from yours, so something like "This flag lets all tags and their associated objects be downloaded instead of"...

Hi,

I just searched the List to see if there were any postings on "fetch --tags", because I was recently thrown for a loop by the fact the this command retrieves only tags (and commits needed to fulfill them). So I was very happy to find this discussion. I was actually trying to figure out whether the observed behavior is a bug, given that there is no mention of it in the documentation.

Perhaps it will be useful to say what would have been most helpful for me. In the current documentation for "fetch --tags", one sentence reads, "This flag lets all tags and their associated objects be downloaded." The following small modification would, IMO, be sufficient: "This flag causes all tags and their associated objects (only) to be downloaded."

Now I have a related question. I always want to retrieve all tags from tracking branches when I do a "git pull". Right now, if I want to do this, it seem (unless I am missing something) that I have to do "git fetch --tags; git fetch; git merge". Is there a way I can put something into my .git/config file so that I get this effect simply by doing a "git pull"? That's what I was trying to do when I added "tagopt = --tags".

Thanks, -P.

Peter Shenkin <shenkin@gmail.com> writes:

[...]

Actually fetching of branches on remote into remote-tracking branches would also fetch all tags that point to commits on fetched branches (so called "autofollow" feature).

If you want to fetch _all_ tags, you need to configure fetched branches (e.g. via glob refspec). I think that then "tagopt = --tags" works as expected then, as it is in addition to refspec not as the only refspec; "fetch = +refs/tags/*:refs/tags/*" should work as well.

HTH

On Fri, Sep 30, 2011 at 02:51, Peter Shenkin <shenkin@gmail.com> wrote:

Well, you're missing the fact that it not only causes those to be downloaded, but it also causes the defaults to be ignored, which is why you don't get the other stuff. You can still tell git to fetch anything else you want in addition.

See here:

  [PATCH v3] Docs: Clarify the --tags option of `git fetch'
  Message-ID: <686c38876d5a4ad6bfac67ca77fe9bb3-mfwitten@gmail.com>
  http://article.gmane.org/gmane.comp.version-control.git/181887

Michael Witten <mfwitten <at> gmail.com> writes:

I was no longer missing it at the time I posted. 

But that is indeed what I was missing when I first encountered the behavior. The purpose of posting was to point out that with a very small change in the documentation, I would not have missed it.

-P.

On Sat, Oct 1, 2011 at 05:40, Peter Shenkin <shenkin@gmail.com> wrote:

However, my point was this:

  You can still tell git to fetch anything else you want in addition.

That point doesn't seem clear with your proposed alteration.

Michael Witten <mfwitten <at> gmail.com> writes:

Michael,

Yes, you are right. I am still missing how to do that.

Can you show me a sample fetch invocation that would have the effect of downloading all tags and also branch heads?

Thanks, -P.

On Sat, Oct 1, 2011 at 17:16, Peter Shenkin <shenkin@gmail.com> wrote:

Unfortunately, there's currently no way to tell "git fetch" to download whatever your configuration files specify as default, but you can at least be explicit by using what's called a "refspec" (which is documented in "git help fetch"):

  git fetch --tags origin '+refs/heads/*:refs/remotes/origin/*'

You could probably get your hands on the default refspec by rigging something up with "git symbolic-ref" and "git config", but that's so much hassle; currently, it is probably best just to run "git fetch" twice.

Sincerely, Michael Witten

You might also find this email insightful:

  http://article.gmane.org/gmane.comp.version-control.git/181911
  Message-ID: <7142366f54c44cea82542adf8aea5bb9-mfwitten@gmail.com>
  Subject: Re: any way to "re-sync" a bare repository against
               another bare repository?

Michael Witten <mfwitten <at> gmail.com> writes:

Well, Junio had just about convinced me that there was nothing wrong with the documentation -- just with the way I was reading it -- until I read the above.

I tried it and yes, it does do what I want. Which was not at all my expectation, having read Junio's comment about how the documentation is to be read.

Junio argued that the man-page mod I suggested -- namely, "This flag causes all tags and their associated objects (only) to be downloaded." -- was unneeded because the meaning, though correct, is clear already and therefore redundant.

But the real problem is that the reading he gives is just wrong.

I have the following in my .git/config file:

[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*
	tagopt = --tags
	url = <whatever>

Given this, I do not see how anyone could infer from anything in the documentation that

git fetch

would do anything different from:

git fetch --tags origin +refs/heads/*:refs/remotes/origin/*

If I am wrong about this, please cite chapter and verse.

The question is not how the --tags option should be documented, but rather why "--tags" should behave differently when the refspec is given on the commandline than when the refspec is given in the .git/config file.

In fact, I no longer think it is a documentation error. It is a just a really terrible implementation decision. If it was desired to allow "git fetch --tags" to work without using the user's specified refspec, then a "--no-heads" option should have been provided to override the user's refspec -- no matter where it was given.

Though a retrofit would likely break too many workflows, the best one might hope for now would likely be the addition of a "--heads" option, which would have the effect of bringing down the branch heads even though this would not normally be done."

But then it would still be necessary to say that "--tags" does not normally obey the user's refspec if given in the config file, but does if given on the command line.

I might still be missing something. If anyone thinks the current behavior is clear from a careful reading of the documentation, I would like to hear how that inference could be drawn. For no matter how one reads the --tags description, it seems it is wrong in one of the two cases.

It is either wrong for a refspec on the command-line (if you think it says it downloads tags only) or else it is wrong for refspec in the config file (if you think it says it downloads tags and heads).

On Sat, Oct 1, 2011 at 20:22, Peter Shenkin <shenkin@gmail.com> wrote:

Again, see here:

 [PATCH v3] Docs: Clarify the --tags option of `git fetch'
 Message-ID: <686c38876d5a4ad6bfac67ca77fe9bb3-mfwitten@gmail.com>
 http://article.gmane.org/gmane.comp.version-control.git/181887

namely:

    This option is merely a shorthand for writing the refspec
    `refs/tags/\*:refs/tags/\*'; that is,

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

    are equivalent to:

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

In other words, by writing "--tags", you are actually writing "refs/tags/\*:refs/tags/\*"; because you are stating an *explicit* refspec, "git fetch" doesn't bother with any *implicit* default in your config, which is consistent with how "git fetch" works.

It would probably be a good idea if there were a "--defaults", too.

Michael Witten <mfwitten <at> gmail.com> writes:
 

Yes, I understand that fully and it makes perfect sense.

But it leaves unexplained and undocumented the fact that the user's specification of an *additional* refspec is observed if the additional refspec is given on the command line but ignored if the additional refspec is given in the config file.

-P.

Peter Shenkin <shenkin <at> gmail.com> writes:

I have to take this back. It makes sense that a refspec on the cmdline overrides one in the config file.

I understand the behavior now, and Michael's suggestion of a --default to add the refspec in the config file to the cmdline is IMO a good one.

'Nuff said. (By me, anyway....)

Thanks for your help and patience, everyone.

-P.

Peter Shenkin <shenkin@gmail.com> writes:

Hmm, from time to time we seem to see this kind of documentation suggestion where:

 - We (try to) describe what xyzzy does by saying "This is what xyzzy
   does". We specifically do not say "In addition to what normally
   happens, xyzzy causes these additional things to happen."

 - The reader (somehow) assumes xyzzy does more than what we described in
   the documentation, even we did not say "In addition to..."; and then

 - A patch is proposed to add "these other things are _not_ done", after
   existing "This is what xyzzy does".

And it is not limited to the description of this particular option.

I think in general our documentation aims to spell out _all_ that happens, and explicitly say "In addition to what normally happens", "This page lists only the most common ways", etc., when such a clatification is needed.

I am wondering if there is a systemic failure that gives an impression that by default the documentation is incomplete and all other unspecified thing also happens to the readers? If so are there things that we could do better without going through individual description?

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

...
 

Yes, I would say that there is one obvious systemic failure.

Nowhere is it documented (as far as I am aware) that this is the way the git documentation should be read.

Since, in this regard, it differs from most software documentation, it ought itself to be documented, perhaps on the top-level git man page.

-P.