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 objectname
115 The object name (aka SHA-1). For a non-ambiguous abbreviation of
116 the object name append :short. For an abbreviation of the object
117 name with desired length append :short=<length>, where the minimum
118 length is MINIMUM_ABBREV. The length may be exceeded to ensure
119 unique object names.
120 upstream
122 The name of a local ref which can be considered “upstream” from the
123 displayed ref. Respects :short, :lstrip and :rstrip in the same way
124 as refname above. Additionally respects :track to show "[ahead N,
125 behind M]" and :trackshort to show the terse version: ">" (ahead),
126 "<" (behind), "<>" (ahead and behind), or "=" (in sync). :track
127 also prints "[gone]" whenever unknown upstream ref is encountered.
128 Append :track,nobracket to show tracking information without
129 brackets (i.e "ahead N, behind M").
130 For any remote-tracking branch %(upstream), %(upstream:remotename)
132 and %(upstream:remoteref) refer to the name of the remote and the
133 name of the tracked remote ref, respectively. In other words, the
134 remote-tracking branch can be updated explicitly and individually
135 by using the refspec %(upstream:remoteref):%(upstream) to fetch
136 from %(upstream:remotename).
137 Has no effect if the ref does not have tracking information
139 associated with it. All the options apart from nobracket are
140 mutually exclusive, but if used together the last option is
141 selected.
142 push
144 The name of a local ref which represents the @{push} location for
145 the displayed ref. Respects :short, :lstrip, :rstrip, :track,
146 :trackshort, :remotename, and :remoteref options as upstream does.
147 Produces an empty string if no @{push} ref is configured.
148 HEAD
150 * if HEAD matches current ref (the checked out branch), ' '
151 otherwise.
152 color
154 Change output color. Followed by :<colorname>, where color names
155 are described under Values in the "CONFIGURATION FILE" section of
156 git-config(1). For example, %(color:bold red).
157 align
159 Left-, middle-, or right-align the content between %(align:...) and
160 %(end). The "align:" is followed by width=<width> and
161 position=<position> in any order separated by a comma, where the
162 <position> is either left, right or middle, default being left and
163 <width> is the total length of the content with alignment. For
164 brevity, the "width=" and/or "position=" prefixes may be omitted,
165 and bare <width> and <position> used instead. For instance,
166 %(align:<width>,<position>). If the contents length is more than
167 the width then no alignment is performed. If used with --quote
168 everything in between %(align:...) and %(end) is quoted, but if
169 nested then only the topmost level performs quoting.
170 if
172 Used as %(if)...%(then)...%(end) or
173 %(if)...%(then)...%(else)...%(end). If there is an atom with value
174 or string literal after the %(if) then everything after the %(then)
175 is printed, else if the %(else) atom is used, then everything after
176 %(else) is printed. We ignore space when evaluating the string
177 before %(then), this is useful when we use the %(HEAD) atom which
178 prints either "*" or " " and we want to apply the if condition only
179 on the HEAD ref. Append ":equals=<string>" or ":notequals=<string>"
180 to compare the value between the %(if:...) and %(then) atoms with
181 the given string.
182 symref
184 The ref which the given symbolic ref refers to. If not a symbolic
185 ref, nothing is printed. Respects the :short, :lstrip and :rstrip
186 options in the same way as refname above.
187 In addition to the above, for commit and tag objects, the header field
189 names (tree, parent, object, type, and tag) can be used to specify the
190 value in the header field.
191 For commit and tag objects, the special creatordate and creator fields
193 will correspond to the appropriate date or name-email-date tuple from
194 the committer or tagger fields depending on the object type. These are
195 intended for working on a mix of annotated and lightweight tags.
196 Fields that have name-email-date tuple as its value (author, committer,
198 and tagger) can be suffixed with name, email, and date to extract the
199 named component.
200 The complete message in a commit and tag object is contents. Its first
202 line is contents:subject, where subject is the concatenation of all
203 lines of the commit message up to the first blank line. The next line
204 is contents:body, where body is all of the lines after the first blank
205 line. The optional GPG signature is contents:signature. The first N
206 lines of the message is obtained using contents:lines=N. Additionally,
207 the trailers as interpreted by git-interpret-trailers(1) are obtained
208 as trailers (or by using the historical alias contents:trailers).
209 Non-trailer lines from the trailer block can be omitted with
210 trailers:only. Whitespace-continuations can be removed from trailers so
211 that each trailer appears on a line by itself with its full content
212 with trailers:unfold. Both can be used together as
213 trailers:unfold,only.
214 For sorting purposes, fields with numeric values sort in numeric order
216 (objectsize, authordate, committerdate, creatordate, taggerdate). All
217 other fields are used to sort in their byte-value order.
218 There is also an option to sort by versions, this can be done by using
220 the fieldname version:refname or its alias v:refname.
221 In any case, a field name that refers to a field inapplicable to the
223 object referred by the ref does not cause an error. It returns an empty
224 string instead.
225 As a special case for the date-type fields, you may specify a format
227 for the date by adding : followed by date format name (see the values
228 the --date option to git-rev-list(1) takes).
229 Some atoms like %(align) and %(if) always require a matching %(end). We
231 call them "opening atoms" and sometimes denote them as %($open).
232 When a scripting language specific quoting is in effect, everything
234 between a top-level opening atom and its matching %(end) is evaluated
235 according to the semantics of the opening atom and only its result from
236 the top-level is quoted.
237
239 An example directly producing formatted text. Show the most recent 3
240 tagged commits:
241 #!/bin/sh
243 git for-each-ref --count=3 --sort='-*authordate' \
245 --format='From: %(*authorname) %(*authoremail)
246 Subject: %(*subject)
247 Date: %(*authordate)
248 Ref: %(*refname)
249 %(*body)
251 ' 'refs/tags'
252 A simple example showing the use of shell eval on the output,
255 demonstrating the use of --shell. List the prefixes of all heads:
256 #!/bin/sh
258 git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
260 while read entry
261 do
262 eval "$entry"
263 echo `dirname $ref`
264 done
265 A bit more elaborate report on tags, demonstrating that the format may
268 be an entire script:
269 #!/bin/sh
271 fmt='
273 r=%(refname)
274 t=%(*objecttype)
275 T=${r#refs/tags/}
276 o=%(*objectname)
278 n=%(*authorname)
279 e=%(*authoremail)
280 s=%(*subject)
281 d=%(*authordate)
282 b=%(*body)
283 kind=Tag
285 if test "z$t" = z
286 then
287 # could be a lightweight tag
288 t=%(objecttype)
289 kind="Lightweight tag"
290 o=%(objectname)
291 n=%(authorname)
292 e=%(authoremail)
293 s=%(subject)
294 d=%(authordate)
295 b=%(body)
296 fi
297 echo "$kind $T points at a $t object $o"
298 if test "z$t" = zcommit
299 then
300 echo "The commit was authored by $n $e
301 at $d, and titled
302 $s
304 Its message reads as:
306 "
307 echo "$b" | sed -e "s/^/ /"
308 echo
309 fi
310 '
311 eval=`git for-each-ref --shell --format="$fmt" \
313 --sort='*objecttype' \
314 --sort=-taggerdate \
315 refs/tags`
316 eval "$eval"
317 An example to show the usage of %(if)...%(then)...%(else)...%(end).
320 This prefixes the current branch with a star.
321 git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/
323 An example to show the usage of %(if)...%(then)...%(end). This prints
326 the authorname, if present.
327 git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
329
332 git-show-ref(1)
333
335 Part of the git(1) suite
336Git 2.20.1 12/15/2018 GIT-FOR-EACH-REF(1)