6325ff9a68b336efd818a9593cb47dd3f189b6ff
1 git-for-each-ref(1)
2 ===================
4 NAME
5 ----
6 git-for-each-ref - Output information on each ref
8 SYNOPSIS
9 --------
10 [verse]
11 'git-for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl]
12 [--sort=<key>]\* [--format=<format>] [<pattern>...]
14 DESCRIPTION
15 -----------
17 Iterate over all refs that match `<pattern>` and show them
18 according to the given `<format>`, after sorting them according
19 to the given set of `<key>`. If `<max>` is given, stop after
20 showing that many refs. The interpolated values in `<format>`
21 can optionally be quoted as string literals in the specified
22 host language allowing their direct evaluation in that language.
24 OPTIONS
25 -------
26 <count>::
27 By default the command shows all refs that match
28 `<pattern>`. This option makes it stop after showing
29 that many refs.
31 <key>::
32 A field name to sort on. Prefix `-` to sort in
33 descending order of the value. When unspecified,
34 `refname` is used. You may use the --sort=<key> option
35 multiple times, in which case the last key becomes the primary
36 key.
38 <format>::
39 A string that interpolates `%(fieldname)` from the
40 object pointed at by a ref being shown. If `fieldname`
41 is prefixed with an asterisk (`*`) and the ref points
42 at a tag object, the value for the field in the object
43 tag refers is used. When unspecified, defaults to
44 `%(objectname) SPC %(objecttype) TAB %(refname)`.
45 It also interpolates `%%` to `%`, and `%xx` where `xx`
46 are hex digits interpolates to character with hex code
47 `xx`; for example `%00` interpolates to `\0` (NUL),
48 `%09` to `\t` (TAB) and `%0a` to `\n` (LF).
50 <pattern>::
51 If one or more patterns are given, only refs are shown that
52 match againt at least one pattern, either using fnmatch(3) or
53 literally, in the latter case matching completely or from the
54 beginning up to a slash.
56 --shell, --perl, --python, --tcl::
57 If given, strings that substitute `%(fieldname)`
58 placeholders are quoted as string literals suitable for
59 the specified host language. This is meant to produce
60 a scriptlet that can directly be `eval`ed.
63 FIELD NAMES
64 -----------
66 Various values from structured fields in referenced objects can
67 be used to interpolate into the resulting output, or as sort
68 keys.
70 For all objects, the following names can be used:
72 refname::
73 The name of the ref (the part after $GIT_DIR/).
75 objecttype::
76 The type of the object (`blob`, `tree`, `commit`, `tag`).
78 objectsize::
79 The size of the object (the same as `git-cat-file -s` reports).
81 objectname::
82 The object name (aka SHA-1).
84 In addition to the above, for commit and tag objects, the header
85 field names (`tree`, `parent`, `object`, `type`, and `tag`) can
86 be used to specify the value in the header field.
88 Fields that have name-email-date tuple as its value (`author`,
89 `committer`, and `tagger`) can be suffixed with `name`, `email`,
90 and `date` to extract the named component.
92 The first line of the message in a commit and tag object is
93 `subject`, the remaining lines are `body`. The whole message
94 is `contents`.
96 For sorting purposes, fields with numeric values sort in numeric
97 order (`objectsize`, `authordate`, `committerdate`, `taggerdate`).
98 All other fields are used to sort in their byte-value order.
100 In any case, a field name that refers to a field inapplicable to
101 the object referred by the ref does not cause an error. It
102 returns an empty string instead.
104 As a special case for the date-type fields, you may specify a format for
105 the date by adding one of `:default`, `:relative`, `:short`, `:local`,
106 `:iso8601` or `:rfc2822` to the end of the fieldname; e.g.
107 `%(taggerdate:relative)`.
110 EXAMPLES
111 --------
113 An example directly producing formatted text. Show the most recent
114 3 tagged commits::
116 ------------
117 #!/bin/sh
119 git-for-each-ref --count=3 --sort='-*authordate' \
120 --format='From: %(*authorname) %(*authoremail)
121 Subject: %(*subject)
122 Date: %(*authordate)
123 Ref: %(*refname)
125 %(*body)
126 ' 'refs/tags'
127 ------------
130 A simple example showing the use of shell eval on the output,
131 demonstrating the use of --shell. List the prefixes of all heads::
132 ------------
133 #!/bin/sh
135 git-for-each-ref --shell --format="ref=%(refname)" refs/heads | \
136 while read entry
137 do
138 eval "$entry"
139 echo `dirname $ref`
140 done
141 ------------
144 A bit more elaborate report on tags, demonstrating that the format
145 may be an entire script::
146 ------------
147 #!/bin/sh
149 fmt='
150 r=%(refname)
151 t=%(*objecttype)
152 T=${r#refs/tags/}
154 o=%(*objectname)
155 n=%(*authorname)
156 e=%(*authoremail)
157 s=%(*subject)
158 d=%(*authordate)
159 b=%(*body)
161 kind=Tag
162 if test "z$t" = z
163 then
164 # could be a lightweight tag
165 t=%(objecttype)
166 kind="Lightweight tag"
167 o=%(objectname)
168 n=%(authorname)
169 e=%(authoremail)
170 s=%(subject)
171 d=%(authordate)
172 b=%(body)
173 fi
174 echo "$kind $T points at a $t object $o"
175 if test "z$t" = zcommit
176 then
177 echo "The commit was authored by $n $e
178 at $d, and titled
180 $s
182 Its message reads as:
183 "
184 echo "$b" | sed -e "s/^/ /"
185 echo
186 fi
187 '
189 eval=`git-for-each-ref --shell --format="$fmt" \
190 --sort='*objecttype' \
191 --sort=-taggerdate \
192 refs/tags`
193 eval "$eval"
194 ------------