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