freshlybakedca.ke
Git fork
1git-for-each-ref(1)
2===================
3
4NAME
5----
6git-for-each-ref - Output information on each ref
7
8SYNOPSIS
9--------
10[synopsis]
11git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
12 [(--sort=<key>)...] [--format=<format>]
13 [--include-root-refs] [--points-at=<object>]
14 [--merged[=<object>]] [--no-merged[=<object>]]
15 [--contains[=<object>]] [--no-contains[=<object>]]
16 [(--exclude=<pattern>)...] [--start-after=<marker>]
17 [ --stdin | (<pattern>...)]
18
19DESCRIPTION
20-----------
21
22Iterate over all refs that match _<pattern>_ and show them
23according to the given _<format>_, after sorting them according
24to the given set of _<key>_. If _<count>_ is given, stop after
25showing that many refs. The interpolated values in _<format>_
26can optionally be quoted as string literals in the specified
27host language allowing their direct evaluation in that language.
28
29OPTIONS
30-------
31include::for-each-ref-options.adoc[]
32
33FIELD NAMES
34-----------
35
36Various values from structured fields in referenced objects can
37be used to interpolate into the resulting output, or as sort
38keys.
39
40For all objects, the following names can be used:
41
42`refname`::
43 The name of the ref (the part after `$GIT_DIR/`).
44 For a non-ambiguous short name of the ref append `:short`.
45 The option `core.warnAmbiguousRefs` is used to select the strict
46 abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_
47 slash-separated path components from the front (back) of the refname
48 (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and
49 `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).
50 If _<n>_ is a negative number, strip as many path components as
51 necessary from the specified end to leave `-<n>` path components
52 (e.g. `%(refname:lstrip=-2)` turns
53 `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
54 turns `refs/tags/foo` into `refs`). When the ref does not have
55 enough components, the result becomes an empty string if
56 stripping with positive _<n>_, or it becomes the full refname if
57 stripping with negative _<N>_. Neither is an error.
58+
59`strip` can be used as a synonym to `lstrip`.
60
61`objecttype`::
62 The type of the object (`blob`, `tree`, `commit`, `tag`).
63
64`objectsize`::
65 The size of the object (the same as 'git cat-file -s' reports).
66 Append `:disk` to get the size, in bytes, that the object takes up on
67 disk. See the note about on-disk sizes in the 'CAVEATS' section below.
68`objectname`::
69 The object name (aka SHA-1).
70 For a non-ambiguous abbreviation of the object name append `:short`.
71 For an abbreviation of the object name with desired length append
72 `:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The
73 length may be exceeded to ensure unique object names.
74`deltabase`::
75 This expands to the object name of the delta base for the
76 given object, if it is stored as a delta. Otherwise it
77 expands to the null object name (all zeroes).
78
79`upstream`::
80 The name of a local ref which can be considered ``upstream''
81 from the displayed ref. Respects `:short`, `:lstrip` and
82 `:rstrip` in the same way as `refname` above. Additionally
83 respects `:track` to show "[ahead N, behind M]" and
84 `:trackshort` to show the terse version: ">" (ahead), "<"
85 (behind), "<>" (ahead and behind), or "=" (in sync). `:track`
86 also prints "[gone]" whenever unknown upstream ref is
87 encountered. Append `:track,nobracket` to show tracking
88 information without brackets (i.e "ahead N, behind M").
89+
90For any remote-tracking branch `%(upstream)`, `%(upstream:remotename)`
91and `%(upstream:remoteref)` refer to the name of the remote and the
92name of the tracked remote ref, respectively. In other words, the
93remote-tracking branch can be updated explicitly and individually by
94using the refspec `%(upstream:remoteref):%(upstream)` to fetch from
95`%(upstream:remotename)`.
96+
97Has no effect if the ref does not have tracking information associated
98with it. All the options apart from `nobracket` are mutually exclusive,
99but if used together the last option is selected.
100
101`push`::
102 The name of a local ref which represents the `@{push}`
103 location for the displayed ref. Respects `:short`, `:lstrip`,
104 `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref`
105 options as `upstream` does. Produces an empty string if no `@{push}`
106 ref is configured.
107
108`HEAD`::
109 `*` if `HEAD` matches current ref (the checked out branch), ' '
110 otherwise.
111
112`color`::
113 Change output color. Followed by `:<colorname>`, where color
114 names are described under Values in the "CONFIGURATION FILE"
115 section of linkgit:git-config[1]. For example,
116 `%(color:bold red)`.
117
118`align`::
119 Left-, middle-, or right-align the content between
120 `%(align:...)` and `%(end)`. The "`align:`" is followed by
121 `width=<width>` and `position=<position>` in any order
122 separated by a comma, where the _<position>_ is either `left`,
123 `right` or `middle`, default being `left` and _<width>_ is the total
124 length of the content with alignment. For brevity, the
125 "width=" and/or "position=" prefixes may be omitted, and bare
126 _<width>_ and _<position>_ used instead. For instance,
127 `%(align:<width>,<position>)`. If the contents length is more
128 than the width then no alignment is performed. If used with
129 `--quote` everything in between `%(align:...)` and `%(end)` is
130 quoted, but if nested then only the topmost level performs
131 quoting.
132
133`if`::
134 Used as `%(if)...%(then)...%(end)` or
135 `%(if)...%(then)...%(else)...%(end)`. If there is an atom with
136 value or string literal after the `%(if)` then everything after
137 the `%(then)` is printed, else if the `%(else)` atom is used, then
138 everything after %(else) is printed. We ignore space when
139 evaluating the string before `%(then)`, this is useful when we
140 use the `%(HEAD)` atom which prints either "`*`" or " " and we
141 want to apply the 'if' condition only on the `HEAD` ref.
142 Append "`:equals=<string>`" or "`:notequals=<string>`" to compare
143 the value between the `%(if:...)` and `%(then)` atoms with the
144 given string.
145
146`symref`::
147 The ref which the given symbolic ref refers to. If not a
148 symbolic ref, nothing is printed. Respects the `:short`,
149 `:lstrip` and `:rstrip` options in the same way as `refname`
150 above.
151
152`signature`::
153 The GPG signature of a commit.
154
155`signature:grade`::
156 Show
157`G`;; for a good (valid) signature
158`B`;; for a bad signature
159`U`;; for a good signature with unknown validity
160`X`;; for a good signature that has expired
161`Y`;; for a good signature made by an expired key
162`R`;; for a good signature made by a revoked key
163`E`;; if the signature cannot be checked (e.g. missing key)
164`N`;; for no signature.
165
166`signature:signer`::
167 The signer of the GPG signature of a commit.
168
169`signature:key`::
170 The key of the GPG signature of a commit.
171
172`signature:fingerprint`::
173 The fingerprint of the GPG signature of a commit.
174
175`signature:primarykeyfingerprint`::
176 The primary key fingerprint of the GPG signature of a commit.
177
178`signature:trustlevel`::
179 The trust level of the GPG signature of a commit. Possible
180 outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`.
181
182`worktreepath`::
183 The absolute path to the worktree in which the ref is checked
184 out, if it is checked out in any linked worktree. Empty string
185 otherwise.
186
187`ahead-behind:<commit-ish>`::
188 Two integers, separated by a space, demonstrating the number of
189 commits ahead and behind, respectively, when comparing the output
190 ref to the _<committish>_ specified in the format.
191
192`is-base:<commit-ish>`::
193 In at most one row, `(<commit-ish>)` will appear to indicate the ref
194 that is most likely the ref used as a starting point for the branch
195 that produced _<commit-ish>_. This choice is made using a heuristic:
196 choose the ref that minimizes the number of commits in the
197 first-parent history of _<commit-ish>_ and not in the first-parent
198 history of the ref.
199+
200For example, consider the following figure of first-parent histories of
201several refs:
202+
203----
204*--*--*--*--*--* refs/heads/A
205\
206 \
207 *--*--*--* refs/heads/B
208 \ \
209 \ \
210 * * refs/heads/C
211 \
212 \
213 *--* refs/heads/D
214----
215+
216Here, if `A`, `B`, and `C` are the filtered references, and the format
217string is `%(refname):%(is-base:D)`, then the output would be
218+
219----
220refs/heads/A:
221refs/heads/B:(D)
222refs/heads/C:
223----
224+
225This is because the first-parent history of `D` has its earliest
226intersection with the first-parent histories of the filtered refs at a
227common first-parent ancestor of `B` and `C` and ties are broken by the
228earliest ref in the sorted order.
229+
230Note that this token will not appear if the first-parent history of
231_<commit-ish>_ does not intersect the first-parent histories of the
232filtered refs.
233
234`describe[:<option>,...]`::
235 A human-readable name, like linkgit:git-describe[1];
236 empty string for undescribable commits. The `describe` string may
237 be followed by a colon and one or more comma-separated options.
238+
239--
240`tags=<bool-value>`;;
241 Instead of only considering annotated tags, consider
242 lightweight tags as well; see the corresponding option in
243 linkgit:git-describe[1] for details.
244`abbrev=<number>`;;
245 Use at least _<number>_ hexadecimal digits; see the corresponding
246 option in linkgit:git-describe[1] for details.
247`match=<pattern>`;;
248 Only consider tags matching the `glob`(7) _<pattern>_,
249 excluding the `refs/tags/` prefix; see the corresponding option
250 in linkgit:git-describe[1] for details.
251`exclude=<pattern>`;;
252 Do not consider tags matching the `glob`(7) _<pattern>_,
253 excluding the `refs/tags/` prefix; see the corresponding option
254 in linkgit:git-describe[1] for details.
255--
256
257In addition to the above, for commit and tag objects, the header
258field names (`tree`, `parent`, `object`, `type`, and `tag`) can
259be used to specify the value in the header field.
260Fields `tree` and `parent` can also be used with modifier `:short` and
261`:short=<length>` just like `objectname`.
262
263For commit and tag objects, the special `creatordate` and `creator`
264fields will correspond to the appropriate date or name-email-date tuple
265from the `committer` or `tagger` fields depending on the object type.
266These are intended for working on a mix of annotated and lightweight tags.
267
268For tag objects, a `fieldname` prefixed with an asterisk (`*`) expands to
269the `fieldname` value of the peeled object, rather than that of the tag
270object itself.
271
272Fields that have name-email-date tuple as its value (`author`,
273`committer`, and `tagger`) can be suffixed with `name`, `email`,
274and `date` to extract the named component. For email fields (`authoremail`,
275`committeremail` and `taggeremail`), `:trim` can be appended to get the email
276without angle brackets, and `:localpart` to get the part before the `@` symbol
277out of the trimmed email. In addition to these, the `:mailmap` option and the
278corresponding `:mailmap,trim` and `:mailmap,localpart` can be used (order does
279not matter) to get values of the name and email according to the .mailmap file
280or according to the file set in the mailmap.file or mailmap.blob configuration
281variable (see linkgit:gitmailmap[5]).
282
283The raw data in an object is `raw`.
284
285`raw:size`::
286 The raw data size of the object.
287
288Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`,
289because such language may not support arbitrary binary data in their string
290variable type.
291
292The message in a commit or a tag object is `contents`, from which
293`contents:<part>` can be used to extract various parts out of:
294
295`contents:size`::
296 The size in bytes of the commit or tag message.
297
298`contents:subject`::
299 The first paragraph of the message, which typically is a
300 single line, is taken as the "subject" of the commit or the
301 tag message.
302 Instead of `contents:subject`, field `subject` can also be used to
303 obtain same results. `:sanitize` can be appended to `subject` for
304 subject line suitable for filename.
305
306`contents:body`::
307 The remainder of the commit or the tag message that follows
308 the "subject".
309
310`contents:signature`::
311 The optional GPG signature of the tag.
312
313`contents:lines=<n>`::
314 The first _<n>_ lines of the message.
315
316Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
317are obtained as `trailers[:<option>,...]` (or by using the historical alias
318`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers`
319section of linkgit:git-log[1].
320
321For sorting purposes, fields with numeric values sort in numeric order
322(`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`).
323All other fields are used to sort in their byte-value order.
324
325There is also an option to sort by versions, this can be done by using
326the fieldname `version:refname` or its alias `v:refname`.
327
328In any case, a field name that refers to a field inapplicable to
329the object referred by the ref does not cause an error. It
330returns an empty string instead.
331
332As a special case for the date-type fields, you may specify a format for the
333date by adding `:` followed by date format name (see the values the `--date`
334option to linkgit:git-rev-list[1] takes). If this formatting is provided in
335a `--sort` key, references will be sorted according to the byte-value of the
336formatted string rather than the numeric value of the underlying timestamp.
337
338Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`.
339We call them "opening atoms" and sometimes denote them as `%($open)`.
340
341When a scripting language specific quoting is in effect, everything
342between a top-level opening atom and its matching %(end) is evaluated
343according to the semantics of the opening atom and only its result
344from the top-level is quoted.
345
346
347EXAMPLES
348--------
349
350An example directly producing formatted text. Show the most recent
3513 tagged commits:
352
353------------
354#!/bin/sh
355
356git for-each-ref --count=3 --sort='-*authordate' \
357`--format='From: %(*authorname) %(*authoremail)
358Subject: %(*subject)
359Date: %(*authordate)
360Ref: %(*refname)
361
362%(*body)
363' 'refs/tags'
364------------
365
366
367A simple example showing the use of shell eval on the output,
368demonstrating the use of `--shell`. List the prefixes of all heads:
369
370------------
371#!/bin/sh
372
373git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
374while read entry
375do
376 eval "$entry"
377 echo `dirname $ref`
378done
379------------
380
381
382A bit more elaborate report on tags, demonstrating that the format
383may be an entire script:
384
385------------
386#!/bin/sh
387
388fmt='
389 r=%(refname)
390 t=%(*objecttype)
391 T=${r#refs/tags/}
392
393 o=%(*objectname)
394 n=%(*authorname)
395 e=%(*authoremail)
396 s=%(*subject)
397 d=%(*authordate)
398 b=%(*body)
399
400 kind=Tag
401 if test "z$t" = z
402 then
403 # could be a lightweight tag
404 t=%(objecttype)
405 kind="Lightweight tag"
406 o=%(objectname)
407 n=%(authorname)
408 e=%(authoremail)
409 s=%(subject)
410 d=%(authordate)
411 b=%(body)
412 fi
413 echo "$kind $T points at a $t object $o"
414 if test "z$t" = zcommit
415 then
416 echo "The commit was authored by $n $e
417at $d, and titled
418
419 $s
420
421Its message reads as:
422"
423 echo "$b" | sed -e "s/^/ /"
424 echo
425 fi
426'
427
428eval=`git for-each-ref --shell --format="$fmt" \
429 --sort='*objecttype' \
430 --sort=-taggerdate \
431 refs/tags`
432eval "$eval"
433------------
434
435
436An example to show the usage of `%(if)...%(then)...%(else)...%(end)`.
437This prefixes the current branch with a star.
438
439------------
440git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/
441------------
442
443
444An example to show the usage of `%(if)...%(then)...%(end)`.
445This prints the authorname, if present.
446
447------------
448git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
449------------
450
451CAVEATS
452-------
453
454Note that the sizes of objects on disk are reported accurately, but care
455should be taken in drawing conclusions about which refs or objects are
456responsible for disk usage. The size of a packed non-delta object may be
457much larger than the size of objects which delta against it, but the
458choice of which object is the base and which is the delta is arbitrary
459and is subject to change during a repack.
460
461Note also that multiple copies of an object may be present in the object
462database; in this case, it is undefined which copy's size or delta base
463will be reported.
464
465NOTES
466-----
467
468include::ref-reachability-filters.adoc[]
469
470SEE ALSO
471--------
472linkgit:git-show-ref[1]
473
474GIT
475---
476Part of the linkgit:git[1] suite