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