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 complete message in a commit and tag object is contents. Its first
88 line is contents:subject, where subject is the concatenation of all
89 lines of the commit message up to the first blank line. The next line
90 is contents:body, where body is all of the lines after the first blank
91 line. Finally, the optional GPG signature is contents:signature.
92 For sorting purposes, fields with numeric values sort in numeric order
94 (objectsize, authordate, committerdate, taggerdate). All other fields
95 are used to sort in their byte-value order.
96 In any case, a field name that refers to a field inapplicable to the
98 object referred by the ref does not cause an error. It returns an empty
99 string instead.
100 As a special case for the date-type fields, you may specify a format
102 for the date by adding one of :default, :relative, :short, :local,
103 :iso8601, :rfc2822 or :raw to the end of the fieldname; e.g.
104 %(taggerdate:relative).
105
107 An example directly producing formatted text. Show the most recent 3
108 tagged commits:
109 #!/bin/sh
111 git for-each-ref --count=3 --sort='-*authordate' \
113 --format='From: %(*authorname) %(*authoremail)
114 Subject: %(*subject)
115 Date: %(*authordate)
116 Ref: %(*refname)
117 %(*body)
119 ' 'refs/tags'
120 A simple example showing the use of shell eval on the output,
123 demonstrating the use of --shell. List the prefixes of all heads:
124 #!/bin/sh
126 git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
128 while read entry
129 do
130 eval "$entry"
131 echo `dirname $ref`
132 done
133 A bit more elaborate report on tags, demonstrating that the format may
136 be an entire script:
137 #!/bin/sh
139 fmt='
141 r=%(refname)
142 t=%(*objecttype)
143 T=${r#refs/tags/}
144 o=%(*objectname)
146 n=%(*authorname)
147 e=%(*authoremail)
148 s=%(*subject)
149 d=%(*authordate)
150 b=%(*body)
151 kind=Tag
153 if test "z$t" = z
154 then
155 # could be a lightweight tag
156 t=%(objecttype)
157 kind="Lightweight tag"
158 o=%(objectname)
159 n=%(authorname)
160 e=%(authoremail)
161 s=%(subject)
162 d=%(authordate)
163 b=%(body)
164 fi
165 echo "$kind $T points at a $t object $o"
166 if test "z$t" = zcommit
167 then
168 echo "The commit was authored by $n $e
169 at $d, and titled
170 $s
172 Its message reads as:
174 "
175 echo "$b" | sed -e "s/^/ /"
176 echo
177 fi
178 '
179 eval=`git for-each-ref --shell --format="$fmt" \
181 --sort='*objecttype' \
182 --sort=-taggerdate \
183 refs/tags`
184 eval "$eval"
185
188 Written by Junio C Hamano <gitster@pobox.com[1]>.
189
191 Documentation by Junio C Hamano and the git-list
192 <git@vger.kernel.org[2]>.
193
195 Part of the git(1) suite
196
198 1. gitster@pobox.com
199 mailto:gitster@pobox.com
200 2. git@vger.kernel.org
202 mailto:git@vger.kernel.org
203Git 1.8.3.1 11/19/2018 GIT-FOR-EACH-REF(1)