| blob | 84a0e9aaebb910502d89eba7c3dc21460c487a78 |
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-02-15
6 .\" Manual: Git Manual
7 .\" Source: Git 2.44.0.rc1.17.g3e0d3cd5c7
8 .\" Language: English
9 .\"
10 .TH "GIT\-FOR\-EACH\-REF" "1" "2024\-02\-15" "Git 2\&.44\&.0\&.rc1\&.17\&.g3" "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 [ \-\-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 .SH "FIELD NAMES"
175 .sp
176 Various values from structured fields in referenced objects can be used to interpolate into the resulting output, or as sort keys\&.
177 .sp
178 For all objects, the following names can be used:
179 .PP
180 refname
181 .RS 4
182 The name of the ref (the part after $GIT_DIR/)\&. For a non\-ambiguous short name of the ref append
183 \fB:short\fR\&. The option core\&.warnAmbiguousRefs is used to select the strict abbreviation mode\&. If
184 \fBlstrip=<N>\fR
185 (\fBrstrip=<N>\fR) is appended, strips
186 \fB<N>\fR
187 slash\-separated path components from the front (back) of the refname (e\&.g\&.
188 \fB%(refname:lstrip=2)\fR
189 turns
190 \fBrefs/tags/foo\fR
191 into
192 \fBfoo\fR
193 and
194 \fB%(refname:rstrip=2)\fR
195 turns
196 \fBrefs/tags/foo\fR
197 into
198 \fBrefs\fR)\&. If
199 \fB<N>\fR
200 is a negative number, strip as many path components as necessary from the specified end to leave
201 \fB\-<N>\fR
202 path components (e\&.g\&.
203 \fB%(refname:lstrip=\-2)\fR
204 turns
205 \fBrefs/tags/foo\fR
206 into
207 \fBtags/foo\fR
208 and
209 \fB%(refname:rstrip=\-1)\fR
210 turns
211 \fBrefs/tags/foo\fR
212 into
213 \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\&.
214 .sp
215 \fBstrip\fR
216 can be used as a synonym to
217 \fBlstrip\fR\&.
218 .RE
219 .PP
220 objecttype
221 .RS 4
222 The type of the object (\fBblob\fR,
223 \fBtree\fR,
224 \fBcommit\fR,
225 \fBtag\fR)\&.
226 .RE
227 .PP
228 objectsize
229 .RS 4
230 The size of the object (the same as
231 \fIgit cat\-file \-s\fR
232 reports)\&. Append
233 \fB:disk\fR
234 to get the size, in bytes, that the object takes up on disk\&. See the note about on\-disk sizes in the
235 \fBCAVEATS\fR
236 section below\&.
237 .RE
238 .PP
239 objectname
240 .RS 4
241 The object name (aka SHA\-1)\&. For a non\-ambiguous abbreviation of the object name append
242 \fB:short\fR\&. For an abbreviation of the object name with desired length append
243 \fB:short=<length>\fR, where the minimum length is MINIMUM_ABBREV\&. The length may be exceeded to ensure unique object names\&.
244 .RE
245 .PP
246 deltabase
247 .RS 4
248 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)\&.
249 .RE
250 .PP
251 upstream
252 .RS 4
253 The name of a local ref which can be considered \(lqupstream\(rq from the displayed ref\&. Respects
254 \fB:short\fR,
255 \fB:lstrip\fR
256 and
257 \fB:rstrip\fR
258 in the same way as
259 \fBrefname\fR
260 above\&. Additionally respects
261 \fB:track\fR
262 to show "[ahead N, behind M]" and
263 \fB:trackshort\fR
264 to show the terse version: ">" (ahead), "<" (behind), "<>" (ahead and behind), or "=" (in sync)\&.
265 \fB:track\fR
266 also prints "[gone]" whenever unknown upstream ref is encountered\&. Append
267 \fB:track,nobracket\fR
268 to show tracking information without brackets (i\&.e "ahead N, behind M")\&.
269 .sp
270 For any remote\-tracking branch
271 \fB%(upstream)\fR,
272 \fB%(upstream:remotename)\fR
273 and
274 \fB%(upstream:remoteref)\fR
275 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
276 \fB%(upstream:remoteref):%(upstream)\fR
277 to fetch from
278 \fB%(upstream:remotename)\fR\&.
279 .sp
280 Has no effect if the ref does not have tracking information associated with it\&. All the options apart from
281 \fBnobracket\fR
282 are mutually exclusive, but if used together the last option is selected\&.
283 .RE
284 .PP
285 push
286 .RS 4
287 The name of a local ref which represents the
288 \fB@{push}\fR
289 location for the displayed ref\&. Respects
290 \fB:short\fR,
291 \fB:lstrip\fR,
292 \fB:rstrip\fR,
293 \fB:track\fR,
294 \fB:trackshort\fR,
295 \fB:remotename\fR, and
296 \fB:remoteref\fR
297 options as
298 \fBupstream\fR
299 does\&. Produces an empty string if no
300 \fB@{push}\fR
301 ref is configured\&.
302 .RE
303 .PP
304 HEAD
305 .RS 4
306 \fI*\fR
307 if HEAD matches current ref (the checked out branch), \*(Aq \*(Aq otherwise\&.
308 .RE
309 .PP
310 color
311 .RS 4
312 Change output color\&. Followed by
313 \fB:<colorname>\fR, where color names are described under Values in the "CONFIGURATION FILE" section of
314 \fBgit-config\fR(1)\&. For example,
315 \fB%(color:bold red)\fR\&.
316 .RE
317 .PP
318 align
319 .RS 4
320 Left\-, middle\-, or right\-align the content between %(align:\&...) and %(end)\&. The "align:" is followed by
321 \fBwidth=<width>\fR
322 and
323 \fBposition=<position>\fR
324 in any order separated by a comma, where the
325 \fB<position>\fR
326 is either left, right or middle, default being left and
327 \fB<width>\fR
328 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,
329 \fB%(align:<width>,<position>)\fR\&. If the contents length is more than the width then no alignment is performed\&. If used with
330 \fB\-\-quote\fR
331 everything in between %(align:\&...) and %(end) is quoted, but if nested then only the topmost level performs quoting\&.
332 .RE
333 .PP
334 if
335 .RS 4
336 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
337 \fIif\fR
338 condition only on the
339 \fIHEAD\fR
340 ref\&. Append ":equals=<string>" or ":notequals=<string>" to compare the value between the %(if:\&...) and %(then) atoms with the given string\&.
341 .RE
342 .PP
343 symref
344 .RS 4
345 The ref which the given symbolic ref refers to\&. If not a symbolic ref, nothing is printed\&. Respects the
346 \fB:short\fR,
347 \fB:lstrip\fR
348 and
349 \fB:rstrip\fR
350 options in the same way as
351 \fBrefname\fR
352 above\&.
353 .RE
354 .PP
355 signature
356 .RS 4
357 The GPG signature of a commit\&.
358 .RE
359 .PP
360 signature:grade
361 .RS 4
362 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\&.
363 .RE
364 .PP
365 signature:signer
366 .RS 4
367 The signer of the GPG signature of a commit\&.
368 .RE
369 .PP
370 signature:key
371 .RS 4
372 The key of the GPG signature of a commit\&.
373 .RE
374 .PP
375 signature:fingerprint
376 .RS 4
377 The fingerprint of the GPG signature of a commit\&.
378 .RE
379 .PP
380 signature:primarykeyfingerprint
381 .RS 4
382 The primary key fingerprint of the GPG signature of a commit\&.
383 .RE
384 .PP
385 signature:trustlevel
386 .RS 4
387 The trust level of the GPG signature of a commit\&. Possible outputs are
388 \fBultimate\fR,
389 \fBfully\fR,
390 \fBmarginal\fR,
391 \fBnever\fR
392 and
393 \fBundefined\fR\&.
394 .RE
395 .PP
396 worktreepath
397 .RS 4
398 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\&.
399 .RE
400 .PP
401 ahead\-behind:<committish>
402 .RS 4
403 Two integers, separated by a space, demonstrating the number of commits ahead and behind, respectively, when comparing the output ref to the
404 \fB<committish>\fR
405 specified in the format\&.
406 .RE
407 .PP
408 describe[:options]
409 .RS 4
410 A human\-readable name, like
411 \fBgit-describe\fR(1); empty string for undescribable commits\&. The
412 \fBdescribe\fR
413 string may be followed by a colon and one or more comma\-separated options\&.
414 .PP
415 tags=<bool\-value>
416 .RS 4
417 Instead of only considering annotated tags, consider lightweight tags as well; see the corresponding option in
418 \fBgit-describe\fR(1)
419 for details\&.
420 .RE
421 .PP
422 abbrev=<number>
423 .RS 4
424 Use at least <number> hexadecimal digits; see the corresponding option in
425 \fBgit-describe\fR(1)
426 for details\&.
427 .RE
428 .PP
429 match=<pattern>
430 .RS 4
431 Only consider tags matching the given
432 \fBglob(7)\fR
433 pattern, excluding the "refs/tags/" prefix; see the corresponding option in
434 \fBgit-describe\fR(1)
435 for details\&.
436 .RE
437 .PP
438 exclude=<pattern>
439 .RS 4
440 Do not consider tags matching the given
441 \fBglob(7)\fR
442 pattern, excluding the "refs/tags/" prefix; see the corresponding option in
443 \fBgit-describe\fR(1)
444 for details\&.
445 .RE
446 .RE
447 .sp
448 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\&.
449 .sp
450 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\&.
451 .sp
452 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\&.
453 .sp
454 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))\&.
455 .sp
456 The raw data in an object is \fBraw\fR\&.
457 .PP
458 raw:size
459 .RS 4
460 The raw data size of the object\&.
461 .RE
462 .sp
463 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\&.
464 .sp
465 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:
466 .PP
467 contents:size
468 .RS 4
469 The size in bytes of the commit or tag message\&.
470 .RE
471 .PP
472 contents:subject
473 .RS 4
474 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
475 \fBcontents:subject\fR, field
476 \fBsubject\fR
477 can also be used to obtain same results\&.
478 \fB:sanitize\fR
479 can be appended to
480 \fBsubject\fR
481 for subject line suitable for filename\&.
482 .RE
483 .PP
484 contents:body
485 .RS 4
486 The remainder of the commit or the tag message that follows the "subject"\&.
487 .RE
488 .PP
489 contents:signature
490 .RS 4
491 The optional GPG signature of the tag\&.
492 .RE
493 .PP
494 contents:lines=N
495 .RS 4
496 The first
497 \fBN\fR
498 lines of the message\&.
499 .RE
500 .sp
501 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)\&.
502 .sp
503 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\&.
504 .sp
505 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\&.
506 .sp
507 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\&.
508 .sp
509 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\&.
510 .sp
511 Some atoms like %(align) and %(if) always require a matching %(end)\&. We call them "opening atoms" and sometimes denote them as %($open)\&.
512 .sp
513 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\&.
514 .SH "EXAMPLES"
515 .sp
516 An example directly producing formatted text\&. Show the most recent 3 tagged commits:
517 .sp
518 .if n \{\
519 .RS 4
520 .\}
521 .nf
522 #!/bin/sh
524 git for\-each\-ref \-\-count=3 \-\-sort=\*(Aq\-*authordate\*(Aq \e
525 \-\-format=\*(AqFrom: %(*authorname) %(*authoremail)
526 Subject: %(*subject)
527 Date: %(*authordate)
528 Ref: %(*refname)
530 %(*body)
531 \*(Aq \*(Aqrefs/tags\*(Aq
532 .fi
533 .if n \{\
534 .RE
535 .\}
536 .sp
537 .sp
538 A simple example showing the use of shell eval on the output, demonstrating the use of \-\-shell\&. List the prefixes of all heads:
539 .sp
540 .if n \{\
541 .RS 4
542 .\}
543 .nf
544 #!/bin/sh
546 git for\-each\-ref \-\-shell \-\-format="ref=%(refname)" refs/heads | \e
547 while read entry
548 do
549 eval "$entry"
550 echo `dirname $ref`
551 done
552 .fi
553 .if n \{\
554 .RE
555 .\}
556 .sp
557 .sp
558 A bit more elaborate report on tags, demonstrating that the format may be an entire script:
559 .sp
560 .if n \{\
561 .RS 4
562 .\}
563 .nf
564 #!/bin/sh
566 fmt=\*(Aq
567 r=%(refname)
568 t=%(*objecttype)
569 T=${r#refs/tags/}
571 o=%(*objectname)
572 n=%(*authorname)
573 e=%(*authoremail)
574 s=%(*subject)
575 d=%(*authordate)
576 b=%(*body)
578 kind=Tag
579 if test "z$t" = z
580 then
581 # could be a lightweight tag
582 t=%(objecttype)
583 kind="Lightweight tag"
584 o=%(objectname)
585 n=%(authorname)
586 e=%(authoremail)
587 s=%(subject)
588 d=%(authordate)
589 b=%(body)
590 fi
591 echo "$kind $T points at a $t object $o"
592 if test "z$t" = zcommit
593 then
594 echo "The commit was authored by $n $e
595 at $d, and titled
597 $s
599 Its message reads as:
600 "
601 echo "$b" | sed \-e "s/^/ /"
602 echo
603 fi
604 \*(Aq
606 eval=`git for\-each\-ref \-\-shell \-\-format="$fmt" \e
607 \-\-sort=\*(Aq*objecttype\*(Aq \e
608 \-\-sort=\-taggerdate \e
609 refs/tags`
610 eval "$eval"
611 .fi
612 .if n \{\
613 .RE
614 .\}
615 .sp
616 .sp
617 An example to show the usage of %(if)\&...%(then)\&...%(else)\&...%(end)\&. This prefixes the current branch with a star\&.
618 .sp
619 .if n \{\
620 .RS 4
621 .\}
622 .nf
623 git for\-each\-ref \-\-format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/
624 .fi
625 .if n \{\
626 .RE
627 .\}
628 .sp
629 .sp
630 An example to show the usage of %(if)\&...%(then)\&...%(end)\&. This prints the authorname, if present\&.
631 .sp
632 .if n \{\
633 .RS 4
634 .\}
635 .nf
636 git for\-each\-ref \-\-format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
637 .fi
638 .if n \{\
639 .RE
640 .\}
641 .sp
642 .SH "CAVEATS"
643 .sp
644 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\&.
645 .sp
646 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\&.
647 .SH "NOTES"
648 .sp
649 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\&.
650 .sp
651 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\&.
652 .SH "SEE ALSO"
653 .sp
654 \fBgit-show-ref\fR(1)
655 .SH "GIT"
656 .sp
657 Part of the \fBgit\fR(1) suite