Koosha Khajehmoogahi <koosha@xxxxxxxxx> writes:
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index f620ee4..0bb2390 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -96,12 +96,24 @@ if it is part of the log message.
> --remove-empty::
> Stop when a given path disappears from the tree.
>
> +--merges={show|hide|only}::
> ++
> +--
> +`show`: show both merge and non-merge commits
> +
> +`hide`: only show non-merge commits; same as `--max-parents=1`
> +
> +`only`: only show merge commits; same as `--min-parents=2`
> +
> +If `--merges=` is not specified, default value is `show`.
> +--
> ++
> +
I am not sure if the "default value is `show`" is something we would
even want to mention like this. It does not tell the whole story
and may even confuse the users, who did
git log --merge
git log --max-parent=...
but did not say any "--merges=<something>".
I think the importat point we want to teach users is that this is an
option to use when you want to limit what is output (and by default,
we show all but nothing else in the manpage says we hide things,
so...). And it would be beneficial to highlight that 'show' is only
there to defeat an unusual log.merges setting in users' config.
Also the formatting of this part looks rather unusual. I would have
expected that these three items to be listed as a true AsciiDoc
enumeration, not three hand-crafted enumration-looking separate
paragraphs.
Taking both points together, we may want to do something more like
this, perhaps?
--merges={show|hide|only}::
Limit the output by type of commits.
`hide`;;
Hide merge commits from the output.
`only`;;
Hide non-merge commits from the output (i.e showing
only merge commits).
`show`;;
Do not hide either merge or non-merge commits. This
is primarily useful when the user has non-standard
setting of `log.merges` configuration variable that
needs to be overriden from the command line.
Thanks.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html