git-fetch.txt: document fetch output

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 <pclouds@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Nguyễn Thái Ngọc Duy committed Jun 26, 2016 at 07:58 UTC a52397cce6c1049c3c9507d734243ee125d11f0c
1 file changed +46
Documentation/git-fetch.txt
+46
@@ -99,6 +99,52 @@ The latter use of the `remote.<repository>.fetch` values can be
99 overridden by giving the `--refmap=<refspec>` parameter(s) on the
100 command line.
101
102 +OUTPUT
103 +------
104 +
105 +The output of "git fetch" depends on the transport method used; this
106 +section describes the output when fetching over the Git protocol
107 +(either locally or via ssh) and Smart HTTP protocol.
108 +
109 +The status of the fetch is output in tabular form, with each line
110 +representing the status of a single ref. Each line is of the form:
111 +
112 +-------------------------------
113 + <flag> <summary> <from> -> <to> [<reason>]
114 +-------------------------------
115 +
116 +The status of up-to-date refs is shown only if the --verbose option is
117 +used.
118 +
119 +flag::
120 + A single character indicating the status of the ref:
121 +(space);; for a successfully fetched fast-forward;
122 +`+`;; for a successful forced update;
123 +`x`;; for a successfully pruned ref;
124 +`-`;; for a successful tag update;
125 +`*`;; for a successfully fetched new ref;
126 +`!`;; for a ref that was rejected or failed to update; and
127 +`=`;; for a ref that was up to date and did not need fetching.
128 +
129 +summary::
130 + For a successfully fetched ref, the summary shows the old and new
131 + values of the ref in a form suitable for using as an argument to
132 + `git log` (this is `<old>..<new>` in most cases, and
133 + `<old>...<new>` for forced non-fast-forward updates).
134 +
135 +from::
136 + The name of the remote ref being fetched from, minus its
137 + `refs/<type>/` prefix. In the case of deletion, the name of
138 + the remote ref is "(none)".
139 +
140 +to::
141 + The name of the local ref being updated, minus its
142 + `refs/<type>/` prefix.
143 +
144 +reason::
145 + A human-readable explanation. In the case of successfully fetched
146 + refs, no explanation is needed. For a failed ref, the reason for
147 + failure is described.
148
149 EXAMPLES
150 --------