On 10/24/2013 11:11 PM, Junio C Hamano wrote:
> Michael Haggerty <[email protected]> writes:
>
>> ...
>> Signed-off-by: Michael Haggerty <[email protected]>
>
> Everything in the proposed log message made sense to me.
>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> index d4d93c9..83c1700 100644
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -2086,7 +2086,7 @@ remote.<name>.vcs::
>> remote.<name>.prune::
>> When set to true, fetching from this remote by default will also
>> remove any remote-tracking branches which no longer exist on the
>> - remote (as if the `--prune` option was give on the command line).
>> + remote (as if the `--prune` option was given on the command line).
>
> Shouldn't we stop saying "branches" here?
>
>> diff --git a/Documentation/fetch-options.txt
>> b/Documentation/fetch-options.txt
>> index 0e6d2ac..5d12219 100644
>> --- a/Documentation/fetch-options.txt
>> +++ b/Documentation/fetch-options.txt
>> @@ -41,8 +41,14 @@ ifndef::git-pull[]
>>
>> -p::
>> --prune::
>> - After fetching, remove any remote-tracking branches which
>> - no longer exist on the remote.
>> + After fetching, remove any remote-tracking branches that
>
> Likewise. This is a lot more important than the one in
> remote.<name>.prune documentation, as the next sentence "Tags are
> not subject to ..." implies that they fall into the same category as
> what gets pruned here, i.e. "remote-tracking branches" in the above
> sentence, but nobody calls refs/tags/v1.0.0 a "remote-tracking
> branch" even if it came from your 'origin'.
OK, I will change both of the above from "remote-tracking branches" to
"remote-tracking references".
>> + no longer exist on the remote. Tags are not subject to
>> + pruning in the usual case that they are fetched because of the
>> + --tags option or remote.<name>.tagopt.
>
> We should mention the most usual case tags are fetched, before
> mentioning the case the unusual option "--tags" was used from the
> command line or .tagopt configuration was used. Namely, when the
> tags are automatically followed.
OK, I will change this in the next draft.
>> @@ -63,7 +69,10 @@ ifndef::git-pull[]
>> --tags::
>> This is a short-hand requesting that all tags be fetched from
>> the remote in addition to whatever else is being fetched. It
>> - is similar to using the refspec `refs/tags/*:refs/tags/*`.
>> + is similar to using the refspec `refs/tags/*:refs/tags/*`,
>> + except that it doesn't subject tags to pruning, regardless of
>> + a --prune option or the configuration settings of fetch.prune
>> + or remote.<name>.prune.
>
> Using --tags is not similar to using refs/tags/*:refs/tags/* after
> the previous patch already; "git fetch origin --tags" and "git fetch
> origin refs/tags/*:refs/tags/*" are vastly different and that was
> the whole point of the previous step. And that "calling something
> not so similar similar" needs to be fixed further here to clarify
> that they are not similar in yet another way.
>
> We should just lose "It is similar to using" from 10/15 and start
> over, perhaps? Add the first paragraph of the below in 10/15 and
> add the rest in 11/15, or something.
>
> --tags::
> Request that all tags be fetched from the remote
> under the same name (i.e. `refs/tags/X` is created in
> our repository by copying their `refs/tags/X`), in
> addition to whatever is fetched by the same `git
> fetch` command without this option on the command
> line.
> +
> When `refs/tags/*` hierarchy from the remote is copied only
> because this option was given, they are not subject to be
> pruned when `--prune` option (or configuration variables
> like `fetch.prune` or `remote.<name>.prune`) is in effect.
>
> That would make it clear that they are subject to pruning when --mirror
> or an explicit refspec refs/tags/*:refs/tags/* is given, as tags are
> not fetched "only because of --tags" in such cases.
I see your point. What do you think about the following version, which
is a bit more compact and refers the reader to --prune for the full story:
-t::
--tags::
Fetch all tags from the remote (i.e., fetch remote tags
`refs/tags/*` into local tags with the same name), in addition
to whatever else would otherwise be fetched. Using this
option does not subject tags to pruning, even if --prune is
used (though tags may be pruned anyway if they are also the
destination of an explicit refspec; see '--prune').
I also want to improve the description of tag auto-following in general.
I will send a re-rolled patch series in the next couple of days.
Thanks for your prompt and helpful advice!
Michael
--
Michael Haggerty
[email protected]
http://softwareswirl.blogspot.com/
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
