Re: [PATCH] Documentation/git-rerere: document 'remaining' command

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 6, 2012, 19:24 UTC
Message-ID: <7vwr6xsfbn.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1331036512-7626-1-git-send-email-vfr@lyx.org>

Vincent van Ravesteijn <vfr@lyx.org> writes:

Show 32 quoted lines

> From: Vincent van Ravesteijn <vfr@lyx.org>
>
> This adds the 'remaining' command to the documentation of
> 'git rerere'. This command was added in ac49f5ca (Feb 16 2011;
> Martin von Zweigbergk <martin.von.zweigbergk@gmail.com>) but
> it was never documented.
>
> Signed-off-by: Vincent van Ravesteijn <vfr@lyx.org>
> ---
>  Documentation/git-rerere.txt |   10 +++++++++-
>  1 files changed, 9 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt
> index a6253ba..b75d34b 100644
> --- a/Documentation/git-rerere.txt
> +++ b/Documentation/git-rerere.txt
> @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges
>  SYNOPSIS
>  --------
>  [verse]
> -'git rerere' ['clear'|'forget' <pathspec>|'diff'|'status'|'gc']
> +'git rerere' ['clear'|'forget' <pathspec>|'diff'|'remaining'|'status'|'gc']
>  
>  DESCRIPTION
>  -----------
> @@ -53,6 +53,14 @@ useful for tracking what has changed while the user is resolving
>  conflicts.  Additional arguments are passed directly to the system
>  'diff' command installed in PATH.
>  
> +'remaining'::
> +
> +Like 'diff', but this only prints the unresolved filenames. This

What aspect of 'rerere remaining' is like 'rerere diff'?

In general, people should think twice after writing "Like X, but Y" and try to come up with a more clear description that does not have to force the user to read about X and then selectively forget what he just read and replace it with Y. This is especially true when the Y part is significantly different from what X does.

Another phrase to watch out for when writing documentation is "X. In other words, Y." People do this after writing X and finding it hard to understand and necessary to explain in easier terms. Reading it again without "X. In other words, " often yields a better description.

	'remaining'::

        Print paths with conflicts that are not resolved.

Should be sufficient, I think.

In fact, wouldn't this be more or less equivalent to "ls-files -u" without anything other than name part?