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 worktreepath
197 The absolute path to the worktree in which the ref is checked out,
198 if it is checked out in any linked worktree. Empty string
199 otherwise.
200 In addition to the above, for commit and tag objects, the header field
202 names (tree, parent, object, type, and tag) can be used to specify the
203 value in the header field.
204 For commit and tag objects, the special creatordate and creator fields
206 will correspond to the appropriate date or name-email-date tuple from
207 the committer or tagger fields depending on the object type. These are
208 intended for working on a mix of annotated and lightweight tags.
209 Fields that have name-email-date tuple as its value (author, committer,
211 and tagger) can be suffixed with name, email, and date to extract the
212 named component.
213 The complete message in a commit and tag object is contents. Its first
215 line is contents:subject, where subject is the concatenation of all
216 lines of the commit message up to the first blank line. The next line
217 is contents:body, where body is all of the lines after the first blank
218 line. The optional GPG signature is contents:signature. The first N
219 lines of the message is obtained using contents:lines=N. Additionally,
220 the trailers as interpreted by git-interpret-trailers(1) are obtained
221 as trailers (or by using the historical alias contents:trailers).
222 Non-trailer lines from the trailer block can be omitted with
223 trailers:only. Whitespace-continuations can be removed from trailers so
224 that each trailer appears on a line by itself with its full content
225 with trailers:unfold. Both can be used together as
226 trailers:unfold,only.
227 For sorting purposes, fields with numeric values sort in numeric order
229 (objectsize, authordate, committerdate, creatordate, taggerdate). All
230 other fields are used to sort in their byte-value order.
231 There is also an option to sort by versions, this can be done by using
233 the fieldname version:refname or its alias v:refname.
234 In any case, a field name that refers to a field inapplicable to the
236 object referred by the ref does not cause an error. It returns an empty
237 string instead.
238 As a special case for the date-type fields, you may specify a format
240 for the date by adding : followed by date format name (see the values
241 the --date option to git-rev-list(1) takes).
242 Some atoms like %(align) and %(if) always require a matching %(end). We
244 call them "opening atoms" and sometimes denote them as %($open).
245 When a scripting language specific quoting is in effect, everything
247 between a top-level opening atom and its matching %(end) is evaluated
248 according to the semantics of the opening atom and only its result from
249 the top-level is quoted.
250
252 An example directly producing formatted text. Show the most recent 3
253 tagged commits:
254 #!/bin/sh
256 git for-each-ref --count=3 --sort='-*authordate' \
258 --format='From: %(*authorname) %(*authoremail)
259 Subject: %(*subject)
260 Date: %(*authordate)
261 Ref: %(*refname)
262 %(*body)
264 ' 'refs/tags'
265 A simple example showing the use of shell eval on the output,
268 demonstrating the use of --shell. List the prefixes of all heads:
269 #!/bin/sh
271 git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
273 while read entry
274 do
275 eval "$entry"
276 echo `dirname $ref`
277 done
278 A bit more elaborate report on tags, demonstrating that the format may
281 be an entire script:
282 #!/bin/sh
284 fmt='
286 r=%(refname)
287 t=%(*objecttype)
288 T=${r#refs/tags/}
289 o=%(*objectname)
291 n=%(*authorname)
292 e=%(*authoremail)
293 s=%(*subject)
294 d=%(*authordate)
295 b=%(*body)
296 kind=Tag
298 if test "z$t" = z
299 then
300 # could be a lightweight tag
301 t=%(objecttype)
302 kind="Lightweight tag"
303 o=%(objectname)
304 n=%(authorname)
305 e=%(authoremail)
306 s=%(subject)
307 d=%(authordate)
308 b=%(body)
309 fi
310 echo "$kind $T points at a $t object $o"
311 if test "z$t" = zcommit
312 then
313 echo "The commit was authored by $n $e
314 at $d, and titled
315 $s
317 Its message reads as:
319 "
320 echo "$b" | sed -e "s/^/ /"
321 echo
322 fi
323 '
324 eval=`git for-each-ref --shell --format="$fmt" \
326 --sort='*objecttype' \
327 --sort=-taggerdate \
328 refs/tags`
329 eval "$eval"
330 An example to show the usage of %(if)...%(then)...%(else)...%(end).
333 This prefixes the current branch with a star.
334 git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/
336 An example to show the usage of %(if)...%(then)...%(end). This prints
339 the authorname, if present.
340 git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
342
345 Note that the sizes of objects on disk are reported accurately, but
346 care should be taken in drawing conclusions about which refs or objects
347 are responsible for disk usage. The size of a packed non-delta object
348 may be much larger than the size of objects which delta against it, but
349 the choice of which object is the base and which is the delta is
350 arbitrary and is subject to change during a repack.
351 Note also that multiple copies of an object may be present in the
353 object database; in this case, it is undefined which copy’s size or
354 delta base will be reported.
355
357 git-show-ref(1)
358
360 Part of the git(1) suite
361Git 2.24.1 12/10/2019 GIT-FOR-EACH-REF(1)