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).
73 upstream
75 The name of a local ref which can be considered “upstream” from the
76 displayed ref. Respects :short in the same way as refname above.
77 In addition to the above, for commit and tag objects, the header field
79 names (tree, parent, object, type, and tag) can be used to specify the
80 value in the header field.
81 Fields that have name-email-date tuple as its value (author, committer,
83 and tagger) can be suffixed with name, email, and date to extract the
84 named component.
85 The first line of the message in a commit and tag object is subject,
87 the remaining lines are body. The whole message is contents.
88 For sorting purposes, fields with numeric values sort in numeric order
90 (objectsize, authordate, committerdate, taggerdate). All other fields
91 are used to sort in their byte-value order.
92 In any case, a field name that refers to a field inapplicable to the
94 object referred by the ref does not cause an error. It returns an empty
95 string instead.
96 As a special case for the date-type fields, you may specify a format
98 for the date by adding one of :default, :relative, :short, :local,
99 :iso8601 or :rfc2822 to the end of the fieldname; e.g.
100 %(taggerdate:relative).
101
103 An example directly producing formatted text. Show the most recent 3
104 tagged commits::
105 #!/bin/sh
107 git for-each-ref --count=3 --sort=´-*authordate´ \
109 --format=´From: %(*authorname) %(*authoremail)
110 Subject: %(*subject)
111 Date: %(*authordate)
112 Ref: %(*refname)
113 %(*body)
115 ´ ´refs/tags´
116 A simple example showing the use of shell eval on the output,
119 demonstrating the use of --shell. List the prefixes of all heads::
120 #!/bin/sh
122 git for-each-ref --shell --format="ref=%(refname)" refs/heads | \
124 while read entry
125 do
126 eval "$entry"
127 echo `dirname $ref`
128 done
129 A bit more elaborate report on tags, demonstrating that the format may
132 be an entire script::
133 #!/bin/sh
135 fmt=´
137 r=%(refname)
138 t=%(*objecttype)
139 T=${r#refs/tags/}
140 o=%(*objectname)
142 n=%(*authorname)
143 e=%(*authoremail)
144 s=%(*subject)
145 d=%(*authordate)
146 b=%(*body)
147 kind=Tag
149 if test "z$t" = z
150 then
151 # could be a lightweight tag
152 t=%(objecttype)
153 kind="Lightweight tag"
154 o=%(objectname)
155 n=%(authorname)
156 e=%(authoremail)
157 s=%(subject)
158 d=%(authordate)
159 b=%(body)
160 fi
161 echo "$kind $T points at a $t object $o"
162 if test "z$t" = zcommit
163 then
164 echo "The commit was authored by $n $e
165 at $d, and titled
166 $s
168 Its message reads as:
170 "
171 echo "$b" | sed -e "s/^/ /"
172 echo
173 fi
174 ´
175 eval=`git for-each-ref --shell --format="$fmt" \
177 --sort=´*objecttype´ \
178 --sort=-taggerdate \
179 refs/tags`
180 eval "$eval"
181Git 1.7.1 08/16/2017 GIT-FOR-EACH-REF(1)