Re: [PATCH 2/6] Fix odd markup in --diff-filter documentation

From: Štěpán Němec <stepan.nemec@gmail.com>
Date: Oct 8, 2010, 18:40 UTC
Message-ID: <877hhsttnj.fsf@gmail.com>
In-Reply-To: <20101008180327.GA13910@burratino>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 18 quoted lines

> Štěpán Němec wrote:
>> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>>> Strictly speaking, --diff-filter= (with empty argument) is allowed, too,
>>> but I don't know if it's worth fitting that in.
>>
>> If it provides some kind of useful behaviour (I don't know and you
>> didn't clarify that either), then it should be documented I guess?
>
> Just a special case of the usual behavior: it selects the empty set of
> files.  Doesn't sound useful to me, but maybe someone writing a
> front-end would want to be reassured that --diff-filter will still
> work if the user unchecks all the boxes.
>
> Of course, one can also just try it...
>
> If you can find a way to format it nicely (using brackets?), then I
> think it should be part of the documented syntax, yes.

Well, in that case simply replacing parens with brackets would do, i.e.

--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]

instead of

--diff-filter=((A|C|D|M|R|T|U|X|B)...[*])

That would mean the following instead of the original [2/6]:

--- 8< ---
Subject: Fix odd markup in --diff-filter documentation

Instead of using the regex-like bracket expression, use grouping to make it more consistent with other similar places. The brackets now have the same meaning as in other documentation (i.e., the argument is optional).

Signed-off-by: Štěpán Němec <stepnem@gmail.com>
Mentored-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/diff-options.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index cbf3c92..e954af0 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -248,13 +248,13 @@ endif::git-log[]
        If `n` is specified, it has the same meaning as for `-M<n>`.

 ifndef::git-format-patch[]
---diff-filter=[ACDMRTUXB*]::
+--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]::
        Select only files that are Added (`A`), Copied (`C`),
        Deleted (`D`), Modified (`M`), Renamed (`R`), have their
        type (i.e. regular file, symlink, submodule, ...) changed (`T`),
        are Unmerged (`U`), are
        Unknown (`X`), or have had their pairing Broken (`B`).
-       Any combination of the filter characters may be used.
+       Any combination of the filter characters (including none) can be used.
        When `*` (All-or-none) is added to the combination, all
        paths are selected if there is any file that matches
        other criteria in the comparison; if there is no file
--