1git-for-each-ref(1) 2=================== 3 4NAME 5---- 6git-for-each-ref - Output information on each ref 7 8SYNOPSIS 9-------- 10[verse] 11'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] 12 [(--sort=<key>)...] [--format=<format>] [<pattern>...] 13 [--points-at=<object>] 14 (--merged[=<object>] | --no-merged[=<object>]) 15 [--contains[=<object>]] [--no-contains[=<object>]] 16 17DESCRIPTION 18----------- 19 20Iterate over all refs that match `<pattern>` and show them 21according to the given `<format>`, after sorting them according 22to the given set of `<key>`. If `<count>` is given, stop after 23showing that many refs. The interpolated values in `<format>` 24can optionally be quoted as string literals in the specified 25host language allowing their direct evaluation in that language. 26 27OPTIONS 28------- 29<pattern>...:: 30 If one or more patterns are given, only refs are shown that 31 match against at least one pattern, either using fnmatch(3) or 32 literally, in the latter case matching completely or from the 33 beginning up to a slash. 34 35--count=<count>:: 36 By default the command shows all refs that match 37 `<pattern>`. This option makes it stop after showing 38 that many refs. 39 40--sort=<key>:: 41 A field name to sort on. Prefix `-` to sort in 42 descending order of the value. When unspecified, 43 `refname` is used. You may use the --sort=<key> option 44 multiple times, in which case the last key becomes the primary 45 key. 46 47--format=<format>:: 48 A string that interpolates `%(fieldname)` from a ref being shown 49 and the object it points at. If `fieldname` 50 is prefixed with an asterisk (`*`) and the ref points 51 at a tag object, use the value for the field in the object 52 which the tag object refers to (instead of the field in the tag object). 53 When unspecified, `<format>` defaults to 54 `%(objectname) SPC %(objecttype) TAB %(refname)`. 55 It also interpolates `%%` to `%`, and `%xx` where `xx` 56 are hex digits interpolates to character with hex code 57 `xx`; for example `%00` interpolates to `\0` (NUL), 58 `%09` to `\t` (TAB) and `%0a` to `\n` (LF). 59 60--color[=<when>]: 61 Respect any colors specified in the `--format` option. The 62 `<when>` field must be one of `always`, `never`, or `auto` (if 63 `<when>` is absent, behave as if `always` was given). 64 65--shell:: 66--perl:: 67--python:: 68--tcl:: 69 If given, strings that substitute `%(fieldname)` 70 placeholders are quoted as string literals suitable for 71 the specified host language. This is meant to produce 72 a scriptlet that can directly be `eval`ed. 73 74--points-at=<object>:: 75 Only list refs which points at the given object. 76 77--merged[=<object>]:: 78 Only list refs whose tips are reachable from the 79 specified commit (HEAD if not specified), 80 incompatible with `--no-merged`. 81 82--no-merged[=<object>]:: 83 Only list refs whose tips are not reachable from the 84 specified commit (HEAD if not specified), 85 incompatible with `--merged`. 86 87--contains[=<object>]:: 88 Only list refs which contain the specified commit (HEAD if not 89 specified). 90 91--no-contains[=<object>]:: 92 Only list refs which don't contain the specified commit (HEAD 93 if not specified). 94 95--ignore-case:: 96 Sorting and filtering refs are case insensitive. 97 98FIELD NAMES 99----------- 100 101Various values from structured fields in referenced objects can 102be used to interpolate into the resulting output, or as sort 103keys. 104 105For all objects, the following names can be used: 106 107refname:: 108 The name of the ref (the part after $GIT_DIR/). 109 For a non-ambiguous short name of the ref append `:short`. 110 The option core.warnAmbiguousRefs is used to select the strict 111 abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` 112 slash-separated path components from the front (back) of the refname 113 (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and 114 `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). 115 If `<N>` is a negative number, strip as many path components as 116 necessary from the specified end to leave `-<N>` path components 117 (e.g. `%(refname:lstrip=-2)` turns 118 `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` 119 turns `refs/tags/foo` into `refs`). When the ref does not have 120 enough components, the result becomes an empty string if 121 stripping with positive <N>, or it becomes the full refname if 122 stripping with negative <N>. Neither is an error. 123+ 124`strip` can be used as a synomym to `lstrip`. 125 126objecttype:: 127 The type of the object (`blob`, `tree`, `commit`, `tag`). 128 129objectsize:: 130 The size of the object (the same as 'git cat-file -s' reports). 131 132objectname:: 133 The object name (aka SHA-1). 134 For a non-ambiguous abbreviation of the object name append `:short`. 135 For an abbreviation of the object name with desired length append 136 `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The 137 length may be exceeded to ensure unique object names. 138 139upstream:: 140 The name of a local ref which can be considered ``upstream'' 141 from the displayed ref. Respects `:short`, `:lstrip` and 142 `:rstrip` in the same way as `refname` above. Additionally 143 respects `:track` to show "[ahead N, behind M]" and 144 `:trackshort` to show the terse version: ">" (ahead), "<" 145 (behind), "<>" (ahead and behind), or "=" (in sync). `:track` 146 also prints "[gone]" whenever unknown upstream ref is 147 encountered. Append `:track,nobracket` to show tracking 148 information without brackets (i.e "ahead N, behind M"). Has 149 no effect if the ref does not have tracking information 150 associated with it. All the options apart from `nobracket` 151 are mutually exclusive, but if used together the last option 152 is selected. 153 154push:: 155 The name of a local ref which represents the `@{push}` 156 location for the displayed ref. Respects `:short`, `:lstrip`, 157 `:rstrip`, `:track`, and `:trackshort` options as `upstream` 158 does. Produces an empty string if no `@{push}` ref is 159 configured. 160 161HEAD:: 162 '*' if HEAD matches current ref (the checked out branch), ' ' 163 otherwise. 164 165color:: 166 Change output color. Followed by `:<colorname>`, where color 167 names are described under Values in the "CONFIGURATION FILE" 168 section of linkgit:git-config[1]. For example, 169 `%(color:bold red)`. 170 171align:: 172 Left-, middle-, or right-align the content between 173 %(align:...) and %(end). The "align:" is followed by 174 `width=<width>` and `position=<position>` in any order 175 separated by a comma, where the `<position>` is either left, 176 right or middle, default being left and `<width>` is the total 177 length of the content with alignment. For brevity, the 178 "width=" and/or "position=" prefixes may be omitted, and bare 179 <width> and <position> used instead. For instance, 180 `%(align:<width>,<position>)`. If the contents length is more 181 than the width then no alignment is performed. If used with 182 `--quote` everything in between %(align:...) and %(end) is 183 quoted, but if nested then only the topmost level performs 184 quoting. 185 186if:: 187 Used as %(if)...%(then)...%(end) or 188 %(if)...%(then)...%(else)...%(end). If there is an atom with 189 value or string literal after the %(if) then everything after 190 the %(then) is printed, else if the %(else) atom is used, then 191 everything after %(else) is printed. We ignore space when 192 evaluating the string before %(then), this is useful when we 193 use the %(HEAD) atom which prints either "*" or " " and we 194 want to apply the 'if' condition only on the 'HEAD' ref. 195 Append ":equals=<string>" or ":notequals=<string>" to compare 196 the value between the %(if:...) and %(then) atoms with the 197 given string. 198 199symref:: 200 The ref which the given symbolic ref refers to. If not a 201 symbolic ref, nothing is printed. Respects the `:short`, 202 `:lstrip` and `:rstrip` options in the same way as `refname` 203 above. 204 205In addition to the above, for commit and tag objects, the header 206field names (`tree`, `parent`, `object`, `type`, and `tag`) can 207be used to specify the value in the header field. 208 209For commit and tag objects, the special `creatordate` and `creator` 210fields will correspond to the appropriate date or name-email-date tuple 211from the `committer` or `tagger` fields depending on the object type. 212These are intended for working on a mix of annotated and lightweight tags. 213 214Fields that have name-email-date tuple as its value (`author`, 215`committer`, and `tagger`) can be suffixed with `name`, `email`, 216and `date` to extract the named component. 217 218The complete message in a commit and tag object is `contents`. 219Its first line is `contents:subject`, where subject is the concatenation 220of all lines of the commit message up to the first blank line. The next 221line is `contents:body`, where body is all of the lines after the first 222blank line. The optional GPG signature is `contents:signature`. The 223first `N` lines of the message is obtained using `contents:lines=N`. 224Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] 225are obtained as `trailers` (or by using the historical alias 226`contents:trailers`). Non-trailer lines from the trailer block can be omitted 227with `trailers:only`. Whitespace-continuations can be removed from trailers so 228that each trailer appears on a line by itself with its full content with 229`trailers:unfold`. Both can be used together as `trailers:unfold,only`. 230 231For sorting purposes, fields with numeric values sort in numeric order 232(`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`). 233All other fields are used to sort in their byte-value order. 234 235There is also an option to sort by versions, this can be done by using 236the fieldname `version:refname` or its alias `v:refname`. 237 238In any case, a field name that refers to a field inapplicable to 239the object referred by the ref does not cause an error. It 240returns an empty string instead. 241 242As a special case for the date-type fields, you may specify a format for 243the date by adding `:` followed by date format name (see the 244values the `--date` option to linkgit:git-rev-list[1] takes). 245 246Some atoms like %(align) and %(if) always require a matching %(end). 247We call them "opening atoms" and sometimes denote them as %($open). 248 249When a scripting language specific quoting is in effect, everything 250between a top-level opening atom and its matching %(end) is evaluated 251according to the semantics of the opening atom and only its result 252from the top-level is quoted. 253 254 255EXAMPLES 256-------- 257 258An example directly producing formatted text. Show the most recent 2593 tagged commits: 260 261------------ 262#!/bin/sh 263 264git for-each-ref --count=3 --sort='-*authordate' \ 265--format='From: %(*authorname) %(*authoremail) 266Subject: %(*subject) 267Date: %(*authordate) 268Ref: %(*refname) 269 270%(*body) 271' 'refs/tags' 272------------ 273 274 275A simple example showing the use of shell eval on the output, 276demonstrating the use of --shell. List the prefixes of all heads: 277------------ 278#!/bin/sh 279 280git for-each-ref --shell --format="ref=%(refname)" refs/heads | \ 281while read entry 282do 283 eval "$entry" 284 echo `dirname $ref` 285done 286------------ 287 288 289A bit more elaborate report on tags, demonstrating that the format 290may be an entire script: 291------------ 292#!/bin/sh 293 294fmt=' 295 r=%(refname) 296 t=%(*objecttype) 297 T=${r#refs/tags/} 298 299 o=%(*objectname) 300 n=%(*authorname) 301 e=%(*authoremail) 302 s=%(*subject) 303 d=%(*authordate) 304 b=%(*body) 305 306 kind=Tag 307 if test "z$t" = z 308 then 309 # could be a lightweight tag 310 t=%(objecttype) 311 kind="Lightweight tag" 312 o=%(objectname) 313 n=%(authorname) 314 e=%(authoremail) 315 s=%(subject) 316 d=%(authordate) 317 b=%(body) 318 fi 319 echo "$kind $T points at a $t object $o" 320 if test "z$t" = zcommit 321 then 322 echo "The commit was authored by $n $e 323at $d, and titled 324 325 $s 326 327Its message reads as: 328" 329 echo "$b" | sed -e "s/^/ /" 330 echo 331 fi 332' 333 334eval=`git for-each-ref --shell --format="$fmt" \ 335 --sort='*objecttype' \ 336 --sort=-taggerdate \ 337 refs/tags` 338eval "$eval" 339------------ 340 341 342An example to show the usage of %(if)...%(then)...%(else)...%(end). 343This prefixes the current branch with a star. 344 345------------ 346git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/ 347------------ 348 349 350An example to show the usage of %(if)...%(then)...%(end). 351This prints the authorname, if present. 352 353------------ 354git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)" 355------------ 356 357SEE ALSO 358-------- 359linkgit:git-show-ref[1] 360 361GIT 362--- 363Part of the linkgit:git[1] suite