public inbox for git@vger.kernel.org 
 help / color / mirror / Atom feed

From: Junio C Hamano <gitster@pobox•com>
To: Koosha Khajehmoogahi <koosha@posteo•de>
Cc: git@vger•kernel.org, sunshine@sunshineco•com
Subject: Re: [PATCH v2 3/5] Documentation: add git-log --merges= option and log.merges config. var
Date: Sun, 05 Apr 2015 14:41:07 -0700	[thread overview]
Message-ID: <xmqq8ue6cky4.fsf@gitster.dls.corp.google.com> (raw)
In-Reply-To: <1428110521-31028-3-git-send-email-koosha@posteo.de> (Koosha Khajehmoogahi's message of "Sat, 4 Apr 2015 03:21:59 +0200")

Koosha Khajehmoogahi <koosha@posteo•de> 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.

next prev parent reply	other threads:[~2015-04-05 21:42 UTC|newest]

Thread overview: 14+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <266077>
2015-04-04  1:21 ` [PATCH v2 1/5] revision: add --merges={show|only|hide} option Koosha Khajehmoogahi
2015-04-04  1:21   ` [PATCH v2 2/5] log: honor log.merges= option Koosha Khajehmoogahi
2015-04-04 20:00     ` Junio C Hamano
2015-04-07 22:15       ` Koosha Khajehmoogahi
2015-04-08  2:28         ` Junio C Hamano
2015-04-08 10:42           ` Koosha Khajehmoogahi
2015-04-13  4:56             ` Junio C Hamano
2015-04-07  5:18     ` Eric Sunshine
2015-04-04  1:21   ` [PATCH v2 3/5] Documentation: add git-log --merges= option and log.merges config. var Koosha Khajehmoogahi
2015-04-05 21:41     ` Junio C Hamano [this message]
2015-04-04  1:22   ` [PATCH v2 4/5] t4202-log: add tests for --merges= Koosha Khajehmoogahi
2015-04-07  7:32     ` Eric Sunshine
2015-04-04  1:22   ` [PATCH v2 5/5] bash-completion: add support for git-log --merges= and log.merges Koosha Khajehmoogahi
2015-04-07  5:16   ` [PATCH v2 1/5] revision: add --merges={show|only|hide} option Eric Sunshine

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqq8ue6cky4.fsf@gitster.dls.corp.google.com \
    --to=gitster@pobox$(echo .)com \
    --cc=git@vger$(echo .)kernel.org \
    --cc=koosha@posteo$(echo .)de \
    --cc=sunshine@sunshineco$(echo .)com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox