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 synonym 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"). 149+ 150For any remote-tracking branch `%(upstream)`, `%(upstream:remotename)` 151and `%(upstream:remoteref)` refer to the name of the remote and the 152name of the tracked remote ref, respectively. In other words, the 153remote-tracking branch can be updated explicitly and individually by 154using the refspec `%(upstream:remoteref):%(upstream)` to fetch from 155`%(upstream:remotename)`. 156+ 157Has no effect if the ref does not have tracking information associated 158with it. All the options apart from `nobracket` are mutually exclusive, 159but if used together the last option is selected. 160 161push:: 162 The name of a local ref which represents the `@{push}` 163 location for the displayed ref. Respects `:short`, `:lstrip`, 164 `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref` 165 options as `upstream` does. Produces an empty string if no `@{push}` 166 ref is configured. 167 168HEAD:: 169 '*' if HEAD matches current ref (the checked out branch), ' ' 170 otherwise. 171 172color:: 173 Change output color. Followed by `:<colorname>`, where color 174 names are described under Values in the "CONFIGURATION FILE" 175 section of linkgit:git-config[1]. For example, 176 `%(color:bold red)`. 177 178align:: 179 Left-, middle-, or right-align the content between 180 %(align:...) and %(end). The "align:" is followed by 181 `width=<width>` and `position=<position>` in any order 182 separated by a comma, where the `<position>` is either left, 183 right or middle, default being left and `<width>` is the total 184 length of the content with alignment. For brevity, the 185 "width=" and/or "position=" prefixes may be omitted, and bare 186 <width> and <position> used instead. For instance, 187 `%(align:<width>,<position>)`. If the contents length is more 188 than the width then no alignment is performed. If used with 189 `--quote` everything in between %(align:...) and %(end) is 190 quoted, but if nested then only the topmost level performs 191 quoting. 192 193if:: 194 Used as %(if)...%(then)...%(end) or 195 %(if)...%(then)...%(else)...%(end). If there is an atom with 196 value or string literal after the %(if) then everything after 197 the %(then) is printed, else if the %(else) atom is used, then 198 everything after %(else) is printed. We ignore space when 199 evaluating the string before %(then), this is useful when we 200 use the %(HEAD) atom which prints either "*" or " " and we 201 want to apply the 'if' condition only on the 'HEAD' ref. 202 Append ":equals=<string>" or ":notequals=<string>" to compare 203 the value between the %(if:...) and %(then) atoms with the 204 given string. 205 206symref:: 207 The ref which the given symbolic ref refers to. If not a 208 symbolic ref, nothing is printed. Respects the `:short`, 209 `:lstrip` and `:rstrip` options in the same way as `refname` 210 above. 211 212In addition to the above, for commit and tag objects, the header 213field names (`tree`, `parent`, `object`, `type`, and `tag`) can 214be used to specify the value in the header field. 215 216For commit and tag objects, the special `creatordate` and `creator` 217fields will correspond to the appropriate date or name-email-date tuple 218from the `committer` or `tagger` fields depending on the object type. 219These are intended for working on a mix of annotated and lightweight tags. 220 221Fields that have name-email-date tuple as its value (`author`, 222`committer`, and `tagger`) can be suffixed with `name`, `email`, 223and `date` to extract the named component. 224 225The complete message in a commit and tag object is `contents`. 226Its first line is `contents:subject`, where subject is the concatenation 227of all lines of the commit message up to the first blank line. The next 228line is `contents:body`, where body is all of the lines after the first 229blank line. The optional GPG signature is `contents:signature`. The 230first `N` lines of the message is obtained using `contents:lines=N`. 231Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] 232are obtained as `trailers` (or by using the historical alias 233`contents:trailers`). Non-trailer lines from the trailer block can be omitted 234with `trailers:only`. Whitespace-continuations can be removed from trailers so 235that each trailer appears on a line by itself with its full content with 236`trailers:unfold`. Both can be used together as `trailers:unfold,only`. 237 238For sorting purposes, fields with numeric values sort in numeric order 239(`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`). 240All other fields are used to sort in their byte-value order. 241 242There is also an option to sort by versions, this can be done by using 243the fieldname `version:refname` or its alias `v:refname`. 244 245In any case, a field name that refers to a field inapplicable to 246the object referred by the ref does not cause an error. It 247returns an empty string instead. 248 249As a special case for the date-type fields, you may specify a format for 250the date by adding `:` followed by date format name (see the 251values the `--date` option to linkgit:git-rev-list[1] takes). 252 253Some atoms like %(align) and %(if) always require a matching %(end). 254We call them "opening atoms" and sometimes denote them as %($open). 255 256When a scripting language specific quoting is in effect, everything 257between a top-level opening atom and its matching %(end) is evaluated 258according to the semantics of the opening atom and only its result 259from the top-level is quoted. 260 261 262EXAMPLES 263-------- 264 265An example directly producing formatted text. Show the most recent 2663 tagged commits: 267 268------------ 269#!/bin/sh 270 271git for-each-ref --count=3 --sort='-*authordate' \ 272--format='From: %(*authorname) %(*authoremail) 273Subject: %(*subject) 274Date: %(*authordate) 275Ref: %(*refname) 276 277%(*body) 278' 'refs/tags' 279------------ 280 281 282A simple example showing the use of shell eval on the output, 283demonstrating the use of --shell. List the prefixes of all heads: 284------------ 285#!/bin/sh 286 287git for-each-ref --shell --format="ref=%(refname)" refs/heads | \ 288while read entry 289do 290 eval "$entry" 291 echo `dirname $ref` 292done 293------------ 294 295 296A bit more elaborate report on tags, demonstrating that the format 297may be an entire script: 298------------ 299#!/bin/sh 300 301fmt=' 302 r=%(refname) 303 t=%(*objecttype) 304 T=${r#refs/tags/} 305 306 o=%(*objectname) 307 n=%(*authorname) 308 e=%(*authoremail) 309 s=%(*subject) 310 d=%(*authordate) 311 b=%(*body) 312 313 kind=Tag 314 if test "z$t" = z 315 then 316 # could be a lightweight tag 317 t=%(objecttype) 318 kind="Lightweight tag" 319 o=%(objectname) 320 n=%(authorname) 321 e=%(authoremail) 322 s=%(subject) 323 d=%(authordate) 324 b=%(body) 325 fi 326 echo "$kind $T points at a $t object $o" 327 if test "z$t" = zcommit 328 then 329 echo "The commit was authored by $n $e 330at $d, and titled 331 332 $s 333 334Its message reads as: 335" 336 echo "$b" | sed -e "s/^/ /" 337 echo 338 fi 339' 340 341eval=`git for-each-ref --shell --format="$fmt" \ 342 --sort='*objecttype' \ 343 --sort=-taggerdate \ 344 refs/tags` 345eval "$eval" 346------------ 347 348 349An example to show the usage of %(if)...%(then)...%(else)...%(end). 350This prefixes the current branch with a star. 351 352------------ 353git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/ 354------------ 355 356 357An example to show the usage of %(if)...%(then)...%(end). 358This prints the authorname, if present. 359 360------------ 361git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)" 362------------ 363 364SEE ALSO 365-------- 366linkgit:git-show-ref[1] 367 368GIT 369--- 370Part of the linkgit:git[1] suite