]>
Commit | Line | Data |
---|---|---|
9f613ddd JH |
1 | git-for-each-ref(1) |
2 | =================== | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-for-each-ref - Output information on each ref | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
97925fde | 10 | [verse] |
b1889c36 | 11 | 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] |
0adda936 | 12 | [(--sort=<key>)...] [--format=<format>] [<pattern>...] |
9f613ddd JH |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
16 | ||
17 | Iterate over all refs that match `<pattern>` and show them | |
18 | according to the given `<format>`, after sorting them according | |
d4040e0a | 19 | to the given set of `<key>`. If `<count>` is given, stop after |
23bfbb81 | 20 | showing that many refs. The interpolated values in `<format>` |
9f613ddd | 21 | can optionally be quoted as string literals in the specified |
1729fa98 | 22 | host language allowing their direct evaluation in that language. |
9f613ddd JH |
23 | |
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. | |
30 | ||
31 | <key>:: | |
32 | A field name to sort on. Prefix `-` to sort in | |
33 | descending order of the value. When unspecified, | |
c0f6dc9b LW |
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. | |
9f613ddd JH |
37 | |
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 | |
ba7545ad JN |
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). | |
9f613ddd | 49 | |
f448e24e | 50 | <pattern>...:: |
c0f6dc9b | 51 | If one or more patterns are given, only refs are shown that |
1168d402 | 52 | match against at least one pattern, either using fnmatch(3) or |
c0f6dc9b LW |
53 | literally, in the latter case matching completely or from the |
54 | beginning up to a slash. | |
9f613ddd | 55 | |
3240240f SB |
56 | --shell:: |
57 | --perl:: | |
58 | --python:: | |
59 | --tcl:: | |
9f613ddd JH |
60 | If given, strings that substitute `%(fieldname)` |
61 | placeholders are quoted as string literals suitable for | |
62 | the specified host language. This is meant to produce | |
63 | a scriptlet that can directly be `eval`ed. | |
64 | ||
65 | ||
66 | FIELD NAMES | |
67 | ----------- | |
68 | ||
69 | Various values from structured fields in referenced objects can | |
70 | be used to interpolate into the resulting output, or as sort | |
71 | keys. | |
72 | ||
73 | For all objects, the following names can be used: | |
74 | ||
75 | refname:: | |
69057cf3 | 76 | The name of the ref (the part after $GIT_DIR/). |
7d66f21a | 77 | For a non-ambiguous short name of the ref append `:short`. |
2bb98169 BW |
78 | The option core.warnAmbiguousRefs is used to select the strict |
79 | abbreviation mode. | |
9f613ddd JH |
80 | |
81 | objecttype:: | |
82 | The type of the object (`blob`, `tree`, `commit`, `tag`). | |
83 | ||
84 | objectsize:: | |
0b444cdb | 85 | The size of the object (the same as 'git cat-file -s' reports). |
9f613ddd JH |
86 | |
87 | objectname:: | |
88 | The object name (aka SHA-1). | |
67687fea | 89 | For a non-ambiguous abbreviation of the object name append `:short`. |
9f613ddd | 90 | |
8cae19d9 JK |
91 | upstream:: |
92 | The name of a local ref which can be considered ``upstream'' | |
93 | from the displayed ref. Respects `:short` in the same way as | |
94 | `refname` above. | |
95 | ||
9f613ddd JH |
96 | In addition to the above, for commit and tag objects, the header |
97 | field names (`tree`, `parent`, `object`, `type`, and `tag`) can | |
98 | be used to specify the value in the header field. | |
99 | ||
100 | Fields that have name-email-date tuple as its value (`author`, | |
101 | `committer`, and `tagger`) can be suffixed with `name`, `email`, | |
102 | and `date` to extract the named component. | |
103 | ||
e2b23972 MG |
104 | The complete message in a commit and tag object is `contents`. |
105 | Its first line is `contents:subject`, the remaining lines | |
106 | are `contents:body` and the optional GPG signature | |
107 | is `contents:signature`. | |
9f613ddd JH |
108 | |
109 | For sorting purposes, fields with numeric values sort in numeric | |
110 | order (`objectsize`, `authordate`, `committerdate`, `taggerdate`). | |
111 | All other fields are used to sort in their byte-value order. | |
112 | ||
113 | In any case, a field name that refers to a field inapplicable to | |
114 | the object referred by the ref does not cause an error. It | |
115 | returns an empty string instead. | |
116 | ||
d392e712 AP |
117 | As a special case for the date-type fields, you may specify a format for |
118 | the date by adding one of `:default`, `:relative`, `:short`, `:local`, | |
119 | `:iso8601` or `:rfc2822` to the end of the fieldname; e.g. | |
120 | `%(taggerdate:relative)`. | |
121 | ||
9f613ddd JH |
122 | |
123 | EXAMPLES | |
124 | -------- | |
125 | ||
1729fa98 | 126 | An example directly producing formatted text. Show the most recent |
22817b40 | 127 | 3 tagged commits: |
9f613ddd JH |
128 | |
129 | ------------ | |
130 | #!/bin/sh | |
131 | ||
b1889c36 | 132 | git for-each-ref --count=3 --sort='-*authordate' \ |
9f613ddd JH |
133 | --format='From: %(*authorname) %(*authoremail) |
134 | Subject: %(*subject) | |
135 | Date: %(*authordate) | |
136 | Ref: %(*refname) | |
137 | ||
138 | %(*body) | |
139 | ' 'refs/tags' | |
140 | ------------ | |
141 | ||
1729fa98 AW |
142 | |
143 | A simple example showing the use of shell eval on the output, | |
22817b40 | 144 | demonstrating the use of --shell. List the prefixes of all heads: |
1729fa98 AW |
145 | ------------ |
146 | #!/bin/sh | |
147 | ||
b1889c36 | 148 | git for-each-ref --shell --format="ref=%(refname)" refs/heads | \ |
1729fa98 AW |
149 | while read entry |
150 | do | |
151 | eval "$entry" | |
152 | echo `dirname $ref` | |
153 | done | |
154 | ------------ | |
155 | ||
156 | ||
157 | A bit more elaborate report on tags, demonstrating that the format | |
22817b40 | 158 | may be an entire script: |
9f613ddd JH |
159 | ------------ |
160 | #!/bin/sh | |
161 | ||
162 | fmt=' | |
163 | r=%(refname) | |
164 | t=%(*objecttype) | |
165 | T=${r#refs/tags/} | |
166 | ||
167 | o=%(*objectname) | |
168 | n=%(*authorname) | |
169 | e=%(*authoremail) | |
170 | s=%(*subject) | |
171 | d=%(*authordate) | |
172 | b=%(*body) | |
173 | ||
174 | kind=Tag | |
175 | if test "z$t" = z | |
176 | then | |
177 | # could be a lightweight tag | |
178 | t=%(objecttype) | |
179 | kind="Lightweight tag" | |
180 | o=%(objectname) | |
181 | n=%(authorname) | |
182 | e=%(authoremail) | |
183 | s=%(subject) | |
184 | d=%(authordate) | |
185 | b=%(body) | |
186 | fi | |
187 | echo "$kind $T points at a $t object $o" | |
188 | if test "z$t" = zcommit | |
189 | then | |
190 | echo "The commit was authored by $n $e | |
191 | at $d, and titled | |
192 | ||
193 | $s | |
194 | ||
195 | Its message reads as: | |
196 | " | |
197 | echo "$b" | sed -e "s/^/ /" | |
198 | echo | |
199 | fi | |
200 | ' | |
201 | ||
b1889c36 | 202 | eval=`git for-each-ref --shell --format="$fmt" \ |
9f613ddd JH |
203 | --sort='*objecttype' \ |
204 | --sort=-taggerdate \ | |
205 | refs/tags` | |
206 | eval "$eval" | |
207 | ------------ | |
621c39de AS |
208 | |
209 | Author | |
210 | ------ | |
211 | Written by Junio C Hamano <gitster@pobox.com>. | |
212 | ||
213 | Documentation | |
214 | ------------- | |
215 | Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>. | |
216 | ||
217 | GIT | |
218 | --- | |
219 | Part of the linkgit:git[1] suite |