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