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

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