From: Karthik Nayak <karthik.188@gmail.com>
Date: Fri, 18 Sep 2015 15:38:42 GMT
Subject: Re: [PATCH v17 14/14] tag.c: implement '--merged' and '--no-merged' options
Message-ID: <CAOLa=ZQbrE9vuES=DwO0wArdt8F_LUdFdzxggEkHFz4BB=O1OQ@mail.gmail.com>
In-Reply-To: <vpqr3lviw38.fsf@anie.imag.fr>

On Fri, Sep 18, 2015 at 9:00 PM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Karthik Nayak <karthik.188@gmail.com> writes:
>
>> On Fri, Sep 18, 2015 at 8:49 PM, Matthieu Moy
>> <Matthieu.Moy@grenoble-inp.fr> wrote:
>>> Karthik Nayak <karthik.188@gmail.com> writes:
>>>
>>>> Not sure this is much of a problem with regards to "--[no-]merged"
>>>> I mean isn't the square brackets self-explanatory?
>>>
>>> Well, usually --no-foo means "cancel the effect of --foo", ie. "git
>>> command --foo --no-foo" is equivalent to "git command".
>>>
>>> Here, --no-merged=some-ref does not _cancel_ the effect but introduce a
>>> new behavior that was not the default. So it may make sense to explain
>>> this more clearly.
>>
>> maybe we should s/no/not ? makes not sense to me
>
> It's too late to rename the option without a transition plan (people's
> finger and scripts use --no-merged already).
>
> But that would be a good idea to introduce --not-merged as a synonym to
> --no-merged, and deprecate --no-merged (it can remain a deprecated alias
> forever if needed, but we should promote --not-merged in the docs).
>

Either ways, I'll add it to my personal list of TODO.
Also having a look around, even the "--contains" option is
similarly documented:

--contains [<commit>]::
    Only list tags which contain the specified commit (HEAD if not
    specified).

About the issue at hand, we should probably squash this in

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 3803bf7..19ef640 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 'git tag' -d <tagname>...
 'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>]
        [--column[=<options>] | --no-column] [--create-reflog] [--sort=<key>]
-       [--format=<format>] [--[no-]merged [<commit>]] [<pattern>...]
+       [--format=<format>] [(--merged | --no-merged) [<commit>]] [<pattern>...]
 'git tag' -v <tagname>...

 DESCRIPTION
@@ -165,10 +165,15 @@ This option is only applicable when listing tags
without annotation lines.
        that of linkgit:git-for-each-ref[1].  When unspecified,
        defaults to `%(refname:short)`.

---[no-]merged [<commit>]::
-       Only list tags whose tips are reachable, or not reachable
-       if '--no-merged' is used, from the specified commit ('HEAD'
-       if not specified).
+--merged [<commit>]::
+       Only list tags whose tips are reachable from the specified
+       commit (The `commit` may be omitted if this is the final
+       argument, in which case it defaults to `HEAD`).
+
+--no-merged [<commit>]::
+       Only list tags whose tips are not reachable from the specified
+       commit (The `commit` may be omitted if this is the final
+       argument, in which case it defaults to `HEAD`).

 CONFIGURATION
 -------------

-- 
Regards,
Karthik Nayak