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

Jonathan Nieder [off-list ref] writes:

Štěpán Němec wrote:

quoted

Jonathan Nieder [off-list ref] writes:

quoted

quoted

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 <redacted>
Mentored-by: Jonathan Nieder [off-list ref]
---
 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
--

Štěpán Němec wrote:

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

Looks good, thanks.