Re: [PATCHv2] git-replace.txt: Clarify list mode

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 26, 2011, 16:30 UTC
Message-ID: <7v4o14f844.fsf@alter.siamese.dyndns.org>
In-Reply-To: <0a88518db0b0db8f1a4a4deeebd6dffc2d603e74.1314345131.git.git@drmicha.warpmail.net>

Michael J Gruber <git@drmicha.warpmail.net> writes:

Show 21 quoted lines

> Clarify that in list mode, "git replace" outputs the shortened ref
> names, not their values.
>
> Also, point to the difficult to find git show-ref $(git replace -l).
>
> Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
> ---
>  Documentation/git-replace.txt |    8 ++++++++
>  1 files changed, 8 insertions(+), 0 deletions(-)
>
> diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
> index 17df525..cd00837 100644
> --- a/Documentation/git-replace.txt
> +++ b/Documentation/git-replace.txt
> @@ -61,6 +61,13 @@ OPTIONS
>  	all if no pattern is given).
>  	Typing "git replace" without arguments, also lists all replace
>  	refs.
> ++
> +Note that this lists the names of the replace refs, not their values
> +(not their replacements). You can get the latter like this, e.g.:

Hmm, the update is _not wrong_ per-se, but...

I highly doubt we would want to try to cover confusions that may come from any and all different mis-/pre-conceptions people may have by making the description _longer_.

Which part of the wording in the existing description made you think that the command might list both names and their contents? We should identify that misleading description (if there is) and fix that, instead of tacking clarifying clauses at the end.

Given these statements:

	"git replace" lists all replace refs.
        "ls" lists paths in the directory.

I would say a natural reading of them is that they list "replace refs" and "paths", not "replace refs and their contents" and "paths and their contents".

By the way, one thing I forgot to say was that I do not think the variant of the output you wanted to have is necessarily a bad thing (it is bad to change the existing output to that variant, breaking other people). Perhaps it can become "-v(erbose)" output?