Subject: Re: [PATCH v3 1/6] git-fetch.txt: document fetch output

From: Marc Branchaud <[email-masked]>
Date: Mon, 6 Jun 2016 10:24:28 -0400

On 2016-06-04 11:11 PM, Nguyễn Thái Ngọc Duy wrote:
> This documents the ref update status of fetch. The structure of this
> output is defined in [1]. The ouput content is refined a bit in [2]
> [3] [4].
>
> This patch is a copy from git-push.txt, modified a bit because the
> flag '-' means different things in push (delete) and fetch (tag
> update).
>
> PS. For code archaeologists, the discussion mentioned in [1] is
> probably [5].
>
> [1] 165f390 (git-fetch: more terse fetch output - 2007-11-03)
> [2] 6315472 (fetch: report local storage errors ... - 2008-06-26)
> [3] f360d84 (builtin-fetch: add --prune option - 2009-11-10)
> [4] 0997ada (fetch: describe new refs based on where... - 2012-04-16)
> [5] http://thread.gmane.org/gmane.comp.version-control.git/61657
>
> Signed-off-by: Nguyễn Thái Ngọc Duy <[email-masked]>
> ---
>   Documentation/git-fetch.txt | 46 +++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 46 insertions(+)
>
> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
> index efe56e0..a0d0539 100644
> --- a/Documentation/git-fetch.txt
> +++ b/Documentation/git-fetch.txt
> @@ -99,6 +99,52 @@ The latter use of the `remote.<repository>.fetch` values can be
>   overridden by giving the `--refmap=<refspec>` parameter(s) on the
>   command line.
>
> +OUTPUT
> +------
> +
> +The output of "git fetch" depends on the transport method used; this
> +section describes the output when fetch over the Git protocol (either

s/fetch/fetching/

> +locally or via ssh).
> +
> +The status of the fetch is output in tabular form, with each line
> +representing the status of a single ref. Each line is of the form:
> +
> +-------------------------------
> + <flag> <summary> <from> -> <to> (<reason>)
> +-------------------------------

(<reason>) should really just be <reason>, as the () are part of the 
reason string.

> +
> +The status of up-to-date refs is shown only if --verbose option is

s/if/if the/

Also, thanks for putting so much effort into this!

I think having a fetch.output configuration setting is perfectly fine. 
This sort of thing is really a matter of personal taste, so having 
choices is good.

		M.