From: Marc Branchaud <marcnarc@xiplink.com>
Date: Fri, 03 Jun 2016 14:33:55 GMT
Subject: Re: [PATCH v2 1/3] git-fetch.txt: document fetch output
Message-ID: <57519553.10106@xiplink.com>
In-Reply-To: <20160603110843.15434-2-pclouds@gmail.com>

On 2016-06-03 07:08 AM, 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]

s/The ouput/The output/

> [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). We probably should unify the documents at some point in
> future.
>
> 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
> ---
>   Documentation/git-fetch.txt | 46 +++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 46 insertions(+)
>
> diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
> index efe56e0..18e733c 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

What a mysterious statement!  Does this tabular format actually change 
when fetching over HTTP?  Maybe it's worth documenting the differences?

> +section describes the output when pushing over the Git protocol

s/pushing/fetching/

> +(either locally or via ssh).
> +
> +The status of the push is output in tabular form, with each line

s/push/fetch/

> +representing the status of a single ref. Each line is of the form:
> +
> +-------------------------------
> + <flag> <summary> <from> -> <to> (<reason>)
> +-------------------------------
> +
> +The status of up-to-date refs is shown only if --verbose option is
> +used.
> +
> +flag::
> +	A single character indicating the status of the ref:
> +(space);; for a successfully fetched fast-forward;
> +`+`;; for a successful forced update;
> +`x`;; for a successfully deleted ref;

I did a double-take here, until I remembered --prune.  Maybe add "(when 
using the --prune option)"?

		M.