1git-for-each-ref(1) 2=================== 3 4NAME 5---- 6git-for-each-ref - Output information on each ref 7 8SYNOPSIS 9-------- 10'git-for-each-ref' [--count=<count>]* [--shell|--perl|--python] [--sort=<key>]* [--format=<format>] [<pattern>] 11 12DESCRIPTION 13----------- 14 15Iterate over all refs that match `<pattern>` and show them 16according to the given `<format>`, after sorting them according 17to the given set of `<key>`s. If `<max>` is given, stop after 18showing that many refs. The interporated values in `<format>` 19can optionally be quoted as string literals in the specified 20host language allowing their direct evaluation in that language. 21 22OPTIONS 23------- 24<count>:: 25 By default the command shows all refs that match 26 `<pattern>`. This option makes it stop after showing 27 that many refs. 28 29<key>:: 30 A field name to sort on. Prefix `-` to sort in 31 descending order of the value. When unspecified, 32 `refname` is used. More than one sort keys can be 33 given. 34 35<format>:: 36 A string that interpolates `%(fieldname)` from the 37 object pointed at by a ref being shown. If `fieldname` 38 is prefixed with an asterisk (`*`) and the ref points 39 at a tag object, the value for the field in the object 40 tag refers is used. When unspecified, defaults to 41 `%(refname)`. 42 43<pattern>:: 44 If given, the name of the ref is matched against this 45 using fnmatch(3). Refs that do not match the pattern 46 are not shown. 47 48--shell, --perl, --python:: 49 If given, strings that substitute `%(fieldname)` 50 placeholders are quoted as string literals suitable for 51 the specified host language. This is meant to produce 52 a scriptlet that can directly be `eval`ed. 53 54 55FIELD NAMES 56----------- 57 58Various values from structured fields in referenced objects can 59be used to interpolate into the resulting output, or as sort 60keys. 61 62For all objects, the following names can be used: 63 64refname:: 65 The name of the ref (the part after $GIT_DIR/refs/). 66 67objecttype:: 68 The type of the object (`blob`, `tree`, `commit`, `tag`). 69 70objectsize:: 71 The size of the object (the same as `git-cat-file -s` reports). 72 73objectname:: 74 The object name (aka SHA-1). 75 76In addition to the above, for commit and tag objects, the header 77field names (`tree`, `parent`, `object`, `type`, and `tag`) can 78be used to specify the value in the header field. 79 80Fields that have name-email-date tuple as its value (`author`, 81`committer`, and `tagger`) can be suffixed with `name`, `email`, 82and `date` to extract the named component. 83 84The first line of the message in a commit and tag object is 85`subject`, the remaining lines are `body`. The whole message 86is `contents`. 87 88For sorting purposes, fields with numeric values sort in numeric 89order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). 90All other fields are used to sort in their byte-value order. 91 92In any case, a field name that refers to a field inapplicable to 93the object referred by the ref does not cause an error. It 94returns an empty string instead. 95 96 97EXAMPLES 98-------- 99 100An example directly producing formatted text. Show the most recent 1013 tagged commits:: 102 103------------ 104#!/bin/sh 105 106git-for-each-ref --count=3 --sort='-*authordate' \ 107--format='From: %(*authorname) %(*authoremail) 108Subject: %(*subject) 109Date: %(*authordate) 110Ref: %(*refname) 111 112%(*body) 113' 'refs/tags' 114------------ 115 116 117A simple example showing the use of shell eval on the output, 118demonstrating the use of --shell. List the prefixes of all heads:: 119------------ 120#!/bin/sh 121 122git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \ 123while read entry 124do 125 eval "$entry" 126 echo `dirname $ref` 127done 128------------ 129 130 131A bit more elaborate report on tags, demonstrating that the format 132may be an entire script:: 133------------ 134#!/bin/sh 135 136fmt=' 137 r=%(refname) 138 t=%(*objecttype) 139 T=${r#refs/tags/} 140 141 o=%(*objectname) 142 n=%(*authorname) 143 e=%(*authoremail) 144 s=%(*subject) 145 d=%(*authordate) 146 b=%(*body) 147 148 kind=Tag 149 if test "z$t" = z 150 then 151 # could be a lightweight tag 152 t=%(objecttype) 153 kind="Lightweight tag" 154 o=%(objectname) 155 n=%(authorname) 156 e=%(authoremail) 157 s=%(subject) 158 d=%(authordate) 159 b=%(body) 160 fi 161 echo "$kind $T points at a $t object $o" 162 if test "z$t" = zcommit 163 then 164 echo "The commit was authored by $n $e 165at $d, and titled 166 167 $s 168 169Its message reads as: 170" 171 echo "$b" | sed -e "s/^/ /" 172 echo 173 fi 174' 175 176eval=`git-for-each-ref --shell --format="$fmt" \ 177 --sort='*objecttype' \ 178 --sort=-taggerdate \ 179 refs/tags` 180eval "$eval" 181------------