Re: [PATCH 01/10] Documentation/git-pull.txt: mention --quiet and --verbose for fetching

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 18, 2010, 21:11 UTC
Message-ID: <7vhbpe5jvo.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1266496631-3980-2-git-send-email-rctay89@gmail.com>

Tay Ray Chuan <rctay89@gmail.com> writes:

Show 13 quoted lines

> This reverts 90e4311 (git-pull: do not mention --quiet and --verbose
> twice, Mon Sep 7 2009).
>
> Then, the subtitles "Options related to merging" and "Options related to
> fetching" weren't present, and the options for git-merge and git-fetch
> options were in a monolithic block.
>
> After 3f7a9b5 (Documentation/git-pull.txt: Add subtitles above included
> option files, Thu Oct 22 2009), it is ok to repeat options in the
> same document, since they are distinguished between those for git-merge
> and git-fetch.
>
> Signed-off-by: Tay Ray Chuan <rctay89@gmail.com>

As the result of the change history, currently we mention -q/-v as if it only applies to the invocation of merge, giving an incorrect impression that they won't affect the invocation of fetch.

While I agree that is a valid issue to address, I am not sure if repeating these in two sections is a good solution. A reader will start scanning the OPTIONS section, finds -q (or -v) and notices it is listed in the "related to merging" subsection, and would stop there. This change would not help such a reader.

It may make more sense to list the options that affects both fetch and merge at the beginning of the OPTIONS section before the merge/fetch subsections. IOW, instead of removing ifndef::git-pull[] like your patch did, it would add ifndef::git-pull[] in the list of options on the merge side, and add pull specific description (e.g. "this is passed to both underlying fetch to squelch progress output of transfer, and underlying merge to squelch the output during the merging") in git-pull.txt.

Show 22 quoted lines

>  Documentation/fetch-options.txt |    2 --
>  1 files changed, 0 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
> index fe716b2..83606f4 100644
> --- a/Documentation/fetch-options.txt
> +++ b/Documentation/fetch-options.txt
> @@ -74,7 +74,6 @@ endif::git-pull[]
>  	the command to specify non-default path for the command
>  	run on the other end.
>  
> -ifndef::git-pull[]
>  -q::
>  --quiet::
>  	Pass --quiet to git-fetch-pack and silence any other internally
> @@ -83,4 +82,3 @@ ifndef::git-pull[]
>  -v::
>  --verbose::
>  	Be verbose.
> -endif::git-pull[]
> -- 
> 1.7.0.27.g5d71b