Merge branch 'tb/complete-describe'
[git/git.git] / Documentation / git-for-each-ref.txt
1 git-for-each-ref(1)
2 ===================
5 ----
6 git-for-each-ref - Output information on each ref
9 --------
10 [verse]
11 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
12 [(--sort=<key>)...] [--format=<format>] [<pattern>...]
13 [--points-at=<object>]
14 (--merged[=<object>] | --no-merged[=<object>])
15 [--contains[=<object>]] [--no-contains[=<object>]]
18 -----------
20 Iterate over all refs that match `<pattern>` and show them
21 according to the given `<format>`, after sorting them according
22 to the given set of `<key>`. If `<count>` is given, stop after
23 showing that many refs. The interpolated values in `<format>`
24 can optionally be quoted as string literals in the specified
25 host language allowing their direct evaluation in that language.
28 -------
29 <pattern>...::
30 If one or more patterns are given, only refs are shown that
31 match against at least one pattern, either using fnmatch(3) or
32 literally, in the latter case matching completely or from the
33 beginning up to a slash.
35 --count=<count>::
36 By default the command shows all refs that match
37 `<pattern>`. This option makes it stop after showing
38 that many refs.
40 --sort=<key>::
41 A field name to sort on. Prefix `-` to sort in
42 descending order of the value. When unspecified,
43 `refname` is used. You may use the --sort=<key> option
44 multiple times, in which case the last key becomes the primary
45 key.
47 --format=<format>::
48 A string that interpolates `%(fieldname)` from a ref being shown
49 and the object it points at. If `fieldname`
50 is prefixed with an asterisk (`*`) and the ref points
51 at a tag object, use the value for the field in the object
52 which the tag object refers to (instead of the field in the tag object).
53 When unspecified, `<format>` defaults to
54 `%(objectname) SPC %(objecttype) TAB %(refname)`.
55 It also interpolates `%%` to `%`, and `%xx` where `xx`
56 are hex digits interpolates to character with hex code
57 `xx`; for example `%00` interpolates to `\0` (NUL),
58 `%09` to `\t` (TAB) and `%0a` to `\n` (LF).
60 --color[=<when>]:
61 Respect any colors specified in the `--format` option. The
62 `<when>` field must be one of `always`, `never`, or `auto` (if
63 `<when>` is absent, behave as if `always` was given).
65 --shell::
66 --perl::
67 --python::
68 --tcl::
69 If given, strings that substitute `%(fieldname)`
70 placeholders are quoted as string literals suitable for
71 the specified host language. This is meant to produce
72 a scriptlet that can directly be `eval`ed.
74 --points-at=<object>::
75 Only list refs which points at the given object.
77 --merged[=<object>]::
78 Only list refs whose tips are reachable from the
79 specified commit (HEAD if not specified),
80 incompatible with `--no-merged`.
82 --no-merged[=<object>]::
83 Only list refs whose tips are not reachable from the
84 specified commit (HEAD if not specified),
85 incompatible with `--merged`.
87 --contains[=<object>]::
88 Only list refs which contain the specified commit (HEAD if not
89 specified).
91 --no-contains[=<object>]::
92 Only list refs which don't contain the specified commit (HEAD
93 if not specified).
95 --ignore-case::
96 Sorting and filtering refs are case insensitive.
99 -----------
101 Various values from structured fields in referenced objects can
102 be used to interpolate into the resulting output, or as sort
103 keys.
105 For all objects, the following names can be used:
107 refname::
108 The name of the ref (the part after $GIT_DIR/).
109 For a non-ambiguous short name of the ref append `:short`.
110 The option core.warnAmbiguousRefs is used to select the strict
111 abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>`
112 slash-separated path components from the front (back) of the refname
113 (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and
114 `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).
115 If `<N>` is a negative number, strip as many path components as
116 necessary from the specified end to leave `-<N>` path components
117 (e.g. `%(refname:lstrip=-2)` turns
118 `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
119 turns `refs/tags/foo` into `refs`). When the ref does not have
120 enough components, the result becomes an empty string if
121 stripping with positive <N>, or it becomes the full refname if
122 stripping with negative <N>. Neither is an error.
123 +
124 `strip` can be used as a synomym to `lstrip`.
126 objecttype::
127 The type of the object (`blob`, `tree`, `commit`, `tag`).
129 objectsize::
130 The size of the object (the same as 'git cat-file -s' reports).
132 objectname::
133 The object name (aka SHA-1).
134 For a non-ambiguous abbreviation of the object name append `:short`.
135 For an abbreviation of the object name with desired length append
136 `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The
137 length may be exceeded to ensure unique object names.
139 upstream::
140 The name of a local ref which can be considered ``upstream''
141 from the displayed ref. Respects `:short`, `:lstrip` and
142 `:rstrip` in the same way as `refname` above. Additionally
143 respects `:track` to show "[ahead N, behind M]" and
144 `:trackshort` to show the terse version: ">" (ahead), "<"
145 (behind), "<>" (ahead and behind), or "=" (in sync). `:track`
146 also prints "[gone]" whenever unknown upstream ref is
147 encountered. Append `:track,nobracket` to show tracking
148 information without brackets (i.e "ahead N, behind M"). Has
149 no effect if the ref does not have tracking information
150 associated with it. All the options apart from `nobracket`
151 are mutually exclusive, but if used together the last option
152 is selected.
154 push::
155 The name of a local ref which represents the `@{push}`
156 location for the displayed ref. Respects `:short`, `:lstrip`,
157 `:rstrip`, `:track`, and `:trackshort` options as `upstream`
158 does. Produces an empty string if no `@{push}` ref is
159 configured.
161 HEAD::
162 '*' if HEAD matches current ref (the checked out branch), ' '
163 otherwise.
165 color::
166 Change output color. Followed by `:<colorname>`, where color
167 names are described under Values in the "CONFIGURATION FILE"
168 section of linkgit:git-config[1]. For example,
169 `%(color:bold red)`.
171 align::
172 Left-, middle-, or right-align the content between
173 %(align:...) and %(end). The "align:" is followed by
174 `width=<width>` and `position=<position>` in any order
175 separated by a comma, where the `<position>` is either left,
176 right or middle, default being left and `<width>` is the total
177 length of the content with alignment. For brevity, the
178 "width=" and/or "position=" prefixes may be omitted, and bare
179 <width> and <position> used instead. For instance,
180 `%(align:<width>,<position>)`. If the contents length is more
181 than the width then no alignment is performed. If used with
182 `--quote` everything in between %(align:...) and %(end) is
183 quoted, but if nested then only the topmost level performs
184 quoting.
186 if::
187 Used as %(if)...%(then)...%(end) or
188 %(if)...%(then)...%(else)...%(end). If there is an atom with
189 value or string literal after the %(if) then everything after
190 the %(then) is printed, else if the %(else) atom is used, then
191 everything after %(else) is printed. We ignore space when
192 evaluating the string before %(then), this is useful when we
193 use the %(HEAD) atom which prints either "*" or " " and we
194 want to apply the 'if' condition only on the 'HEAD' ref.
195 Append ":equals=<string>" or ":notequals=<string>" to compare
196 the value between the %(if:...) and %(then) atoms with the
197 given string.
199 symref::
200 The ref which the given symbolic ref refers to. If not a
201 symbolic ref, nothing is printed. Respects the `:short`,
202 `:lstrip` and `:rstrip` options in the same way as `refname`
203 above.
205 In addition to the above, for commit and tag objects, the header
206 field names (`tree`, `parent`, `object`, `type`, and `tag`) can
207 be used to specify the value in the header field.
209 For commit and tag objects, the special `creatordate` and `creator`
210 fields will correspond to the appropriate date or name-email-date tuple
211 from the `committer` or `tagger` fields depending on the object type.
212 These are intended for working on a mix of annotated and lightweight tags.
214 Fields that have name-email-date tuple as its value (`author`,
215 `committer`, and `tagger`) can be suffixed with `name`, `email`,
216 and `date` to extract the named component.
218 The complete message in a commit and tag object is `contents`.
219 Its first line is `contents:subject`, where subject is the concatenation
220 of all lines of the commit message up to the first blank line. The next
221 line is `contents:body`, where body is all of the lines after the first
222 blank line. The optional GPG signature is `contents:signature`. The
223 first `N` lines of the message is obtained using `contents:lines=N`.
224 Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
225 are obtained as `trailers` (or by using the historical alias
226 `contents:trailers`). Non-trailer lines from the trailer block can be omitted
227 with `trailers:only`. Whitespace-continuations can be removed from trailers so
228 that each trailer appears on a line by itself with its full content with
229 `trailers:unfold`. Both can be used together as `trailers:unfold,only`.
231 For sorting purposes, fields with numeric values sort in numeric order
232 (`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`).
233 All other fields are used to sort in their byte-value order.
235 There is also an option to sort by versions, this can be done by using
236 the fieldname `version:refname` or its alias `v:refname`.
238 In any case, a field name that refers to a field inapplicable to
239 the object referred by the ref does not cause an error. It
240 returns an empty string instead.
242 As a special case for the date-type fields, you may specify a format for
243 the date by adding `:` followed by date format name (see the
244 values the `--date` option to linkgit:git-rev-list[1] takes).
246 Some atoms like %(align) and %(if) always require a matching %(end).
247 We call them "opening atoms" and sometimes denote them as %($open).
249 When a scripting language specific quoting is in effect, everything
250 between a top-level opening atom and its matching %(end) is evaluated
251 according to the semantics of the opening atom and only its result
252 from the top-level is quoted.
256 --------
258 An example directly producing formatted text. Show the most recent
259 3 tagged commits:
261 ------------
262 #!/bin/sh
264 git for-each-ref --count=3 --sort='-*authordate' \
265 --format='From: %(*authorname) %(*authoremail)
266 Subject: %(*subject)
267 Date: %(*authordate)
268 Ref: %(*refname)
270 %(*body)
271 ' 'refs/tags'
272 ------------
275 A simple example showing the use of shell eval on the output,
276 demonstrating the use of --shell. List the prefixes of all heads:
277 ------------
278 #!/bin/sh
280 git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
281 while read entry
282 do
283 eval "$entry"
284 echo `dirname $ref`
285 done
286 ------------
289 A bit more elaborate report on tags, demonstrating that the format
290 may be an entire script:
291 ------------
292 #!/bin/sh
294 fmt='
295 r=%(refname)
296 t=%(*objecttype)
297 T=${r#refs/tags/}
299 o=%(*objectname)
300 n=%(*authorname)
301 e=%(*authoremail)
302 s=%(*subject)
303 d=%(*authordate)
304 b=%(*body)
306 kind=Tag
307 if test "z$t" = z
308 then
309 # could be a lightweight tag
310 t=%(objecttype)
311 kind="Lightweight tag"
312 o=%(objectname)
313 n=%(authorname)
314 e=%(authoremail)
315 s=%(subject)
316 d=%(authordate)
317 b=%(body)
318 fi
319 echo "$kind $T points at a $t object $o"
320 if test "z$t" = zcommit
321 then
322 echo "The commit was authored by $n $e
323 at $d, and titled
325 $s
327 Its message reads as:
328 "
329 echo "$b" | sed -e "s/^/ /"
330 echo
331 fi
332 '
334 eval=`git for-each-ref --shell --format="$fmt" \
335 --sort='*objecttype' \
336 --sort=-taggerdate \
337 refs/tags`
338 eval "$eval"
339 ------------
342 An example to show the usage of %(if)...%(then)...%(else)...%(end).
343 This prefixes the current branch with a star.
345 ------------
346 git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/
347 ------------
350 An example to show the usage of %(if)...%(then)...%(end).
351 This prints the authorname, if present.
353 ------------
354 git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
355 ------------
358 --------
359 linkgit:git-show-ref[1]
361 GIT
362 ---
363 Part of the linkgit:git[1] suite