| blob | 687e1cd3ae9b0ee8aebc5c160641262cf05f11b7 |
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 v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 2024-11-22
6 .\" Manual: Git Manual
7 .\" Source: Git 2.47.0.318.g04eaff62f2
8 .\" Language: English
9 .\"
10 .TH "GIT\-FOR\-EACH\-REF" "1" "2024-11-22" "Git 2\&.47\&.0\&.318\&.g04eaff" "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 .SH "DESCRIPTION"
44 .sp
45 Iterate over all refs that match \fI<pattern>\fR and show them according to the given \fI<format>\fR, after sorting them according to the given set of \fI<key>\fR\&. If \fI<count>\fR is given, stop after showing that many refs\&. The interpolated values in \fI<format>\fR can optionally be quoted as string literals in the specified host language allowing their direct evaluation in that language\&.
46 .SH "OPTIONS"
47 .PP
48 <pattern>\&...\:
49 .RS 4
50 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\&.
51 .RE
52 .PP
53 \-\-stdin
54 .RS 4
55 If
56 \fB\-\-stdin\fR
57 is supplied, then the list of patterns is read from standard input instead of from the argument list\&.
58 .RE
59 .PP
60 \-\-count=<count>
61 .RS 4
62 By default the command shows all refs that match
63 \fI<pattern>\fR\&. This option makes it stop after showing that many refs\&.
64 .RE
65 .PP
66 \-\-sort=<key>
67 .RS 4
68 A field name to sort on\&. Prefix
69 \fB\-\fR
70 to sort in descending order of the value\&. When unspecified,
71 \fBrefname\fR
72 is used\&. You may use the \-\-sort=<key> option multiple times, in which case the last key becomes the primary key\&.
73 .RE
74 .PP
75 \-\-format=<format>
76 .RS 4
77 A string that interpolates %(\fBfieldname\fR) from a ref being shown and the object it points at\&. In addition, the string literal %% renders as % and %xx \- where
78 \fBxx\fR
79 are hex digits \- renders as the character with hex code
80 \fBxx\fR\&. For example, %00 interpolates to \e0 (NUL), %09 to \et (TAB), and %0a to \en (LF)\&.
81 .sp
82 When unspecified,
83 \fI<format>\fR
84 defaults to %(\fBobjectname\fR)
85 \fBSPC\fR
86 %(\fBobjecttype\fR)
87 \fBTAB\fR
88 %(\fBrefname\fR)\&.
89 .RE
90 .PP
91 \-\-color[=<when>]
92 .RS 4
93 Respect any colors specified in the
94 \fB\-\-format\fR
95 option\&. The
96 \fI<when>\fR
97 field must be one of
98 \fBalways\fR,
99 \fBnever\fR, or
100 \fBauto\fR
101 (if
102 \fI<when>\fR
103 is absent, behave as if
104 \fBalways\fR
105 was given)\&.
106 .RE
107 .PP
108 \-\-shell, \-\-perl, \-\-python, \-\-tcl
109 .RS 4
110 If given, strings that substitute %(\fBfieldname\fR) 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\&.
111 .RE
112 .PP
113 \-\-points\-at=<object>
114 .RS 4
115 Only list refs which points at the given object\&.
116 .RE
117 .PP
118 \-\-merged[=<object>]
119 .RS 4
120 Only list refs whose tips are reachable from the specified commit (HEAD if not specified)\&.
121 .RE
122 .PP
123 \-\-no\-merged[=<object>]
124 .RS 4
125 Only list refs whose tips are not reachable from the specified commit (HEAD if not specified)\&.
126 .RE
127 .PP
128 \-\-contains[=<object>]
129 .RS 4
130 Only list refs which contain the specified commit (HEAD if not specified)\&.
131 .RE
132 .PP
133 \-\-no\-contains[=<object>]
134 .RS 4
135 Only list refs which don\(cqt contain the specified commit (HEAD if not specified)\&.
136 .RE
137 .PP
138 \-\-ignore\-case
139 .RS 4
140 Sorting and filtering refs are case insensitive\&.
141 .RE
142 .PP
143 \-\-omit\-empty
144 .RS 4
145 Do not print a newline after formatted refs where the format expands to the empty string\&.
146 .RE
147 .PP
148 \-\-exclude=<pattern>
149 .RS 4
150 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
151 \fI<pattern>\fR
152 above\&.
153 .RE
154 .PP
155 \-\-include\-root\-refs
156 .RS 4
157 List root refs (HEAD and pseudorefs) apart from regular refs\&.
158 .RE
159 .SH "FIELD NAMES"
160 .sp
161 Various values from structured fields in referenced objects can be used to interpolate into the resulting output, or as sort keys\&.
162 .sp
163 For all objects, the following names can be used:
164 .PP
165 refname
166 .RS 4
167 The name of the ref (the part after $GIT_DIR/)\&. For a non\-ambiguous short name of the ref append
168 \fB:short\fR\&. The option core\&.warnAmbiguousRefs is used to select the strict abbreviation mode\&. If
169 \fBlstrip=\fR\fI<N>\fR
170 (\fBrstrip=\fR\fI<N>\fR) is appended, strips
171 \fI<N>\fR
172 slash\-separated path components from the front (back) of the refname (e\&.g\&. %(\fBrefname:lstrip=2\fR) turns
173 \fBrefs/tags/foo\fR
174 into
175 \fBfoo\fR
176 and %(\fBrefname:rstrip=2\fR) turns
177 \fBrefs/tags/foo\fR
178 into
179 \fBrefs\fR)\&. If
180 \fI<N>\fR
181 is a negative number, strip as many path components as necessary from the specified end to leave
182 \fB\-\fR\fI<N>\fR
183 path components (e\&.g\&. %(\fBrefname:lstrip=\-2\fR) turns
184 \fBrefs/tags/foo\fR
185 into
186 \fBtags/foo\fR
187 and %(\fBrefname:rstrip=\-1\fR) turns
188 \fBrefs/tags/foo\fR
189 into
190 \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\&.
191 .sp
192 \fBstrip\fR
193 can be used as a synonym to
194 \fBlstrip\fR\&.
195 .RE
196 .PP
197 objecttype
198 .RS 4
199 The type of the object (\fBblob\fR,
200 \fBtree\fR,
201 \fBcommit\fR,
202 \fBtag\fR)\&.
203 .RE
204 .PP
205 objectsize
206 .RS 4
207 The size of the object (the same as
208 \fIgit cat\-file \-s\fR
209 reports)\&. Append
210 \fB:disk\fR
211 to get the size, in bytes, that the object takes up on disk\&. See the note about on\-disk sizes in the
212 \fBCAVEATS\fR
213 section below\&.
214 .RE
215 .PP
216 objectname
217 .RS 4
218 The object name (aka SHA\-1)\&. For a non\-ambiguous abbreviation of the object name append
219 \fB:short\fR\&. For an abbreviation of the object name with desired length append
220 \fB:short=\fR\fI<length>\fR, where the minimum length is MINIMUM_ABBREV\&. The length may be exceeded to ensure unique object names\&.
221 .RE
222 .PP
223 deltabase
224 .RS 4
225 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)\&.
226 .RE
227 .PP
228 upstream
229 .RS 4
230 The name of a local ref which can be considered
231 \(lqupstream\(rq
232 from the displayed ref\&. Respects
233 \fB:short\fR,
234 \fB:lstrip\fR
235 and
236 \fB:rstrip\fR
237 in the same way as
238 \fBrefname\fR
239 above\&. Additionally respects
240 \fB:track\fR
241 to show "[ahead N, behind M]" and
242 \fB:trackshort\fR
243 to show the terse version: ">" (ahead), "<" (behind), "<>" (ahead and behind), or "=" (in sync)\&.
244 \fB:track\fR
245 also prints "[gone]" whenever unknown upstream ref is encountered\&. Append
246 \fB:track,nobracket\fR
247 to show tracking information without brackets (i\&.e "ahead N, behind M")\&.
248 .sp
249 For any remote\-tracking branch %(\fBupstream\fR), %(\fBupstream:remotename\fR) and %(\fBupstream:remoteref\fR) 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 %(\fBupstream:remoteref\fR)\fB:\fR%(\fBupstream\fR) to fetch from %(\fBupstream:remotename\fR)\&.
250 .sp
251 Has no effect if the ref does not have tracking information associated with it\&. All the options apart from
252 \fBnobracket\fR
253 are mutually exclusive, but if used together the last option is selected\&.
254 .RE
255 .PP
256 push
257 .RS 4
258 The name of a local ref which represents the
259 \fB@\fR{push} location for the displayed ref\&. Respects
260 \fB:short\fR,
261 \fB:lstrip\fR,
262 \fB:rstrip\fR,
263 \fB:track\fR,
264 \fB:trackshort\fR,
265 \fB:remotename\fR, and
266 \fB:remoteref\fR
267 options as
268 \fBupstream\fR
269 does\&. Produces an empty string if no
270 \fB@\fR{push} ref is configured\&.
271 .RE
272 .PP
273 HEAD
274 .RS 4
275 \fI*\fR
276 if HEAD matches current ref (the checked out branch), \*(Aq \*(Aq otherwise\&.
277 .RE
278 .PP
279 color
280 .RS 4
281 Change output color\&. Followed by
282 \fB:\fR\fI<colorname>\fR, where color names are described under Values in the "CONFIGURATION FILE" section of
283 \fBgit-config\fR(1)\&. For example, %(\fBcolor:bold\fR
284 \fBred\fR)\&.
285 .RE
286 .PP
287 align
288 .RS 4
289 Left\-, middle\-, or right\-align the content between %(align:\&...\:) and %(end)\&. The "align:" is followed by
290 \fBwidth=\fR\fI<width>\fR
291 and
292 \fBposition=\fR\fI<position>\fR
293 in any order separated by a comma, where the
294 \fI<position>\fR
295 is either left, right or middle, default being left and
296 \fI<width>\fR
297 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, %(\fBalign:\fR\fI<width>\fR\fB,\fR\fI<position>\fR)\&. If the contents length is more than the width then no alignment is performed\&. If used with
298 \fB\-\-quote\fR
299 everything in between %(align:\&...\:) and %(end) is quoted, but if nested then only the topmost level performs quoting\&.
300 .RE
301 .PP
302 if
303 .RS 4
304 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
305 \fIif\fR
306 condition only on the
307 \fIHEAD\fR
308 ref\&. Append ":equals=<string>" or ":notequals=<string>" to compare the value between the %(if:\&...\:) and %(then) atoms with the given string\&.
309 .RE
310 .PP
311 symref
312 .RS 4
313 The ref which the given symbolic ref refers to\&. If not a symbolic ref, nothing is printed\&. Respects the
314 \fB:short\fR,
315 \fB:lstrip\fR
316 and
317 \fB:rstrip\fR
318 options in the same way as
319 \fBrefname\fR
320 above\&.
321 .RE
322 .PP
323 signature
324 .RS 4
325 The GPG signature of a commit\&.
326 .RE
327 .PP
328 signature:grade
329 .RS 4
330 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\&.
331 .RE
332 .PP
333 signature:signer
334 .RS 4
335 The signer of the GPG signature of a commit\&.
336 .RE
337 .PP
338 signature:key
339 .RS 4
340 The key of the GPG signature of a commit\&.
341 .RE
342 .PP
343 signature:fingerprint
344 .RS 4
345 The fingerprint of the GPG signature of a commit\&.
346 .RE
347 .PP
348 signature:primarykeyfingerprint
349 .RS 4
350 The primary key fingerprint of the GPG signature of a commit\&.
351 .RE
352 .PP
353 signature:trustlevel
354 .RS 4
355 The trust level of the GPG signature of a commit\&. Possible outputs are
356 \fBultimate\fR,
357 \fBfully\fR,
358 \fBmarginal\fR,
359 \fBnever\fR
360 and
361 \fBundefined\fR\&.
362 .RE
363 .PP
364 worktreepath
365 .RS 4
366 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\&.
367 .RE
368 .PP
369 ahead\-behind:<committish>
370 .RS 4
371 Two integers, separated by a space, demonstrating the number of commits ahead and behind, respectively, when comparing the output ref to the
372 \fI<committish>\fR
373 specified in the format\&.
374 .RE
375 .PP
376 is\-base:<committish>
377 .RS 4
378 In at most one row, (\fI<committish>\fR) will appear to indicate the ref that is most likely the ref used as a starting point for the branch that produced
379 \fI<committish>\fR\&. This choice is made using a heuristic: choose the ref that minimizes the number of commits in the first\-parent history of
380 \fI<committish>\fR
381 and not in the first\-parent history of the ref\&.
382 .sp
383 For example, consider the following figure of first\-parent histories of several refs:
384 .sp
385 .if n \{\
386 .RS 4
387 .\}
388 .nf
389 *\-\-*\-\-*\-\-*\-\-*\-\-* refs/heads/A
390 \e
391 \e
392 *\-\-*\-\-*\-\-* refs/heads/B
393 \e \e
394 \e \e
395 * * refs/heads/C
396 \e
397 \e
398 *\-\-* refs/heads/D
399 .fi
400 .if n \{\
401 .RE
402 .\}
403 .sp
404 Here, if
405 \fBA\fR,
406 \fBB\fR, and
407 \fBC\fR
408 are the filtered references, and the format string is %(\fBrefname\fR)\fB:\fR%(\fBis\-base:D\fR), then the output would be
409 .sp
410 .if n \{\
411 .RS 4
412 .\}
413 .nf
414 refs/heads/A:
415 refs/heads/B:(D)
416 refs/heads/C:
417 .fi
418 .if n \{\
419 .RE
420 .\}
421 .sp
422 This is because the first\-parent history of
423 \fBD\fR
424 has its earliest intersection with the first\-parent histories of the filtered refs at a common first\-parent ancestor of
425 \fBB\fR
426 and
427 \fBC\fR
428 and ties are broken by the earliest ref in the sorted order\&.
429 .sp
430 Note that this token will not appear if the first\-parent history of
431 \fI<committish>\fR
432 does not intersect the first\-parent histories of the filtered refs\&.
433 .RE
434 .PP
435 describe[:options]
436 .RS 4
437 A human\-readable name, like
438 \fBgit-describe\fR(1); empty string for undescribable commits\&. The
439 \fBdescribe\fR
440 string may be followed by a colon and one or more comma\-separated options\&.
441 .PP
442 tags=<bool\-value>
443 .RS 4
444 Instead of only considering annotated tags, consider lightweight tags as well; see the corresponding option in
445 \fBgit-describe\fR(1)
446 for details\&.
447 .RE
448 .PP
449 abbrev=<number>
450 .RS 4
451 Use at least <number> hexadecimal digits; see the corresponding option in
452 \fBgit-describe\fR(1)
453 for details\&.
454 .RE
455 .PP
456 match=<pattern>
457 .RS 4
458 Only consider tags matching the given
459 \fBglob\fR(\fB7\fR) pattern, excluding the "refs/tags/" prefix; see the corresponding option in
460 \fBgit-describe\fR(1)
461 for details\&.
462 .RE
463 .PP
464 exclude=<pattern>
465 .RS 4
466 Do not consider tags matching the given
467 \fBglob\fR(\fB7\fR) pattern, excluding the "refs/tags/" prefix; see the corresponding option in
468 \fBgit-describe\fR(1)
469 for details\&.
470 .RE
471 .RE
472 .sp
473 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=\fR\fI<length>\fR just like \fBobjectname\fR\&.
474 .sp
475 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\&.
476 .sp
477 For tag objects, a \fBfieldname\fR prefixed with an asterisk (*) expands to the \fBfieldname\fR value of the peeled object, rather than that of the tag object itself\&.
478 .sp
479 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))\&.
480 .sp
481 The raw data in an object is \fBraw\fR\&.
482 .PP
483 raw:size
484 .RS 4
485 The raw data size of the object\&.
486 .RE
487 .sp
488 Note that \fB\-\-format=\fR%(\fBraw\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\&.
489 .sp
490 The message in a commit or a tag object is \fBcontents\fR, from which \fBcontents:\fR\fI<part>\fR can be used to extract various parts out of:
491 .PP
492 contents:size
493 .RS 4
494 The size in bytes of the commit or tag message\&.
495 .RE
496 .PP
497 contents:subject
498 .RS 4
499 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
500 \fBcontents:subject\fR, field
501 \fBsubject\fR
502 can also be used to obtain same results\&.
503 \fB:sanitize\fR
504 can be appended to
505 \fBsubject\fR
506 for subject line suitable for filename\&.
507 .RE
508 .PP
509 contents:body
510 .RS 4
511 The remainder of the commit or the tag message that follows the "subject"\&.
512 .RE
513 .PP
514 contents:signature
515 .RS 4
516 The optional GPG signature of the tag\&.
517 .RE
518 .PP
519 contents:lines=N
520 .RS 4
521 The first
522 \fBN\fR
523 lines of the message\&.
524 .RE
525 .sp
526 Additionally, the trailers as interpreted by \fBgit-interpret-trailers\fR(1) are obtained as \fBtrailers\fR[\fB:options\fR] (or by using the historical alias \fBcontents:trailers\fR[\fB:options\fR])\&. For valid [:option] values see \fBtrailers\fR section of \fBgit-log\fR(1)\&.
527 .sp
528 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\&.
529 .sp
530 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\&.
531 .sp
532 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\&.
533 .sp
534 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\&.
535 .sp
536 Some atoms like %(align) and %(if) always require a matching %(end)\&. We call them "opening atoms" and sometimes denote them as %($open)\&.
537 .sp
538 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\&.
539 .SH "EXAMPLES"
540 .sp
541 An example directly producing formatted text\&. Show the most recent 3 tagged commits:
542 .sp
543 .if n \{\
544 .RS 4
545 .\}
546 .nf
547 #!/bin/sh
549 git for\-each\-ref \-\-count=3 \-\-sort=\*(Aq\-*authordate\*(Aq \e
550 \-\-format=\*(AqFrom: %(*authorname) %(*authoremail)
551 Subject: %(*subject)
552 Date: %(*authordate)
553 Ref: %(*refname)
555 %(*body)
556 \*(Aq \*(Aqrefs/tags\*(Aq
557 .fi
558 .if n \{\
559 .RE
560 .\}
561 .sp
562 A simple example showing the use of shell eval on the output, demonstrating the use of \-\-shell\&. List the prefixes of all heads:
563 .sp
564 .if n \{\
565 .RS 4
566 .\}
567 .nf
568 #!/bin/sh
570 git for\-each\-ref \-\-shell \-\-format="ref=%(refname)" refs/heads | \e
571 while read entry
572 do
573 eval "$entry"
574 echo `dirname $ref`
575 done
576 .fi
577 .if n \{\
578 .RE
579 .\}
580 .sp
581 A bit more elaborate report on tags, demonstrating that the format may be an entire script:
582 .sp
583 .if n \{\
584 .RS 4
585 .\}
586 .nf
587 #!/bin/sh
589 fmt=\*(Aq
590 r=%(refname)
591 t=%(*objecttype)
592 T=${r#refs/tags/}
594 o=%(*objectname)
595 n=%(*authorname)
596 e=%(*authoremail)
597 s=%(*subject)
598 d=%(*authordate)
599 b=%(*body)
601 kind=Tag
602 if test "z$t" = z
603 then
604 # could be a lightweight tag
605 t=%(objecttype)
606 kind="Lightweight tag"
607 o=%(objectname)
608 n=%(authorname)
609 e=%(authoremail)
610 s=%(subject)
611 d=%(authordate)
612 b=%(body)
613 fi
614 echo "$kind $T points at a $t object $o"
615 if test "z$t" = zcommit
616 then
617 echo "The commit was authored by $n $e
618 at $d, and titled
620 $s
622 Its message reads as:
623 "
624 echo "$b" | sed \-e "s/^/ /"
625 echo
626 fi
627 \*(Aq
629 eval=`git for\-each\-ref \-\-shell \-\-format="$fmt" \e
630 \-\-sort=\*(Aq*objecttype\*(Aq \e
631 \-\-sort=\-taggerdate \e
632 refs/tags`
633 eval "$eval"
634 .fi
635 .if n \{\
636 .RE
637 .\}
638 .sp
639 An example to show the usage of %(if)\&...\:%(then)\&...\:%(else)\&...\:%(end)\&. This prefixes the current branch with a star\&.
640 .sp
641 .if n \{\
642 .RS 4
643 .\}
644 .nf
645 git for\-each\-ref \-\-format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/
646 .fi
647 .if n \{\
648 .RE
649 .\}
650 .sp
651 An example to show the usage of %(if)\&...\:%(then)\&...\:%(end)\&. This prints the authorname, if present\&.
652 .sp
653 .if n \{\
654 .RS 4
655 .\}
656 .nf
657 git for\-each\-ref \-\-format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
658 .fi
659 .if n \{\
660 .RE
661 .\}
662 .SH "CAVEATS"
663 .sp
664 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\&.
665 .sp
666 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\&.
667 .SH "NOTES"
668 .sp
669 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\&.
670 .sp
671 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\&.
672 .SH "SEE ALSO"
673 .sp
674 \fBgit-show-ref\fR(1)
675 .SH "GIT"
676 .sp
677 Part of the \fBgit\fR(1) suite