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>` (`rstrip=<N>`) is appended, strips `<N>` 99 slash-separated path components from the front (back) of the refname 100 (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and 101 `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). 102 If `<N>` is a negative number, strip as many path components as 103 necessary from the specified end to leave `-<N>` path components 104 (e.g. `%(refname:lstrip=-2)` turns 105 `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` 106 turns `refs/tags/foo` into `refs`). When the ref does not have 107 enough components, the result becomes an empty string if 108 stripping with positive <N>, or it becomes the full refname if 109 stripping with negative <N>. Neither is an error. 110 111objecttype:: 112 The type of the object (`blob`, `tree`, `commit`, `tag`). 113 114objectsize:: 115 The size of the object (the same as 'git cat-file -s' reports). 116 117objectname:: 118 The object name (aka SHA-1). 119 For a non-ambiguous abbreviation of the object name append `:short`. 120 For an abbreviation of the object name with desired length append 121 `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The 122 length may be exceeded to ensure unique object names. 123 124upstream:: 125 The name of a local ref which can be considered ``upstream'' 126 from the displayed ref. Respects `:short`, `:lstrip` and 127 `:rstrip` in the same way as `refname` above. Additionally 128 respects `:track` to show "[ahead N, behind M]" and 129 `:trackshort` to show the terse version: ">" (ahead), "<" 130 (behind), "<>" (ahead and behind), or "=" (in sync). `:track` 131 also prints "[gone]" whenever unknown upstream ref is 132 encountered. Append `:track,nobracket` to show tracking 133 information without brackets (i.e "ahead N, behind M"). Has 134 no effect if the ref does not have tracking information 135 associated with it. All the options apart from `nobracket` 136 are mutually exclusive, but if used together the last option 137 is selected. 138 139push:: 140 The name of a local ref which represents the `@{push}` 141 location for the displayed ref. Respects `:short`, `:lstrip`, 142 `:rstrip`, `:track`, and `:trackshort` options as `upstream` 143 does. Produces an empty string if no `@{push}` ref is 144 configured. 145 146HEAD:: 147 '*' if HEAD matches current ref (the checked out branch), ' ' 148 otherwise. 149 150color:: 151 Change output color. Followed by `:<colorname>`, where names 152 are described in `color.branch.*`. 153 154align:: 155 Left-, middle-, or right-align the content between 156 %(align:...) and %(end). The "align:" is followed by 157 `width=<width>` and `position=<position>` in any order 158 separated by a comma, where the `<position>` is either left, 159 right or middle, default being left and `<width>` is the total 160 length of the content with alignment. For brevity, the 161 "width=" and/or "position=" prefixes may be omitted, and bare 162 <width> and <position> used instead. For instance, 163 `%(align:<width>,<position>)`. If the contents length is more 164 than the width then no alignment is performed. If used with 165 `--quote` everything in between %(align:...) and %(end) is 166 quoted, but if nested then only the topmost level performs 167 quoting. 168 169if:: 170 Used as %(if)...%(then)...%(end) or 171 %(if)...%(then)...%(else)...%(end). If there is an atom with 172 value or string literal after the %(if) then everything after 173 the %(then) is printed, else if the %(else) atom is used, then 174 everything after %(else) is printed. We ignore space when 175 evaluating the string before %(then), this is useful when we 176 use the %(HEAD) atom which prints either "*" or " " and we 177 want to apply the 'if' condition only on the 'HEAD' ref. 178 Append ":equals=<string>" or ":notequals=<string>" to compare 179 the value between the %(if:...) and %(then) atoms with the 180 given string. 181 182symref:: 183 The ref which the given symbolic ref refers to. If not a 184 symbolic ref, nothing is printed. Respects the `:short`, 185 `:lstrip` and `:rstrip` options in the same way as `refname` 186 above. 187 188In addition to the above, for commit and tag objects, the header 189field names (`tree`, `parent`, `object`, `type`, and `tag`) can 190be used to specify the value in the header field. 191 192For commit and tag objects, the special `creatordate` and `creator` 193fields will correspond to the appropriate date or name-email-date tuple 194from the `committer` or `tagger` fields depending on the object type. 195These are intended for working on a mix of annotated and lightweight tags. 196 197Fields that have name-email-date tuple as its value (`author`, 198`committer`, and `tagger`) can be suffixed with `name`, `email`, 199and `date` to extract the named component. 200 201The complete message in a commit and tag object is `contents`. 202Its first line is `contents:subject`, where subject is the concatenation 203of all lines of the commit message up to the first blank line. The next 204line is 'contents:body', where body is all of the lines after the first 205blank line. The optional GPG signature is `contents:signature`. The 206first `N` lines of the message is obtained using `contents:lines=N`. 207Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] 208are obtained as 'contents:trailers'. 209 210For sorting purposes, fields with numeric values sort in numeric order 211(`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`). 212All other fields are used to sort in their byte-value order. 213 214There is also an option to sort by versions, this can be done by using 215the fieldname `version:refname` or its alias `v:refname`. 216 217In any case, a field name that refers to a field inapplicable to 218the object referred by the ref does not cause an error. It 219returns an empty string instead. 220 221As a special case for the date-type fields, you may specify a format for 222the date by adding `:` followed by date format name (see the 223values the `--date` option to linkgit:git-rev-list[1] takes). 224 225Some atoms like %(align) and %(if) always require a matching %(end). 226We call them "opening atoms" and sometimes denote them as %($open). 227 228When a scripting language specific quoting is in effect, everything 229between a top-level opening atom and its matching %(end) is evaluated 230according to the semantics of the opening atom and only its result 231from the top-level is quoted. 232 233 234EXAMPLES 235-------- 236 237An example directly producing formatted text. Show the most recent 2383 tagged commits: 239 240------------ 241#!/bin/sh 242 243git for-each-ref --count=3 --sort='-*authordate' \ 244--format='From: %(*authorname) %(*authoremail) 245Subject: %(*subject) 246Date: %(*authordate) 247Ref: %(*refname) 248 249%(*body) 250' 'refs/tags' 251------------ 252 253 254A simple example showing the use of shell eval on the output, 255demonstrating the use of --shell. List the prefixes of all heads: 256------------ 257#!/bin/sh 258 259git for-each-ref --shell --format="ref=%(refname)" refs/heads | \ 260while read entry 261do 262 eval "$entry" 263 echo `dirname $ref` 264done 265------------ 266 267 268A bit more elaborate report on tags, demonstrating that the format 269may be an entire script: 270------------ 271#!/bin/sh 272 273fmt=' 274 r=%(refname) 275 t=%(*objecttype) 276 T=${r#refs/tags/} 277 278 o=%(*objectname) 279 n=%(*authorname) 280 e=%(*authoremail) 281 s=%(*subject) 282 d=%(*authordate) 283 b=%(*body) 284 285 kind=Tag 286 if test "z$t" = z 287 then 288 # could be a lightweight tag 289 t=%(objecttype) 290 kind="Lightweight tag" 291 o=%(objectname) 292 n=%(authorname) 293 e=%(authoremail) 294 s=%(subject) 295 d=%(authordate) 296 b=%(body) 297 fi 298 echo "$kind $T points at a $t object $o" 299 if test "z$t" = zcommit 300 then 301 echo "The commit was authored by $n $e 302at $d, and titled 303 304 $s 305 306Its message reads as: 307" 308 echo "$b" | sed -e "s/^/ /" 309 echo 310 fi 311' 312 313eval=`git for-each-ref --shell --format="$fmt" \ 314 --sort='*objecttype' \ 315 --sort=-taggerdate \ 316 refs/tags` 317eval "$eval" 318------------ 319 320 321An example to show the usage of %(if)...%(then)...%(else)...%(end). 322This prefixes the current branch with a star. 323 324------------ 325git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/ 326------------ 327 328 329An example to show the usage of %(if)...%(then)...%(end). 330This prints the authorname, if present. 331 332------------ 333git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)" 334------------ 335 336SEE ALSO 337-------- 338linkgit:git-show-ref[1] 339 340GIT 341--- 342Part of the linkgit:git[1] suite