| blob | 5ca23062b1ec94d843c42f0fa4b838d826d31a92 |
1 '\" t
2 .\" Title: git-for-each-ref
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2024-04-15
6 .\" Manual: Git Manual
7 .\" Source: Git 2.44.0.616.g548fe35913
8 .\" Language: English
9 .\"
10 .TH "GIT\-FOR\-EACH\-REF" "1" "2024\-04\-15" "Git 2\&.44\&.0\&.616\&.g548fe3" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-for-each-ref \- Output information on each ref
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit for\-each\-ref\fR [\-\-count=<count>] [\-\-shell|\-\-perl|\-\-python|\-\-tcl]
36 [(\-\-sort=<key>)\&...] [\-\-format=<format>]
37 [\-\-include\-root\-refs] [ \-\-stdin | <pattern>\&... ]
38 [\-\-points\-at=<object>]
39 [\-\-merged[=<object>]] [\-\-no\-merged[=<object>]]
40 [\-\-contains[=<object>]] [\-\-no\-contains[=<object>]]
41 [\-\-exclude=<pattern> \&...]
42 .fi
43 .sp
44 .SH "DESCRIPTION"
45 .sp
46 Iterate over all refs that match \fB<pattern>\fR and show them according to the given \fB<format>\fR, after sorting them according to the given set of \fB<key>\fR\&. If \fB<count>\fR is given, stop after showing that many refs\&. The interpolated values in \fB<format>\fR can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language\&.
47 .SH "OPTIONS"
48 .PP
49 <pattern>\&...
50 .RS 4
51 If one or more patterns are given, only refs are shown that match against at least one pattern, either using fnmatch(3) or literally, in the latter case matching completely or from the beginning up to a slash\&.
52 .RE
53 .PP
54 \-\-stdin
55 .RS 4
56 If
57 \fB\-\-stdin\fR
58 is supplied, then the list of patterns is read from standard input instead of from the argument list\&.
59 .RE
60 .PP
61 \-\-count=<count>
62 .RS 4
63 By default the command shows all refs that match
64 \fB<pattern>\fR\&. This option makes it stop after showing that many refs\&.
65 .RE
66 .PP
67 \-\-sort=<key>
68 .RS 4
69 A field name to sort on\&. Prefix
70 \fB\-\fR
71 to sort in descending order of the value\&. When unspecified,
72 \fBrefname\fR
73 is used\&. You may use the \-\-sort=<key> option multiple times, in which case the last key becomes the primary key\&.
74 .RE
75 .PP
76 \-\-format=<format>
77 .RS 4
78 A string that interpolates
79 \fB%(fieldname)\fR
80 from a ref being shown and the object it points at\&. In addition, the string literal
81 \fB%%\fR
82 renders as
83 \fB%\fR
84 and
85 \fB%xx\fR
86 \- where
87 \fBxx\fR
88 are hex digits \- renders as the character with hex code
89 \fBxx\fR\&. For example,
90 \fB%00\fR
91 interpolates to
92 \fB\e0\fR
93 (NUL),
94 \fB%09\fR
95 to
96 \fB\et\fR
97 (TAB), and
98 \fB%0a\fR
99 to
100 \fB\en\fR
101 (LF)\&.
102 .sp
103 When unspecified,
104 \fB<format>\fR
105 defaults to
106 \fB%(objectname) SPC %(objecttype) TAB %(refname)\fR\&.
107 .RE
108 .PP
109 \-\-color[=<when>]
110 .RS 4
111 Respect any colors specified in the
112 \fB\-\-format\fR
113 option\&. The
114 \fB<when>\fR
115 field must be one of
116 \fBalways\fR,
117 \fBnever\fR, or
118 \fBauto\fR
119 (if
120 \fB<when>\fR
121 is absent, behave as if
122 \fBalways\fR
123 was given)\&.
124 .RE
125 .PP
126 \-\-shell, \-\-perl, \-\-python, \-\-tcl
127 .RS 4
128 If given, strings that substitute
129 \fB%(fieldname)\fR
130 placeholders are quoted as string literals suitable for the specified host language\&. This is meant to produce a scriptlet that can directly be `eval`ed\&.
131 .RE
132 .PP
133 \-\-points\-at=<object>
134 .RS 4
135 Only list refs which points at the given object\&.
136 .RE
137 .PP
138 \-\-merged[=<object>]
139 .RS 4
140 Only list refs whose tips are reachable from the specified commit (HEAD if not specified)\&.
141 .RE
142 .PP
143 \-\-no\-merged[=<object>]
144 .RS 4
145 Only list refs whose tips are not reachable from the specified commit (HEAD if not specified)\&.
146 .RE
147 .PP
148 \-\-contains[=<object>]
149 .RS 4
150 Only list refs which contain the specified commit (HEAD if not specified)\&.
151 .RE
152 .PP
153 \-\-no\-contains[=<object>]
154 .RS 4
155 Only list refs which don\(cqt contain the specified commit (HEAD if not specified)\&.
156 .RE
157 .PP
158 \-\-ignore\-case
159 .RS 4
160 Sorting and filtering refs are case insensitive\&.
161 .RE
162 .PP
163 \-\-omit\-empty
164 .RS 4
165 Do not print a newline after formatted refs where the format expands to the empty string\&.
166 .RE
167 .PP
168 \-\-exclude=<pattern>
169 .RS 4
170 If one or more patterns are given, only refs which do not match any excluded pattern(s) are shown\&. Matching is done using the same rules as
171 \fB<pattern>\fR
172 above\&.
173 .RE
174 .PP
175 \-\-include\-root\-refs
176 .RS 4
177 List root refs (HEAD and pseudorefs) apart from regular refs\&.
178 .RE
179 .SH "FIELD NAMES"
180 .sp
181 Various values from structured fields in referenced objects can be used to interpolate into the resulting output, or as sort keys\&.
182 .sp
183 For all objects, the following names can be used:
184 .PP
185 refname
186 .RS 4
187 The name of the ref (the part after $GIT_DIR/)\&. For a non\-ambiguous short name of the ref append
188 \fB:short\fR\&. The option core\&.warnAmbiguousRefs is used to select the strict abbreviation mode\&. If
189 \fBlstrip=<N>\fR
190 (\fBrstrip=<N>\fR) is appended, strips
191 \fB<N>\fR
192 slash\-separated path components from the front (back) of the refname (e\&.g\&.
193 \fB%(refname:lstrip=2)\fR
194 turns
195 \fBrefs/tags/foo\fR
196 into
197 \fBfoo\fR
198 and
199 \fB%(refname:rstrip=2)\fR
200 turns
201 \fBrefs/tags/foo\fR
202 into
203 \fBrefs\fR)\&. If
204 \fB<N>\fR
205 is a negative number, strip as many path components as necessary from the specified end to leave
206 \fB\-<N>\fR
207 path components (e\&.g\&.
208 \fB%(refname:lstrip=\-2)\fR
209 turns
210 \fBrefs/tags/foo\fR
211 into
212 \fBtags/foo\fR
213 and
214 \fB%(refname:rstrip=\-1)\fR
215 turns
216 \fBrefs/tags/foo\fR
217 into
218 \fBrefs\fR)\&. When the ref does not have enough components, the result becomes an empty string if stripping with positive <N>, or it becomes the full refname if stripping with negative <N>\&. Neither is an error\&.
219 .sp
220 \fBstrip\fR
221 can be used as a synonym to
222 \fBlstrip\fR\&.
223 .RE
224 .PP
225 objecttype
226 .RS 4
227 The type of the object (\fBblob\fR,
228 \fBtree\fR,
229 \fBcommit\fR,
230 \fBtag\fR)\&.
231 .RE
232 .PP
233 objectsize
234 .RS 4
235 The size of the object (the same as
236 \fIgit cat\-file \-s\fR
237 reports)\&. Append
238 \fB:disk\fR
239 to get the size, in bytes, that the object takes up on disk\&. See the note about on\-disk sizes in the
240 \fBCAVEATS\fR
241 section below\&.
242 .RE
243 .PP
244 objectname
245 .RS 4
246 The object name (aka SHA\-1)\&. For a non\-ambiguous abbreviation of the object name append
247 \fB:short\fR\&. For an abbreviation of the object name with desired length append
248 \fB:short=<length>\fR, where the minimum length is MINIMUM_ABBREV\&. The length may be exceeded to ensure unique object names\&.
249 .RE
250 .PP
251 deltabase
252 .RS 4
253 This expands to the object name of the delta base for the given object, if it is stored as a delta\&. Otherwise it expands to the null object name (all zeroes)\&.
254 .RE
255 .PP
256 upstream
257 .RS 4
258 The name of a local ref which can be considered \(lqupstream\(rq from the displayed ref\&. Respects
259 \fB:short\fR,
260 \fB:lstrip\fR
261 and
262 \fB:rstrip\fR
263 in the same way as
264 \fBrefname\fR
265 above\&. Additionally respects
266 \fB:track\fR
267 to show "[ahead N, behind M]" and
268 \fB:trackshort\fR
269 to show the terse version: ">" (ahead), "<" (behind), "<>" (ahead and behind), or "=" (in sync)\&.
270 \fB:track\fR
271 also prints "[gone]" whenever unknown upstream ref is encountered\&. Append
272 \fB:track,nobracket\fR
273 to show tracking information without brackets (i\&.e "ahead N, behind M")\&.
274 .sp
275 For any remote\-tracking branch
276 \fB%(upstream)\fR,
277 \fB%(upstream:remotename)\fR
278 and
279 \fB%(upstream:remoteref)\fR
280 refer to the name of the remote and the name of the tracked remote ref, respectively\&. In other words, the remote\-tracking branch can be updated explicitly and individually by using the refspec
281 \fB%(upstream:remoteref):%(upstream)\fR
282 to fetch from
283 \fB%(upstream:remotename)\fR\&.
284 .sp
285 Has no effect if the ref does not have tracking information associated with it\&. All the options apart from
286 \fBnobracket\fR
287 are mutually exclusive, but if used together the last option is selected\&.
288 .RE
289 .PP
290 push
291 .RS 4
292 The name of a local ref which represents the
293 \fB@{push}\fR
294 location for the displayed ref\&. Respects
295 \fB:short\fR,
296 \fB:lstrip\fR,
297 \fB:rstrip\fR,
298 \fB:track\fR,
299 \fB:trackshort\fR,
300 \fB:remotename\fR, and
301 \fB:remoteref\fR
302 options as
303 \fBupstream\fR
304 does\&. Produces an empty string if no
305 \fB@{push}\fR
306 ref is configured\&.
307 .RE
308 .PP
309 HEAD
310 .RS 4
311 \fI*\fR
312 if HEAD matches current ref (the checked out branch), \*(Aq \*(Aq otherwise\&.
313 .RE
314 .PP
315 color
316 .RS 4
317 Change output color\&. Followed by
318 \fB:<colorname>\fR, where color names are described under Values in the "CONFIGURATION FILE" section of
319 \fBgit-config\fR(1)\&. For example,
320 \fB%(color:bold red)\fR\&.
321 .RE
322 .PP
323 align
324 .RS 4
325 Left\-, middle\-, or right\-align the content between %(align:\&...) and %(end)\&. The "align:" is followed by
326 \fBwidth=<width>\fR
327 and
328 \fBposition=<position>\fR
329 in any order separated by a comma, where the
330 \fB<position>\fR
331 is either left, right or middle, default being left and
332 \fB<width>\fR
333 is the total length of the content with alignment\&. For brevity, the "width=" and/or "position=" prefixes may be omitted, and bare <width> and <position> used instead\&. For instance,
334 \fB%(align:<width>,<position>)\fR\&. If the contents length is more than the width then no alignment is performed\&. If used with
335 \fB\-\-quote\fR
336 everything in between %(align:\&...) and %(end) is quoted, but if nested then only the topmost level performs quoting\&.
337 .RE
338 .PP
339 if
340 .RS 4
341 Used as %(if)\&...%(then)\&...%(end) or %(if)\&...%(then)\&...%(else)\&...%(end)\&. If there is an atom with value or string literal after the %(if) then everything after the %(then) is printed, else if the %(else) atom is used, then everything after %(else) is printed\&. We ignore space when evaluating the string before %(then), this is useful when we use the %(HEAD) atom which prints either "*" or " " and we want to apply the
342 \fIif\fR
343 condition only on the
344 \fIHEAD\fR
345 ref\&. Append ":equals=<string>" or ":notequals=<string>" to compare the value between the %(if:\&...) and %(then) atoms with the given string\&.
346 .RE
347 .PP
348 symref
349 .RS 4
350 The ref which the given symbolic ref refers to\&. If not a symbolic ref, nothing is printed\&. Respects the
351 \fB:short\fR,
352 \fB:lstrip\fR
353 and
354 \fB:rstrip\fR
355 options in the same way as
356 \fBrefname\fR
357 above\&.
358 .RE
359 .PP
360 signature
361 .RS 4
362 The GPG signature of a commit\&.
363 .RE
364 .PP
365 signature:grade
366 .RS 4
367 Show "G" for a good (valid) signature, "B" for a bad signature, "U" for a good signature with unknown validity, "X" for a good signature that has expired, "Y" for a good signature made by an expired key, "R" for a good signature made by a revoked key, "E" if the signature cannot be checked (e\&.g\&. missing key) and "N" for no signature\&.
368 .RE
369 .PP
370 signature:signer
371 .RS 4
372 The signer of the GPG signature of a commit\&.
373 .RE
374 .PP
375 signature:key
376 .RS 4
377 The key of the GPG signature of a commit\&.
378 .RE
379 .PP
380 signature:fingerprint
381 .RS 4
382 The fingerprint of the GPG signature of a commit\&.
383 .RE
384 .PP
385 signature:primarykeyfingerprint
386 .RS 4
387 The primary key fingerprint of the GPG signature of a commit\&.
388 .RE
389 .PP
390 signature:trustlevel
391 .RS 4
392 The trust level of the GPG signature of a commit\&. Possible outputs are
393 \fBultimate\fR,
394 \fBfully\fR,
395 \fBmarginal\fR,
396 \fBnever\fR
397 and
398 \fBundefined\fR\&.
399 .RE
400 .PP
401 worktreepath
402 .RS 4
403 The absolute path to the worktree in which the ref is checked out, if it is checked out in any linked worktree\&. Empty string otherwise\&.
404 .RE
405 .PP
406 ahead\-behind:<committish>
407 .RS 4
408 Two integers, separated by a space, demonstrating the number of commits ahead and behind, respectively, when comparing the output ref to the
409 \fB<committish>\fR
410 specified in the format\&.
411 .RE
412 .PP
413 describe[:options]
414 .RS 4
415 A human\-readable name, like
416 \fBgit-describe\fR(1); empty string for undescribable commits\&. The
417 \fBdescribe\fR
418 string may be followed by a colon and one or more comma\-separated options\&.
419 .PP
420 tags=<bool\-value>
421 .RS 4
422 Instead of only considering annotated tags, consider lightweight tags as well; see the corresponding option in
423 \fBgit-describe\fR(1)
424 for details\&.
425 .RE
426 .PP
427 abbrev=<number>
428 .RS 4
429 Use at least <number> hexadecimal digits; see the corresponding option in
430 \fBgit-describe\fR(1)
431 for details\&.
432 .RE
433 .PP
434 match=<pattern>
435 .RS 4
436 Only consider tags matching the given
437 \fBglob(7)\fR
438 pattern, excluding the "refs/tags/" prefix; see the corresponding option in
439 \fBgit-describe\fR(1)
440 for details\&.
441 .RE
442 .PP
443 exclude=<pattern>
444 .RS 4
445 Do not consider tags matching the given
446 \fBglob(7)\fR
447 pattern, excluding the "refs/tags/" prefix; see the corresponding option in
448 \fBgit-describe\fR(1)
449 for details\&.
450 .RE
451 .RE
452 .sp
453 In addition to the above, for commit and tag objects, the header field names (\fBtree\fR, \fBparent\fR, \fBobject\fR, \fBtype\fR, and \fBtag\fR) can be used to specify the value in the header field\&. Fields \fBtree\fR and \fBparent\fR can also be used with modifier \fB:short\fR and \fB:short=<length>\fR just like \fBobjectname\fR\&.
454 .sp
455 For commit and tag objects, the special \fBcreatordate\fR and \fBcreator\fR fields will correspond to the appropriate date or name\-email\-date tuple from the \fBcommitter\fR or \fBtagger\fR fields depending on the object type\&. These are intended for working on a mix of annotated and lightweight tags\&.
456 .sp
457 For tag objects, a \fBfieldname\fR prefixed with an asterisk (\fB*\fR) expands to the \fBfieldname\fR value of the peeled object, rather than that of the tag object itself\&.
458 .sp
459 Fields that have name\-email\-date tuple as its value (\fBauthor\fR, \fBcommitter\fR, and \fBtagger\fR) can be suffixed with \fBname\fR, \fBemail\fR, and \fBdate\fR to extract the named component\&. For email fields (\fBauthoremail\fR, \fBcommitteremail\fR and \fBtaggeremail\fR), \fB:trim\fR can be appended to get the email without angle brackets, and \fB:localpart\fR to get the part before the \fB@\fR symbol out of the trimmed email\&. In addition to these, the \fB:mailmap\fR option and the corresponding \fB:mailmap,trim\fR and \fB:mailmap,localpart\fR can be used (order does not matter) to get values of the name and email according to the \&.mailmap file or according to the file set in the mailmap\&.file or mailmap\&.blob configuration variable (see \fBgitmailmap\fR(5))\&.
460 .sp
461 The raw data in an object is \fBraw\fR\&.
462 .PP
463 raw:size
464 .RS 4
465 The raw data size of the object\&.
466 .RE
467 .sp
468 Note that \fB\-\-format=%(raw)\fR can not be used with \fB\-\-python\fR, \fB\-\-shell\fR, \fB\-\-tcl\fR, because such language may not support arbitrary binary data in their string variable type\&.
469 .sp
470 The message in a commit or a tag object is \fBcontents\fR, from which \fBcontents:<part>\fR can be used to extract various parts out of:
471 .PP
472 contents:size
473 .RS 4
474 The size in bytes of the commit or tag message\&.
475 .RE
476 .PP
477 contents:subject
478 .RS 4
479 The first paragraph of the message, which typically is a single line, is taken as the "subject" of the commit or the tag message\&. Instead of
480 \fBcontents:subject\fR, field
481 \fBsubject\fR
482 can also be used to obtain same results\&.
483 \fB:sanitize\fR
484 can be appended to
485 \fBsubject\fR
486 for subject line suitable for filename\&.
487 .RE
488 .PP
489 contents:body
490 .RS 4
491 The remainder of the commit or the tag message that follows the "subject"\&.
492 .RE
493 .PP
494 contents:signature
495 .RS 4
496 The optional GPG signature of the tag\&.
497 .RE
498 .PP
499 contents:lines=N
500 .RS 4
501 The first
502 \fBN\fR
503 lines of the message\&.
504 .RE
505 .sp
506 Additionally, the trailers as interpreted by \fBgit-interpret-trailers\fR(1) are obtained as \fBtrailers[:options]\fR (or by using the historical alias \fBcontents:trailers[:options]\fR)\&. For valid [:option] values see \fBtrailers\fR section of \fBgit-log\fR(1)\&.
507 .sp
508 For sorting purposes, fields with numeric values sort in numeric order (\fBobjectsize\fR, \fBauthordate\fR, \fBcommitterdate\fR, \fBcreatordate\fR, \fBtaggerdate\fR)\&. All other fields are used to sort in their byte\-value order\&.
509 .sp
510 There is also an option to sort by versions, this can be done by using the fieldname \fBversion:refname\fR or its alias \fBv:refname\fR\&.
511 .sp
512 In any case, a field name that refers to a field inapplicable to the object referred by the ref does not cause an error\&. It returns an empty string instead\&.
513 .sp
514 As a special case for the date\-type fields, you may specify a format for the date by adding \fB:\fR followed by date format name (see the values the \fB\-\-date\fR option to \fBgit-rev-list\fR(1) takes)\&. If this formatting is provided in a \fB\-\-sort\fR key, references will be sorted according to the byte\-value of the formatted string rather than the numeric value of the underlying timestamp\&.
515 .sp
516 Some atoms like %(align) and %(if) always require a matching %(end)\&. We call them "opening atoms" and sometimes denote them as %($open)\&.
517 .sp
518 When a scripting language specific quoting is in effect, everything between a top\-level opening atom and its matching %(end) is evaluated according to the semantics of the opening atom and only its result from the top\-level is quoted\&.
519 .SH "EXAMPLES"
520 .sp
521 An example directly producing formatted text\&. Show the most recent 3 tagged commits:
522 .sp
523 .if n \{\
524 .RS 4
525 .\}
526 .nf
527 #!/bin/sh
529 git for\-each\-ref \-\-count=3 \-\-sort=\*(Aq\-*authordate\*(Aq \e
530 \-\-format=\*(AqFrom: %(*authorname) %(*authoremail)
531 Subject: %(*subject)
532 Date: %(*authordate)
533 Ref: %(*refname)
535 %(*body)
536 \*(Aq \*(Aqrefs/tags\*(Aq
537 .fi
538 .if n \{\
539 .RE
540 .\}
541 .sp
542 .sp
543 A simple example showing the use of shell eval on the output, demonstrating the use of \-\-shell\&. List the prefixes of all heads:
544 .sp
545 .if n \{\
546 .RS 4
547 .\}
548 .nf
549 #!/bin/sh
551 git for\-each\-ref \-\-shell \-\-format="ref=%(refname)" refs/heads | \e
552 while read entry
553 do
554 eval "$entry"
555 echo `dirname $ref`
556 done
557 .fi
558 .if n \{\
559 .RE
560 .\}
561 .sp
562 .sp
563 A bit more elaborate report on tags, demonstrating that the format may be an entire script:
564 .sp
565 .if n \{\
566 .RS 4
567 .\}
568 .nf
569 #!/bin/sh
571 fmt=\*(Aq
572 r=%(refname)
573 t=%(*objecttype)
574 T=${r#refs/tags/}
576 o=%(*objectname)
577 n=%(*authorname)
578 e=%(*authoremail)
579 s=%(*subject)
580 d=%(*authordate)
581 b=%(*body)
583 kind=Tag
584 if test "z$t" = z
585 then
586 # could be a lightweight tag
587 t=%(objecttype)
588 kind="Lightweight tag"
589 o=%(objectname)
590 n=%(authorname)
591 e=%(authoremail)
592 s=%(subject)
593 d=%(authordate)
594 b=%(body)
595 fi
596 echo "$kind $T points at a $t object $o"
597 if test "z$t" = zcommit
598 then
599 echo "The commit was authored by $n $e
600 at $d, and titled
602 $s
604 Its message reads as:
605 "
606 echo "$b" | sed \-e "s/^/ /"
607 echo
608 fi
609 \*(Aq
611 eval=`git for\-each\-ref \-\-shell \-\-format="$fmt" \e
612 \-\-sort=\*(Aq*objecttype\*(Aq \e
613 \-\-sort=\-taggerdate \e
614 refs/tags`
615 eval "$eval"
616 .fi
617 .if n \{\
618 .RE
619 .\}
620 .sp
621 .sp
622 An example to show the usage of %(if)\&...%(then)\&...%(else)\&...%(end)\&. This prefixes the current branch with a star\&.
623 .sp
624 .if n \{\
625 .RS 4
626 .\}
627 .nf
628 git for\-each\-ref \-\-format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/
629 .fi
630 .if n \{\
631 .RE
632 .\}
633 .sp
634 .sp
635 An example to show the usage of %(if)\&...%(then)\&...%(end)\&. This prints the authorname, if present\&.
636 .sp
637 .if n \{\
638 .RS 4
639 .\}
640 .nf
641 git for\-each\-ref \-\-format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
642 .fi
643 .if n \{\
644 .RE
645 .\}
646 .sp
647 .SH "CAVEATS"
648 .sp
649 Note that the sizes of objects on disk are reported accurately, but care should be taken in drawing conclusions about which refs or objects are responsible for disk usage\&. The size of a packed non\-delta object may be much larger than the size of objects which delta against it, but the choice of which object is the base and which is the delta is arbitrary and is subject to change during a repack\&.
650 .sp
651 Note also that multiple copies of an object may be present in the object database; in this case, it is undefined which copy\(cqs size or delta base will be reported\&.
652 .SH "NOTES"
653 .sp
654 When combining multiple \fB\-\-contains\fR and \fB\-\-no\-contains\fR filters, only references that contain at least one of the \fB\-\-contains\fR commits and contain none of the \fB\-\-no\-contains\fR commits are shown\&.
655 .sp
656 When combining multiple \fB\-\-merged\fR and \fB\-\-no\-merged\fR filters, only references that are reachable from at least one of the \fB\-\-merged\fR commits and from none of the \fB\-\-no\-merged\fR commits are shown\&.
657 .SH "SEE ALSO"
658 .sp
659 \fBgit-show-ref\fR(1)
660 .SH "GIT"
661 .sp
662 Part of the \fBgit\fR(1) suite