]>
Commit | Line | Data |
---|---|---|
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 | -------- | |
10 | [verse] | |
11 | 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] | |
12 | [(--sort=<key>)...] [--format=<format>] [<pattern>...] | |
13 | [--points-at=<object>] | |
14 | (--merged[=<object>] | --no-merged[=<object>]) | |
15 | [--contains[=<object>]] [--no-contains[=<object>]] | |
16 | ||
17 | DESCRIPTION | |
18 | ----------- | |
19 | ||
20 | Iterate over all refs that match `<pattern>` and show them | |
21 | according to the given `<format>`, after sorting them according | |
22 | to the given set of `<key>`. If `<count>` is given, stop after | |
23 | showing that many refs. The interpolated values in `<format>` | |
24 | can optionally be quoted as string literals in the specified | |
25 | host language allowing their direct evaluation in that language. | |
26 | ||
27 | OPTIONS | |
28 | ------- | |
29 | <pattern>...:: | |
30 | If one or more patterns are given, only refs are shown that | |
31 | match against at least one pattern, either using fnmatch(3) or | |
32 | literally, in the latter case matching completely or from the | |
33 | beginning up to a slash. | |
34 | ||
35 | --count=<count>:: | |
36 | By default the command shows all refs that match | |
37 | `<pattern>`. This option makes it stop after showing | |
38 | that many refs. | |
39 | ||
40 | --sort=<key>:: | |
41 | A field name to sort on. Prefix `-` to sort in | |
42 | descending order of the value. When unspecified, | |
43 | `refname` is used. You may use the --sort=<key> option | |
44 | multiple times, in which case the last key becomes the primary | |
45 | key. | |
46 | ||
47 | --format=<format>:: | |
48 | A string that interpolates `%(fieldname)` from a ref being shown | |
49 | and the object it points at. If `fieldname` | |
50 | is prefixed with an asterisk (`*`) and the ref points | |
51 | at a tag object, use the value for the field in the object | |
52 | which the tag object refers to (instead of the field in the tag object). | |
53 | When unspecified, `<format>` defaults to | |
54 | `%(objectname) SPC %(objecttype) TAB %(refname)`. | |
55 | It also interpolates `%%` to `%`, and `%xx` where `xx` | |
56 | are hex digits interpolates to character with hex code | |
57 | `xx`; for example `%00` interpolates to `\0` (NUL), | |
58 | `%09` to `\t` (TAB) and `%0a` to `\n` (LF). | |
59 | ||
60 | --color[=<when>]:: | |
61 | Respect any colors specified in the `--format` option. The | |
62 | `<when>` field must be one of `always`, `never`, or `auto` (if | |
63 | `<when>` is absent, behave as if `always` was given). | |
64 | ||
65 | --shell:: | |
66 | --perl:: | |
67 | --python:: | |
68 | --tcl:: | |
69 | If given, strings that substitute `%(fieldname)` | |
70 | placeholders are quoted as string literals suitable for | |
71 | the specified host language. This is meant to produce | |
72 | a scriptlet that can directly be `eval`ed. | |
73 | ||
74 | --points-at=<object>:: | |
75 | Only list refs which points at the given object. | |
76 | ||
77 | --merged[=<object>]:: | |
78 | Only list refs whose tips are reachable from the | |
79 | specified commit (HEAD if not specified), | |
80 | incompatible with `--no-merged`. | |
81 | ||
82 | --no-merged[=<object>]:: | |
83 | Only list refs whose tips are not reachable from the | |
84 | specified commit (HEAD if not specified), | |
85 | incompatible with `--merged`. | |
86 | ||
87 | --contains[=<object>]:: | |
88 | Only list refs which contain the specified commit (HEAD if not | |
89 | specified). | |
90 | ||
91 | --no-contains[=<object>]:: | |
92 | Only list refs which don't contain the specified commit (HEAD | |
93 | if not specified). | |
94 | ||
95 | --ignore-case:: | |
96 | Sorting and filtering refs are case insensitive. | |
97 | ||
98 | FIELD NAMES | |
99 | ----------- | |
100 | ||
101 | Various values from structured fields in referenced objects can | |
102 | be used to interpolate into the resulting output, or as sort | |
103 | keys. | |
104 | ||
105 | For all objects, the following names can be used: | |
106 | ||
107 | refname:: | |
108 | The name of the ref (the part after $GIT_DIR/). | |
109 | For a non-ambiguous short name of the ref append `:short`. | |
110 | The option core.warnAmbiguousRefs is used to select the strict | |
111 | abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` | |
112 | slash-separated path components from the front (back) of the refname | |
113 | (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and | |
114 | `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). | |
115 | If `<N>` is a negative number, strip as many path components as | |
116 | necessary from the specified end to leave `-<N>` path components | |
117 | (e.g. `%(refname:lstrip=-2)` turns | |
118 | `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` | |
119 | turns `refs/tags/foo` into `refs`). When the ref does not have | |
120 | enough components, the result becomes an empty string if | |
121 | stripping with positive <N>, or it becomes the full refname if | |
122 | stripping with negative <N>. Neither is an error. | |
123 | + | |
124 | `strip` can be used as a synonym to `lstrip`. | |
125 | ||
126 | objecttype:: | |
127 | The type of the object (`blob`, `tree`, `commit`, `tag`). | |
128 | ||
129 | objectsize:: | |
130 | The size of the object (the same as 'git cat-file -s' reports). | |
131 | Append `:disk` to get the size, in bytes, that the object takes up on | |
132 | disk. See the note about on-disk sizes in the `CAVEATS` section below. | |
133 | objectname:: | |
134 | The object name (aka SHA-1). | |
135 | For a non-ambiguous abbreviation of the object name append `:short`. | |
136 | For an abbreviation of the object name with desired length append | |
137 | `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The | |
138 | length may be exceeded to ensure unique object names. | |
139 | deltabase:: | |
140 | This expands to the object name of the delta base for the | |
141 | given object, if it is stored as a delta. Otherwise it | |
142 | expands to the null object name (all zeroes). | |
143 | ||
144 | upstream:: | |
145 | The name of a local ref which can be considered ``upstream'' | |
146 | from the displayed ref. Respects `:short`, `:lstrip` and | |
147 | `:rstrip` in the same way as `refname` above. Additionally | |
148 | respects `:track` to show "[ahead N, behind M]" and | |
149 | `:trackshort` to show the terse version: ">" (ahead), "<" | |
150 | (behind), "<>" (ahead and behind), or "=" (in sync). `:track` | |
151 | also prints "[gone]" whenever unknown upstream ref is | |
152 | encountered. Append `:track,nobracket` to show tracking | |
153 | information without brackets (i.e "ahead N, behind M"). | |
154 | + | |
155 | For any remote-tracking branch `%(upstream)`, `%(upstream:remotename)` | |
156 | and `%(upstream:remoteref)` refer to the name of the remote and the | |
157 | name of the tracked remote ref, respectively. In other words, the | |
158 | remote-tracking branch can be updated explicitly and individually by | |
159 | using the refspec `%(upstream:remoteref):%(upstream)` to fetch from | |
160 | `%(upstream:remotename)`. | |
161 | + | |
162 | Has no effect if the ref does not have tracking information associated | |
163 | with it. All the options apart from `nobracket` are mutually exclusive, | |
164 | but if used together the last option is selected. | |
165 | ||
166 | push:: | |
167 | The name of a local ref which represents the `@{push}` | |
168 | location for the displayed ref. Respects `:short`, `:lstrip`, | |
169 | `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref` | |
170 | options as `upstream` does. Produces an empty string if no `@{push}` | |
171 | ref is configured. | |
172 | ||
173 | HEAD:: | |
174 | '*' if HEAD matches current ref (the checked out branch), ' ' | |
175 | otherwise. | |
176 | ||
177 | color:: | |
178 | Change output color. Followed by `:<colorname>`, where color | |
179 | names are described under Values in the "CONFIGURATION FILE" | |
180 | section of linkgit:git-config[1]. For example, | |
181 | `%(color:bold red)`. | |
182 | ||
183 | align:: | |
184 | Left-, middle-, or right-align the content between | |
185 | %(align:...) and %(end). The "align:" is followed by | |
186 | `width=<width>` and `position=<position>` in any order | |
187 | separated by a comma, where the `<position>` is either left, | |
188 | right or middle, default being left and `<width>` is the total | |
189 | length of the content with alignment. For brevity, the | |
190 | "width=" and/or "position=" prefixes may be omitted, and bare | |
191 | <width> and <position> used instead. For instance, | |
192 | `%(align:<width>,<position>)`. If the contents length is more | |
193 | than the width then no alignment is performed. If used with | |
194 | `--quote` everything in between %(align:...) and %(end) is | |
195 | quoted, but if nested then only the topmost level performs | |
196 | quoting. | |
197 | ||
198 | if:: | |
199 | Used as %(if)...%(then)...%(end) or | |
200 | %(if)...%(then)...%(else)...%(end). If there is an atom with | |
201 | value or string literal after the %(if) then everything after | |
202 | the %(then) is printed, else if the %(else) atom is used, then | |
203 | everything after %(else) is printed. We ignore space when | |
204 | evaluating the string before %(then), this is useful when we | |
205 | use the %(HEAD) atom which prints either "*" or " " and we | |
206 | want to apply the 'if' condition only on the 'HEAD' ref. | |
207 | Append ":equals=<string>" or ":notequals=<string>" to compare | |
208 | the value between the %(if:...) and %(then) atoms with the | |
209 | given string. | |
210 | ||
211 | symref:: | |
212 | The ref which the given symbolic ref refers to. If not a | |
213 | symbolic ref, nothing is printed. Respects the `:short`, | |
214 | `:lstrip` and `:rstrip` options in the same way as `refname` | |
215 | above. | |
216 | ||
217 | worktreepath:: | |
218 | The absolute path to the worktree in which the ref is checked | |
219 | out, if it is checked out in any linked worktree. Empty string | |
220 | otherwise. | |
221 | ||
222 | In addition to the above, for commit and tag objects, the header | |
223 | field names (`tree`, `parent`, `object`, `type`, and `tag`) can | |
224 | be used to specify the value in the header field. | |
225 | ||
226 | For commit and tag objects, the special `creatordate` and `creator` | |
227 | fields will correspond to the appropriate date or name-email-date tuple | |
228 | from the `committer` or `tagger` fields depending on the object type. | |
229 | These are intended for working on a mix of annotated and lightweight tags. | |
230 | ||
231 | Fields that have name-email-date tuple as its value (`author`, | |
232 | `committer`, and `tagger`) can be suffixed with `name`, `email`, | |
233 | and `date` to extract the named component. | |
234 | ||
235 | The complete message in a commit and tag object is `contents`. | |
236 | Its first line is `contents:subject`, where subject is the concatenation | |
237 | of all lines of the commit message up to the first blank line. The next | |
238 | line is `contents:body`, where body is all of the lines after the first | |
239 | blank line. The optional GPG signature is `contents:signature`. The | |
240 | first `N` lines of the message is obtained using `contents:lines=N`. | |
241 | Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] | |
242 | are obtained as `trailers` (or by using the historical alias | |
243 | `contents:trailers`). Non-trailer lines from the trailer block can be omitted | |
244 | with `trailers:only`. Whitespace-continuations can be removed from trailers so | |
245 | that each trailer appears on a line by itself with its full content with | |
246 | `trailers:unfold`. Both can be used together as `trailers:unfold,only`. | |
247 | ||
248 | For sorting purposes, fields with numeric values sort in numeric order | |
249 | (`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`). | |
250 | All other fields are used to sort in their byte-value order. | |
251 | ||
252 | There is also an option to sort by versions, this can be done by using | |
253 | the fieldname `version:refname` or its alias `v:refname`. | |
254 | ||
255 | In any case, a field name that refers to a field inapplicable to | |
256 | the object referred by the ref does not cause an error. It | |
257 | returns an empty string instead. | |
258 | ||
259 | As a special case for the date-type fields, you may specify a format for | |
260 | the date by adding `:` followed by date format name (see the | |
261 | values the `--date` option to linkgit:git-rev-list[1] takes). | |
262 | ||
263 | Some atoms like %(align) and %(if) always require a matching %(end). | |
264 | We call them "opening atoms" and sometimes denote them as %($open). | |
265 | ||
266 | When a scripting language specific quoting is in effect, everything | |
267 | between a top-level opening atom and its matching %(end) is evaluated | |
268 | according to the semantics of the opening atom and only its result | |
269 | from the top-level is quoted. | |
270 | ||
271 | ||
272 | EXAMPLES | |
273 | -------- | |
274 | ||
275 | An example directly producing formatted text. Show the most recent | |
276 | 3 tagged commits: | |
277 | ||
278 | ------------ | |
279 | #!/bin/sh | |
280 | ||
281 | git for-each-ref --count=3 --sort='-*authordate' \ | |
282 | --format='From: %(*authorname) %(*authoremail) | |
283 | Subject: %(*subject) | |
284 | Date: %(*authordate) | |
285 | Ref: %(*refname) | |
286 | ||
287 | %(*body) | |
288 | ' 'refs/tags' | |
289 | ------------ | |
290 | ||
291 | ||
292 | A simple example showing the use of shell eval on the output, | |
293 | demonstrating the use of --shell. List the prefixes of all heads: | |
294 | ------------ | |
295 | #!/bin/sh | |
296 | ||
297 | git for-each-ref --shell --format="ref=%(refname)" refs/heads | \ | |
298 | while read entry | |
299 | do | |
300 | eval "$entry" | |
301 | echo `dirname $ref` | |
302 | done | |
303 | ------------ | |
304 | ||
305 | ||
306 | A bit more elaborate report on tags, demonstrating that the format | |
307 | may be an entire script: | |
308 | ------------ | |
309 | #!/bin/sh | |
310 | ||
311 | fmt=' | |
312 | r=%(refname) | |
313 | t=%(*objecttype) | |
314 | T=${r#refs/tags/} | |
315 | ||
316 | o=%(*objectname) | |
317 | n=%(*authorname) | |
318 | e=%(*authoremail) | |
319 | s=%(*subject) | |
320 | d=%(*authordate) | |
321 | b=%(*body) | |
322 | ||
323 | kind=Tag | |
324 | if test "z$t" = z | |
325 | then | |
326 | # could be a lightweight tag | |
327 | t=%(objecttype) | |
328 | kind="Lightweight tag" | |
329 | o=%(objectname) | |
330 | n=%(authorname) | |
331 | e=%(authoremail) | |
332 | s=%(subject) | |
333 | d=%(authordate) | |
334 | b=%(body) | |
335 | fi | |
336 | echo "$kind $T points at a $t object $o" | |
337 | if test "z$t" = zcommit | |
338 | then | |
339 | echo "The commit was authored by $n $e | |
340 | at $d, and titled | |
341 | ||
342 | $s | |
343 | ||
344 | Its message reads as: | |
345 | " | |
346 | echo "$b" | sed -e "s/^/ /" | |
347 | echo | |
348 | fi | |
349 | ' | |
350 | ||
351 | eval=`git for-each-ref --shell --format="$fmt" \ | |
352 | --sort='*objecttype' \ | |
353 | --sort=-taggerdate \ | |
354 | refs/tags` | |
355 | eval "$eval" | |
356 | ------------ | |
357 | ||
358 | ||
359 | An example to show the usage of %(if)...%(then)...%(else)...%(end). | |
360 | This prefixes the current branch with a star. | |
361 | ||
362 | ------------ | |
363 | git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)" refs/heads/ | |
364 | ------------ | |
365 | ||
366 | ||
367 | An example to show the usage of %(if)...%(then)...%(end). | |
368 | This prints the authorname, if present. | |
369 | ||
370 | ------------ | |
371 | git for-each-ref --format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)" | |
372 | ------------ | |
373 | ||
374 | CAVEATS | |
375 | ------- | |
376 | ||
377 | Note that the sizes of objects on disk are reported accurately, but care | |
378 | should be taken in drawing conclusions about which refs or objects are | |
379 | responsible for disk usage. The size of a packed non-delta object may be | |
380 | much larger than the size of objects which delta against it, but the | |
381 | choice of which object is the base and which is the delta is arbitrary | |
382 | and is subject to change during a repack. | |
383 | ||
384 | Note also that multiple copies of an object may be present in the object | |
385 | database; in this case, it is undefined which copy's size or delta base | |
386 | will be reported. | |
387 | ||
388 | SEE ALSO | |
389 | -------- | |
390 | linkgit:git-show-ref[1] | |
391 | ||
392 | GIT | |
393 | --- | |
394 | Part of the linkgit:git[1] suite |