Re: [PATCH v2 3/5] Documentation: add git-log --merges= option and log.merges config. var

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 5, 2015, 21:41 UTC
Message-ID: <xmqq8ue6cky4.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1428110521-31028-3-git-send-email-koosha@posteo.de>

Koosha Khajehmoogahi <koosha@posteo.de> writes:

Show 21 quoted lines

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