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>]: Respect any colors specified in the --format option.
53 The <when> field must be one of always, never, or auto (if <when> is
54 absent, behave as if always was given).
55 --shell, --perl, --python, --tcl
57 If given, strings that substitute %(fieldname) placeholders are
58 quoted as string literals suitable for the specified host language.
59 This is meant to produce a scriptlet that can directly be `eval`ed.
60 --points-at=<object>
62 Only list refs which points at the given object.
63 --merged[=<object>]
65 Only list refs whose tips are reachable from the specified commit
66 (HEAD if not specified), incompatible with --no-merged.
67 --no-merged[=<object>]
69 Only list refs whose tips are not reachable from the specified
70 commit (HEAD if not specified), incompatible with --merged.
71 --contains[=<object>]
73 Only list refs which contain the specified commit (HEAD if not
74 specified).
75 --no-contains[=<object>]
77 Only list refs which don’t contain the specified commit (HEAD if
78 not specified).
79 --ignore-case
81 Sorting and filtering refs are case insensitive.
82
84 Various values from structured fields in referenced objects can be used
85 to interpolate into the resulting output, or as sort keys.
86 For all objects, the following names can be used:
88 refname
90 The name of the ref (the part after $GIT_DIR/). For a non-ambiguous
91 short name of the ref append :short. The option
92 core.warnAmbiguousRefs is used to select the strict abbreviation
93 mode. If lstrip=<N> (rstrip=<N>) is appended, strips <N>
94 slash-separated path components from the front (back) of the
95 refname (e.g. %(refname:lstrip=2) turns refs/tags/foo into foo and
96 %(refname:rstrip=2) turns refs/tags/foo into refs). If <N> is a
97 negative number, strip as many path components as necessary from
98 the specified end to leave -<N> path components (e.g.
99 %(refname:lstrip=-2) turns refs/tags/foo into tags/foo and
100 %(refname:rstrip=-1) turns refs/tags/foo into refs). When the ref
101 does not have enough components, the result becomes an empty string
102 if stripping with positive <N>, or it becomes the full refname if
103 stripping with negative <N>. Neither is an error.
104 strip can be used as a synonym to lstrip.
106 objecttype
108 The type of the object (blob, tree, commit, tag).
109 objectsize
111 The size of the object (the same as git cat-file -s reports).
112 objectname
114 The object name (aka SHA-1). For a non-ambiguous abbreviation of
115 the object name append :short. For an abbreviation of the object
116 name with desired length append :short=<length>, where the minimum
117 length is MINIMUM_ABBREV. The length may be exceeded to ensure
118 unique object names.
119 upstream
121 The name of a local ref which can be considered “upstream” from the
122 displayed ref. Respects :short, :lstrip and :rstrip in the same way
123 as refname above. Additionally respects :track to show "[ahead N,
124 behind M]" and :trackshort to show the terse version: ">" (ahead),
125 "<" (behind), "<>" (ahead and behind), or "=" (in sync). :track
126 also prints "[gone]" whenever unknown upstream ref is encountered.
127 Append :track,nobracket to show tracking information without
128 brackets (i.e "ahead N, behind M").
129 For any remote-tracking branch %(upstream), %(upstream:remotename)
131 and %(upstream:remoteref) refer to the name of the remote and the
132 name of the tracked remote ref, respectively. In other words, the
133 remote-tracking branch can be updated explicitly and individually
134 by using the refspec %(upstream:remoteref):%(upstream) to fetch
135 from %(upstream:remotename).
136 Has no effect if the ref does not have tracking information
138 associated with it. All the options apart from nobracket are
139 mutually exclusive, but if used together the last option is
140 selected.
141 push
143 The name of a local ref which represents the @{push} location for
144 the displayed ref. Respects :short, :lstrip, :rstrip, :track,
145 :trackshort, :remotename, and :remoteref options as upstream does.
146 Produces an empty string if no @{push} ref is configured.
147 HEAD
149 * if HEAD matches current ref (the checked out branch), ' '
150 otherwise.
151 color
153 Change output color. Followed by :<colorname>, where color names
154 are described under Values in the "CONFIGURATION FILE" section of
155 git-config(1). For example, %(color:bold red).
156 align
158 Left-, middle-, or right-align the content between %(align:...) and
159 %(end). The "align:" is followed by width=<width> and
160 position=<position> in any order separated by a comma, where the
161 <position> is either left, right or middle, default being left and
162 <width> is the total length of the content with alignment. For
163 brevity, the "width=" and/or "position=" prefixes may be omitted,
164 and bare <width> and <position> used instead. For instance,
165 %(align:<width>,<position>). If the contents length is more than
166 the width then no alignment is performed. If used with --quote
167 everything in between %(align:...) and %(end) is quoted, but if
168 nested then only the topmost level performs quoting.
169 if
171 Used as %(if)...%(then)...%(end) or
172 %(if)...%(then)...%(else)...%(end). If there is an atom with value
173 or string literal after the %(if) then everything after the %(then)
174 is printed, else if the %(else) atom is used, then everything after
175 %(else) is printed. We ignore space when evaluating the string
176 before %(then), this is useful when we use the %(HEAD) atom which
177 prints either "*" or " " and we want to apply the if condition only
178 on the HEAD ref. Append ":equals=<string>" or ":notequals=<string>"
179 to compare the value between the %(if:...) and %(then) atoms with
180 the given string.
181 symref
183 The ref which the given symbolic ref refers to. If not a symbolic
184 ref, nothing is printed. Respects the :short, :lstrip and :rstrip
185 options in the same way as refname above.
186 In addition to the above, for commit and tag objects, the header field
188 names (tree, parent, object, type, and tag) can be used to specify the
189 value in the header field.
190 For commit and tag objects, the special creatordate and creator fields
192 will correspond to the appropriate date or name-email-date tuple from
193 the committer or tagger fields depending on the object type. These are
194 intended for working on a mix of annotated and lightweight tags.
195 Fields that have name-email-date tuple as its value (author, committer,
197 and tagger) can be suffixed with name, email, and date to extract the
198 named component.
199 The complete message in a commit and tag object is contents. Its first
201 line is contents:subject, where subject is the concatenation of all
202 lines of the commit message up to the first blank line. The next line
203 is contents:body, where body is all of the lines after the first blank
204 line. The optional GPG signature is contents:signature. The first N
205 lines of the message is obtained using contents:lines=N. Additionally,
206 the trailers as interpreted by git-interpret-trailers(1) are obtained
207 as trailers (or by using the historical alias contents:trailers).
208 Non-trailer lines from the trailer block can be omitted with
209 trailers:only. Whitespace-continuations can be removed from trailers so
210 that each trailer appears on a line by itself with its full content
211 with trailers:unfold. Both can be used together as
212 trailers:unfold,only.
213 For sorting purposes, fields with numeric values sort in numeric order
215 (objectsize, authordate, committerdate, creatordate, taggerdate). All
216 other fields are used to sort in their byte-value order.
217 There is also an option to sort by versions, this can be done by using
219 the fieldname version:refname or its alias v:refname.
220 In any case, a field name that refers to a field inapplicable to the
222 object referred by the ref does not cause an error. It returns an empty
223 string instead.
224 As a special case for the date-type fields, you may specify a format
226 for the date by adding : followed by date format name (see the values
227 the --date option to git-rev-list(1) takes).
228 Some atoms like %(align) and %(if) always require a matching %(end). We
230 call them "opening atoms" and sometimes denote them as %($open).
231 When a scripting language specific quoting is in effect, everything
233 between a top-level opening atom and its matching %(end) is evaluated
234 according to the semantics of the opening atom and only its result from
235 the top-level is quoted.
236
238 An example directly producing formatted text. Show the most recent 3
239 tagged commits:
240 #!/bin/sh
242 git for-each-ref --count=3 --sort='-*authordate' \
244 --format='From: %(*authorname) %(*authoremail)
245 Subject: %(*subject)
246 Date: %(*authordate)
247 Ref: %(*refname)
248 %(*body)
250 ' 'refs/tags'
251 A simple example showing the use of shell eval on the output,
254 demonstrating the use of --shell. List the prefixes of all heads:
255 #!/bin/sh
257 git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
259 while read entry
260 do
261 eval "$entry"
262 echo `dirname $ref`
263 done
264 A bit more elaborate report on tags, demonstrating that the format may
267 be an entire script:
268 #!/bin/sh
270 fmt='
272 r=%(refname)
273 t=%(*objecttype)
274 T=${r#refs/tags/}
275 o=%(*objectname)
277 n=%(*authorname)
278 e=%(*authoremail)
279 s=%(*subject)
280 d=%(*authordate)
281 b=%(*body)
282 kind=Tag
284 if test "z$t" = z
285 then
286 # could be a lightweight tag
287 t=%(objecttype)
288 kind="Lightweight tag"
289 o=%(objectname)
290 n=%(authorname)
291 e=%(authoremail)
292 s=%(subject)
293 d=%(authordate)
294 b=%(body)
295 fi
296 echo "$kind $T points at a $t object $o"
297 if test "z$t" = zcommit
298 then
299 echo "The commit was authored by $n $e
300 at $d, and titled
301 $s
303 Its message reads as:
305 "
306 echo "$b" | sed -e "s/^/ /"
307 echo
308 fi
309 '
310 eval=`git for-each-ref --shell --format="$fmt" \
312 --sort='*objecttype' \
313 --sort=-taggerdate \
314 refs/tags`
315 eval "$eval"
316 An example to show the usage of %(if)...%(then)...%(else)...%(end).
319 This prefixes the current branch with a star.
320 git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/
322 An example to show the usage of %(if)...%(then)...%(end). This prints
325 the authorname, if present.
326 git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
328
331 git-show-ref(1)
332
334 Part of the git(1) suite
335Git 2.18.1 05/14/2019 GIT-FOR-EACH-REF(1)