1GIT-FOR-EACH-REF(1) Git Manual GIT-FOR-EACH-REF(1)
2
6 git-for-each-ref - Output information on each ref
7
9 git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
10 [(--sort=<key>)...] [--format=<format>] [<pattern>...]
11
14 Iterate over all refs that match <pattern> and show them according to
15 the given <format>, after sorting them according to the given set of
16 <key>. If <count> is given, stop after showing that many refs. The
17 interpolated values in <format> can optionally be quoted as string
18 literals in the specified host language allowing their direct
19 evaluation in that language.
20
22 <count>
23 By default the command shows all refs that match <pattern>. This
24 option makes it stop after showing that many refs.
25 <key>
27 A field name to sort on. Prefix - to sort in descending order of
28 the value. When unspecified, refname is used. You may use the
29 --sort=<key> option multiple times, in which case the last key
30 becomes the primary key.
31 <format>
33 A string that interpolates %(fieldname) from the object pointed at
34 by a ref being shown. If fieldname is prefixed with an asterisk (*)
35 and the ref points at a tag object, the value for the field in the
36 object tag refers is used. When unspecified, defaults to
37 %(objectname) SPC %(objecttype) TAB %(refname). It also
38 interpolates %% to %, and %xx where xx are hex digits interpolates
39 to character with hex code xx; for example %00 interpolates to \0
40 (NUL), %09 to \t (TAB) and %0a to \n (LF).
41 <pattern>...
43 If one or more patterns are given, only refs are shown that match
44 against at least one pattern, either using fnmatch(3) or literally,
45 in the latter case matching completely or from the beginning up to
46 a slash.
47 --shell, --perl, --python, --tcl
49 If given, strings that substitute %(fieldname) placeholders are
50 quoted as string literals suitable for the specified host language.
51 This is meant to produce a scriptlet that can directly be `eval`ed.
52
54 Various values from structured fields in referenced objects can be used
55 to interpolate into the resulting output, or as sort keys.
56 For all objects, the following names can be used:
58 refname
60 The name of the ref (the part after $GIT_DIR/). For a non-ambiguous
61 short name of the ref append :short. The option
62 core.warnAmbiguousRefs is used to select the strict abbreviation
63 mode.
64 objecttype
66 The type of the object (blob, tree, commit, tag).
67 objectsize
69 The size of the object (the same as git cat-file -s reports).
70 objectname
72 The object name (aka SHA-1). For a non-ambiguous abbreviation of
73 the object name append :short.
74 upstream
76 The name of a local ref which can be considered “upstream” from the
77 displayed ref. Respects :short in the same way as refname above.
78 In addition to the above, for commit and tag objects, the header field
80 names (tree, parent, object, type, and tag) can be used to specify the
81 value in the header field.
82 Fields that have name-email-date tuple as its value (author, committer,
84 and tagger) can be suffixed with name, email, and date to extract the
85 named component.
86 The first line of the message in a commit and tag object is subject,
88 the remaining lines are body. The whole message is contents.
89 For sorting purposes, fields with numeric values sort in numeric order
91 (objectsize, authordate, committerdate, taggerdate). All other fields
92 are used to sort in their byte-value order.
93 In any case, a field name that refers to a field inapplicable to the
95 object referred by the ref does not cause an error. It returns an empty
96 string instead.
97 As a special case for the date-type fields, you may specify a format
99 for the date by adding one of :default, :relative, :short, :local,
100 :iso8601 or :rfc2822 to the end of the fieldname; e.g.
101 %(taggerdate:relative).
102
104 An example directly producing formatted text. Show the most recent 3
105 tagged commits:
106 #!/bin/sh
108 git for-each-ref --count=3 --sort='-*authordate' \
110 --format='From: %(*authorname) %(*authoremail)
111 Subject: %(*subject)
112 Date: %(*authordate)
113 Ref: %(*refname)
114 %(*body)
116 ' 'refs/tags'
117 A simple example showing the use of shell eval on the output,
120 demonstrating the use of --shell. List the prefixes of all heads:
121 #!/bin/sh
123 git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
125 while read entry
126 do
127 eval "$entry"
128 echo `dirname $ref`
129 done
130 A bit more elaborate report on tags, demonstrating that the format may
133 be an entire script:
134 #!/bin/sh
136 fmt='
138 r=%(refname)
139 t=%(*objecttype)
140 T=${r#refs/tags/}
141 o=%(*objectname)
143 n=%(*authorname)
144 e=%(*authoremail)
145 s=%(*subject)
146 d=%(*authordate)
147 b=%(*body)
148 kind=Tag
150 if test "z$t" = z
151 then
152 # could be a lightweight tag
153 t=%(objecttype)
154 kind="Lightweight tag"
155 o=%(objectname)
156 n=%(authorname)
157 e=%(authoremail)
158 s=%(subject)
159 d=%(authordate)
160 b=%(body)
161 fi
162 echo "$kind $T points at a $t object $o"
163 if test "z$t" = zcommit
164 then
165 echo "The commit was authored by $n $e
166 at $d, and titled
167 $s
169 Its message reads as:
171 "
172 echo "$b" | sed -e "s/^/ /"
173 echo
174 fi
175 '
176 eval=`git for-each-ref --shell --format="$fmt" \
178 --sort='*objecttype' \
179 --sort=-taggerdate \
180 refs/tags`
181 eval "$eval"
182
185 Written by Junio C Hamano <gitster@pobox.com[1]>.
186
188 Documentation by Junio C Hamano and the git-list
189 <git@vger.kernel.org[2]>.
190
192 Part of the git(1) suite
193
195 1. gitster@pobox.com
196 mailto:gitster@pobox.com
197 2. git@vger.kernel.org
199 mailto:git@vger.kernel.org
200Git 1.7.4.4 04/11/2011 GIT-FOR-EACH-REF(1)