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