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

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

[Anatol Pomozov]

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

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 39d326a..37d2316 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -63,7 +63,8 @@ ifndef::git-pull[]
 	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].
+	linkgit:git-config[1]. Note that if this option is specified
+	then only tags are fetched, refs under refs/heads/* stay unchanged.
 
 --recurse-submodules[=yes|on-demand|no]::
 	This option controls if and under what conditions new commits of
-- 
1.7.7.rc0.72.g4b5ea.dirty

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

[Drew Northup]

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

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

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.

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

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

[Anatol Pomozov]

'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(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 39d326a..37d2316 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -63,7 +63,8 @@ ifndef::git-pull[]
 	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].
+	linkgit:git-config[1]. Note that if this option is specified
+	then only tags are fetched, refs under refs/heads/* stay unchanged.
 
 --recurse-submodules[=yes|on-demand|no]::
 	This option controls if and under what conditions new commits of
-- 
1.7.7.rc0.72.g4b5ea.dirty

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

[Michael Witten]

On Wed, Sep 21, 2011 at 23:52, Anatol Pomozov <anatol.pomozov@gmail.com> wrote:
> +       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.

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

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

> On Wed, Sep 21, 2011 at 23:52, Anatol Pomozov <anatol.pomozov@gmail.com> wrote:
>> +       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".

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

[Michael Witten]

On Thu, Sep 22, 2011 at 00:49, Junio C Hamano <gitster@pobox.com> 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/*'

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

[Michael Witten]

On Thu, Sep 22, 2011 at 02:01, Michael Witten <mfwitten@gmail.com> wrote:
> On Thu, Sep 22, 2011 at 00:49, Junio C Hamano <gitster@pobox.com> 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/*'
>

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

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

[Andrew Ardill]

On 22 September 2011 12:07, Michael Witten <mfwitten@gmail.com> wrote:
> On Thu, Sep 22, 2011 at 02:01, Michael Witten <mfwitten@gmail.com> wrote:
>> On Thu, Sep 22, 2011 at 00:49, Junio C Hamano <gitster@pobox.com> 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/*'
>>
>
> 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

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

[Michael Witten]

On Thu, Sep 22, 2011 at 03:13, Andrew Ardill <andrew.ardill@gmail.com> wrote:
> On 22 September 2011 12:07, Michael Witten <mfwitten@gmail.com> wrote:
>> On Thu, Sep 22, 2011 at 02:01, Michael Witten <mfwitten@gmail.com> wrote:
>>> On Thu, Sep 22, 2011 at 00:49, Junio C Hamano <gitster@pobox.com> 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/*'
>>>
>>
>> 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.

[PATCH] Docs: Clarify the --tags option of `git fetch'

[Michael Witten]

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

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

Re: [PATCH] Docs: Clarify the --tags option of `git fetch'

[Michael Witten]

On Thu, Sep 22, 2011 at 03:39, Michael Witten <mfwitten@gmail.com> wrote:
> ...
> +This option is merely a short-hand for writing the
> ...

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

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

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

> On Thu, Sep 22, 2011 at 03:13, Andrew Ardill <andrew.ardill@gmail.com> wrote:
>>
>> 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.
> ...
> 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...

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

[PATCH v3] Docs: Clarify the --tags option of `git fetch'

[Michael Witten]

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

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

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

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 39d326a..4cc5a80 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -56,14 +56,29 @@ endif::git-pull[]
 ifndef::git-pull[]
 -t::
 --tags::
-	Most of the tags are fetched automatically as branch
-	heads are downloaded, but tags that do not point at
-	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].
+	Most of a remote's tags are fetched automatically as branches are
+	downloaded. However, git does not automatically fetch any tag that,
+	when 'git fetch' completes, would not be reachable from any local
+	branch head.  This option tells git to fetch all tags (and their
+	associated objects).
++
+The 'git fetch' command is often supplied with a default set of branch
+heads to fetch, but using this option tells 'git fetch' to ignore those
+defaults.
++
+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/*'
++
+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

Re: [PATCH v3] Docs: Clarify the --tags option of `git fetch'

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

> 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

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.

>  Documentation/fetch-options.txt |   31 +++++++++++++++++++++++--------
>  1 files changed, 23 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
> index 39d326a..4cc5a80 100644
> --- a/Documentation/fetch-options.txt
> +++ b/Documentation/fetch-options.txt
> @@ -56,14 +56,29 @@ endif::git-pull[]
>  ifndef::git-pull[]
>  -t::
>  --tags::
> -	Most of the tags are fetched automatically as branch
> -	heads are downloaded, but tags that do not point at
> -	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].
> +	Most of a remote's tags are fetched automatically as branches are
> +	downloaded. However, git does not automatically fetch any tag that,
> +	when 'git fetch' completes, would not be reachable from any local
> +	branch head.  This option tells git to fetch all tags (and their
> +	associated objects).

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

diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 60ac8d2..c6c7236 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -19,20 +19,19 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Fetches named heads or tags from one or more other repositories,
-along with the objects necessary to complete them.
+Fetches branches and tags (collectively known as 'refs') from one or more
+other repositories, along with the objects necessary to complete them.
+Which refs are fetched are determined by the <refspec> arguments, if
+given. Otherwise the default <refspec> configured for the <repository>
+are used (see "REMOTES" section below for how <refspec> works).
 
-The ref names and their object names of fetched refs are stored
-in `.git/FETCH_HEAD`.  This information is left for a later merge
-operation done by 'git merge'.
+The ref names and their object names are also stored in `.git/FETCH_HEAD`.
+This information is used by 'git pull' that invokes this command.
 
 When <refspec> stores the fetched result in remote-tracking branches,
-the tags that point at these branches are automatically
-followed.  This is done by first fetching from the remote using
-the given <refspec>s, and if the repository has objects that are
-pointed by remote tags that it does not yet have, then fetch
-those missing tags.  If the other end has tags that point at
-branches you are not interested in, you will not get them.
+the tags that point at commits on these branches are also fetched. Tags
+at the remote that point at commits that are not on these remote-tracking 
+branches are not fetched by this mechanism (use `--tags` option to fetch them).
 
 'git fetch' can fetch from either a single named repository,
 or from several repositories at once if <group> is given and

Re: [PATCH v3] Docs: Clarify the --tags option of `git fetch'

[Michael Witten]

On Thu, Sep 22, 2011 at 17:10, Junio C Hamano <gitster@pobox.com> wrote:
> Michael Witten <mfwitten@gmail.com> writes:
>
>> 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
>
> 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.
>
>>  Documentation/fetch-options.txt |   31 +++++++++++++++++++++++--------
>>  1 files changed, 23 insertions(+), 8 deletions(-)
>>
>> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
>> index 39d326a..4cc5a80 100644
>> --- a/Documentation/fetch-options.txt
>> +++ b/Documentation/fetch-options.txt
>> @@ -56,14 +56,29 @@ endif::git-pull[]
>>  ifndef::git-pull[]
>>  -t::
>>  --tags::
>> -     Most of the tags are fetched automatically as branch
>> -     heads are downloaded, but tags that do not point at
>> -     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].
>> +     Most of a remote's tags are fetched automatically as branches are
>> +     downloaded. However, git does not automatically fetch any tag that,
>> +     when 'git fetch' completes, would not be reachable from any local
>> +     branch head.  This option tells git to fetch all tags (and their
>> +     associated objects).
>
> 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(-)
>
> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
> index 60ac8d2..c6c7236 100644
> --- a/Documentation/git-fetch.txt
> +++ b/Documentation/git-fetch.txt
> @@ -19,20 +19,19 @@ SYNOPSIS
>
>  DESCRIPTION
>  -----------
> -Fetches named heads or tags from one or more other repositories,
> -along with the objects necessary to complete them.
> +Fetches branches and tags (collectively known as 'refs') from one or more
> +other repositories, along with the objects necessary to complete them.
> +Which refs are fetched are determined by the <refspec> arguments, if
> +given. Otherwise the default <refspec> configured for the <repository>
> +are used (see "REMOTES" section below for how <refspec> works).
>
> -The ref names and their object names of fetched refs are stored
> -in `.git/FETCH_HEAD`.  This information is left for a later merge
> -operation done by 'git merge'.
> +The ref names and their object names are also stored in `.git/FETCH_HEAD`.
> +This information is used by 'git pull' that invokes this command.
>
>  When <refspec> stores the fetched result in remote-tracking branches,
> -the tags that point at these branches are automatically
> -followed.  This is done by first fetching from the remote using
> -the given <refspec>s, and if the repository has objects that are
> -pointed by remote tags that it does not yet have, then fetch
> -those missing tags.  If the other end has tags that point at
> -branches you are not interested in, you will not get them.
> +the tags that point at commits on these branches are also fetched. Tags
> +at the remote that point at commits that are not on these remote-tracking
> +branches are not fetched by this mechanism (use `--tags` option to fetch them).
>
>  'git fetch' can fetch from either a single named repository,
>  or from several repositories at once if <group> is given and
>

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.

Re: [PATCH v3] Docs: Clarify the --tags option of `git fetch'

[Michael Witten]

On Thu, Sep 22, 2011 at 17:35, Michael Witten <mfwitten@gmail.com> wrote:
> On Thu, Sep 22, 2011 at 17:10, Junio C Hamano <gitster@pobox.com> wrote:
>> Michael Witten <mfwitten@gmail.com> writes:
>>
>>> 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
>>
>> 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.
>>
>>>  Documentation/fetch-options.txt |   31 +++++++++++++++++++++++--------
>>>  1 files changed, 23 insertions(+), 8 deletions(-)
>>>
>>> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
>>> index 39d326a..4cc5a80 100644
>>> --- a/Documentation/fetch-options.txt
>>> +++ b/Documentation/fetch-options.txt
>>> @@ -56,14 +56,29 @@ endif::git-pull[]
>>>  ifndef::git-pull[]
>>>  -t::
>>>  --tags::
>>> -     Most of the tags are fetched automatically as branch
>>> -     heads are downloaded, but tags that do not point at
>>> -     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].
>>> +     Most of a remote's tags are fetched automatically as branches are
>>> +     downloaded. However, git does not automatically fetch any tag that,
>>> +     when 'git fetch' completes, would not be reachable from any local
>>> +     branch head.  This option tells git to fetch all tags (and their
>>> +     associated objects).
>>
>> 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(-)
>>
>> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
>> index 60ac8d2..c6c7236 100644
>> --- a/Documentation/git-fetch.txt
>> +++ b/Documentation/git-fetch.txt
>> @@ -19,20 +19,19 @@ SYNOPSIS
>>
>>  DESCRIPTION
>>  -----------
>> -Fetches named heads or tags from one or more other repositories,
>> -along with the objects necessary to complete them.
>> +Fetches branches and tags (collectively known as 'refs') from one or more
>> +other repositories, along with the objects necessary to complete them.
>> +Which refs are fetched are determined by the <refspec> arguments, if
>> +given. Otherwise the default <refspec> configured for the <repository>
>> +are used (see "REMOTES" section below for how <refspec> works).
>>
>> -The ref names and their object names of fetched refs are stored
>> -in `.git/FETCH_HEAD`.  This information is left for a later merge
>> -operation done by 'git merge'.
>> +The ref names and their object names are also stored in `.git/FETCH_HEAD`.
>> +This information is used by 'git pull' that invokes this command.
>>
>>  When <refspec> stores the fetched result in remote-tracking branches,
>> -the tags that point at these branches are automatically
>> -followed.  This is done by first fetching from the remote using
>> -the given <refspec>s, and if the repository has objects that are
>> -pointed by remote tags that it does not yet have, then fetch
>> -those missing tags.  If the other end has tags that point at
>> -branches you are not interested in, you will not get them.
>> +the tags that point at commits on these branches are also fetched. Tags
>> +at the remote that point at commits that are not on these remote-tracking
>> +branches are not fetched by this mechanism (use `--tags` option to fetch them).
>>
>>  'git fetch' can fetch from either a single named repository,
>>  or from several repositories at once if <group> is given and
>>
>
> 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.

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*].

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

[Junio C Hamano]

Michael Witten <mfwitten@gmail.com> writes:

>   That is,
>
>     git fetch origin frotz --tags
>
>   is equivalent to:
>
>     git fetch origin frotz 'refs/tags/*:refs/tags/*'

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.

[PATCH v2] Docs: Clarify the --tags option of `git fetch'

[Michael Witten]

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

> Michael Witten <mfwitten@gmail.com> writes:
>
>>   That is,
>>
>>     git fetch origin frotz --tags
>>
>>   is equivalent to:
>>
>>     git fetch origin frotz 'refs/tags/*:refs/tags/*'
>
> 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.

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

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 39d326a..da594bd 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 shorthand 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 --tags frotz
++
+are equivalent to:
++
+	git fetch origin 'refs/tags/*:refs/tags/*'
+	git fetch origin 'refs/tags/*:refs/tags/*' frotz
++
+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

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

[Daniel Johnson]

On Wednesday, September 21, 2011 04:52:56 PM Anatol Pomozov wrote:
> @@ -63,7 +63,8 @@ ifndef::git-pull[]
>  	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].
> +	linkgit:git-config[1]. Note that if this option is specified
> +	then only tags are fetched, refs under refs/heads/* stay unchanged.

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

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

[Peter Shenkin]

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.

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

[Jakub Narebski]

Peter Shenkin <shenkin@gmail.com> writes:

[...]
> 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".

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
-- 
Jakub Narębski

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

[Michael Witten]

On Fri, Sep 30, 2011 at 02:51, Peter Shenkin <shenkin@gmail.com> wrote:
> 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."

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

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

[Peter Shenkin]

Michael Witten <mfwitten <at> gmail.com> writes:
> 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.

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.

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

[Michael Witten]

On Sat, Oct 1, 2011 at 05:40, Peter Shenkin <shenkin@gmail.com> wrote:
> Michael Witten <mfwitten <at> gmail.com> writes:
>> 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.
>
> 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.

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.

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

[Peter Shenkin]

Michael Witten <mfwitten <at> gmail.com> writes:
> However, my point was this:
> 
>   You can still tell git to fetch anything else you want in addition.

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.

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

[Michael Witten]

On Sat, Oct 1, 2011 at 17:16, Peter Shenkin <shenkin@gmail.com> wrote:
> Michael Witten <mfwitten <at> gmail.com> writes:
>> However, my point was this:
>>
>>   You can still tell git to fetch anything else you want in addition.
>
> 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?

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?

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

[Peter Shenkin]

Michael Witten <mfwitten <at> gmail.com> writes:
>   git fetch --tags origin '+refs/heads/*:refs/remotes/origin/*'

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

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

[Michael Witten]

On Sat, Oct 1, 2011 at 20:22, Peter Shenkin <shenkin@gmail.com> wrote:
>
> 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.

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.

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

[Peter Shenkin]

Michael Witten <mfwitten <at> gmail.com> writes:
 
> On Sat, Oct 1, 2011 at 20:22, Peter Shenkin <shenkin <at> gmail.com> wrote:
>     [--tags] is merely a shorthand for writing the refspec
>     `refs/tags/\*:refs/tags/\*'; that is,

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.

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

[Peter Shenkin]

Peter Shenkin <shenkin <at> gmail.com> writes:
> 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.

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.

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

[Junio C Hamano]

Peter Shenkin <shenkin@gmail.com> writes:

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

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?

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

[Peter Shenkin]

Junio C Hamano <gitster <at> pobox.com> writes:
> I think in general our documentation aims to spell out _all_ that happens,
...
 
> I am wondering if there is a systemic failure...
> ,,,If so are there things that we could
> do better without going through individual description?


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.