]>
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>...] |
7c328348 | 13 | [--points-at <object>] [(--merged | --no-merged) [<object>]] |
4a71109a | 14 | [--contains [<object>]] |
9f613ddd JH |
15 | |
16 | DESCRIPTION | |
17 | ----------- | |
18 | ||
19 | Iterate over all refs that match `<pattern>` and show them | |
20 | according to the given `<format>`, after sorting them according | |
d4040e0a | 21 | to the given set of `<key>`. If `<count>` is given, stop after |
23bfbb81 | 22 | showing that many refs. The interpolated values in `<format>` |
9f613ddd | 23 | can optionally be quoted as string literals in the specified |
1729fa98 | 24 | host language allowing their direct evaluation in that language. |
9f613ddd JH |
25 | |
26 | OPTIONS | |
27 | ------- | |
28 | <count>:: | |
29 | By default the command shows all refs that match | |
30 | `<pattern>`. This option makes it stop after showing | |
31 | that many refs. | |
32 | ||
33 | <key>:: | |
34 | A field name to sort on. Prefix `-` to sort in | |
35 | descending order of the value. When unspecified, | |
c0f6dc9b LW |
36 | `refname` is used. You may use the --sort=<key> option |
37 | multiple times, in which case the last key becomes the primary | |
38 | key. | |
9f613ddd JH |
39 | |
40 | <format>:: | |
41 | A string that interpolates `%(fieldname)` from the | |
42 | object pointed at by a ref being shown. If `fieldname` | |
43 | is prefixed with an asterisk (`*`) and the ref points | |
44 | at a tag object, the value for the field in the object | |
45 | tag refers is used. When unspecified, defaults to | |
ba7545ad JN |
46 | `%(objectname) SPC %(objecttype) TAB %(refname)`. |
47 | It also interpolates `%%` to `%`, and `%xx` where `xx` | |
48 | are hex digits interpolates to character with hex code | |
49 | `xx`; for example `%00` interpolates to `\0` (NUL), | |
50 | `%09` to `\t` (TAB) and `%0a` to `\n` (LF). | |
9f613ddd | 51 | |
f448e24e | 52 | <pattern>...:: |
c0f6dc9b | 53 | If one or more patterns are given, only refs are shown that |
1168d402 | 54 | match against at least one pattern, either using fnmatch(3) or |
c0f6dc9b LW |
55 | literally, in the latter case matching completely or from the |
56 | beginning up to a slash. | |
9f613ddd | 57 | |
3240240f SB |
58 | --shell:: |
59 | --perl:: | |
60 | --python:: | |
61 | --tcl:: | |
9f613ddd JH |
62 | If given, strings that substitute `%(fieldname)` |
63 | placeholders are quoted as string literals suitable for | |
64 | the specified host language. This is meant to produce | |
65 | a scriptlet that can directly be `eval`ed. | |
66 | ||
d325406e KN |
67 | --points-at <object>:: |
68 | Only list refs which points at the given object. | |
9f613ddd | 69 | |
7c328348 KN |
70 | --merged [<object>]:: |
71 | Only list refs whose tips are reachable from the | |
72 | specified commit (HEAD if not specified). | |
73 | ||
74 | --no-merged [<object>]:: | |
75 | Only list refs whose tips are not reachable from the | |
76 | specified commit (HEAD if not specified). | |
77 | ||
4a71109a | 78 | --contains [<object>]:: |
8b5a3e98 | 79 | Only list refs which contain the specified commit (HEAD if not |
4a71109a KN |
80 | specified). |
81 | ||
9f613ddd JH |
82 | FIELD NAMES |
83 | ----------- | |
84 | ||
85 | Various values from structured fields in referenced objects can | |
86 | be used to interpolate into the resulting output, or as sort | |
87 | keys. | |
88 | ||
89 | For all objects, the following names can be used: | |
90 | ||
91 | refname:: | |
69057cf3 | 92 | The name of the ref (the part after $GIT_DIR/). |
7d66f21a | 93 | For a non-ambiguous short name of the ref append `:short`. |
2bb98169 | 94 | The option core.warnAmbiguousRefs is used to select the strict |
0571979b JK |
95 | abbreviation mode. If `strip=<N>` is appended, strips `<N>` |
96 | slash-separated path components from the front of the refname | |
97 | (e.g., `%(refname:strip=2)` turns `refs/tags/foo` into `foo`. | |
98 | `<N>` must be a positive integer. If a displayed ref has fewer | |
99 | components than `<N>`, the command aborts with an error. | |
9f613ddd JH |
100 | |
101 | objecttype:: | |
102 | The type of the object (`blob`, `tree`, `commit`, `tag`). | |
103 | ||
104 | objectsize:: | |
0b444cdb | 105 | The size of the object (the same as 'git cat-file -s' reports). |
9f613ddd JH |
106 | |
107 | objectname:: | |
108 | The object name (aka SHA-1). | |
67687fea | 109 | For a non-ambiguous abbreviation of the object name append `:short`. |
9f613ddd | 110 | |
8cae19d9 JK |
111 | upstream:: |
112 | The name of a local ref which can be considered ``upstream'' | |
113 | from the displayed ref. Respects `:short` in the same way as | |
b28061ce RR |
114 | `refname` above. Additionally respects `:track` to show |
115 | "[ahead N, behind M]" and `:trackshort` to show the terse | |
116 | version: ">" (ahead), "<" (behind), "<>" (ahead and behind), | |
117 | or "=" (in sync). Has no effect if the ref does not have | |
118 | tracking information associated with it. | |
8cae19d9 | 119 | |
29bc8850 JK |
120 | push:: |
121 | The name of a local ref which represents the `@{push}` location | |
122 | for the displayed ref. Respects `:short`, `:track`, and | |
123 | `:trackshort` options as `upstream` does. Produces an empty | |
124 | string if no `@{push}` ref is configured. | |
125 | ||
7a48b832 RR |
126 | HEAD:: |
127 | '*' if HEAD matches current ref (the checked out branch), ' ' | |
128 | otherwise. | |
129 | ||
fddb74c9 RR |
130 | color:: |
131 | Change output color. Followed by `:<colorname>`, where names | |
132 | are described in `color.branch.*`. | |
133 | ||
ce592082 KN |
134 | align:: |
135 | Left-, middle-, or right-align the content between | |
395fb8f9 KN |
136 | %(align:...) and %(end). The "align:" is followed by |
137 | `width=<width>` and `position=<position>` in any order | |
138 | separated by a comma, where the `<position>` is either left, | |
139 | right or middle, default being left and `<width>` is the total | |
140 | length of the content with alignment. For brevity, the | |
141 | "width=" and/or "position=" prefixes may be omitted, and bare | |
142 | <width> and <position> used instead. For instance, | |
143 | `%(align:<width>,<position>)`. If the contents length is more | |
144 | than the width then no alignment is performed. If used with | |
bcf9626a | 145 | `--quote` everything in between %(align:...) and %(end) is |
395fb8f9 KN |
146 | quoted, but if nested then only the topmost level performs |
147 | quoting. | |
ce592082 | 148 | |
9f613ddd JH |
149 | In addition to the above, for commit and tag objects, the header |
150 | field names (`tree`, `parent`, `object`, `type`, and `tag`) can | |
151 | be used to specify the value in the header field. | |
152 | ||
e914ef0d EW |
153 | For commit and tag objects, the special `creatordate` and `creator` |
154 | fields will correspond to the appropriate date or name-email-date tuple | |
155 | from the `committer` or `tagger` fields depending on the object type. | |
156 | These are intended for working on a mix of annotated and lightweight tags. | |
157 | ||
9f613ddd JH |
158 | Fields that have name-email-date tuple as its value (`author`, |
159 | `committer`, and `tagger`) can be suffixed with `name`, `email`, | |
160 | and `date` to extract the named component. | |
161 | ||
e2b23972 | 162 | The complete message in a commit and tag object is `contents`. |
52ffe995 JW |
163 | Its first line is `contents:subject`, where subject is the concatenation |
164 | of all lines of the commit message up to the first blank line. The next | |
165 | line is 'contents:body', where body is all of the lines after the first | |
1bb38e5a KN |
166 | blank line. The optional GPG signature is `contents:signature`. The |
167 | first `N` lines of the message is obtained using `contents:lines=N`. | |
9f613ddd | 168 | |
e914ef0d EW |
169 | For sorting purposes, fields with numeric values sort in numeric order |
170 | (`objectsize`, `authordate`, `committerdate`, `creatordate`, `taggerdate`). | |
9f613ddd JH |
171 | All other fields are used to sort in their byte-value order. |
172 | ||
90c00408 KN |
173 | There is also an option to sort by versions, this can be done by using |
174 | the fieldname `version:refname` or its alias `v:refname`. | |
175 | ||
9f613ddd JH |
176 | In any case, a field name that refers to a field inapplicable to |
177 | the object referred by the ref does not cause an error. It | |
178 | returns an empty string instead. | |
179 | ||
d392e712 | 180 | As a special case for the date-type fields, you may specify a format for |
8f50d263 | 181 | the date by adding `:` followed by date format name (see the |
1cca17df | 182 | values the `--date` option to linkgit:git-rev-list[1] takes). |
d392e712 | 183 | |
9f613ddd JH |
184 | |
185 | EXAMPLES | |
186 | -------- | |
187 | ||
1729fa98 | 188 | An example directly producing formatted text. Show the most recent |
22817b40 | 189 | 3 tagged commits: |
9f613ddd JH |
190 | |
191 | ------------ | |
192 | #!/bin/sh | |
193 | ||
b1889c36 | 194 | git for-each-ref --count=3 --sort='-*authordate' \ |
9f613ddd JH |
195 | --format='From: %(*authorname) %(*authoremail) |
196 | Subject: %(*subject) | |
197 | Date: %(*authordate) | |
198 | Ref: %(*refname) | |
199 | ||
200 | %(*body) | |
201 | ' 'refs/tags' | |
202 | ------------ | |
203 | ||
1729fa98 AW |
204 | |
205 | A simple example showing the use of shell eval on the output, | |
22817b40 | 206 | demonstrating the use of --shell. List the prefixes of all heads: |
1729fa98 AW |
207 | ------------ |
208 | #!/bin/sh | |
209 | ||
b1889c36 | 210 | git for-each-ref --shell --format="ref=%(refname)" refs/heads | \ |
1729fa98 AW |
211 | while read entry |
212 | do | |
213 | eval "$entry" | |
214 | echo `dirname $ref` | |
215 | done | |
216 | ------------ | |
217 | ||
218 | ||
219 | A bit more elaborate report on tags, demonstrating that the format | |
22817b40 | 220 | may be an entire script: |
9f613ddd JH |
221 | ------------ |
222 | #!/bin/sh | |
223 | ||
224 | fmt=' | |
225 | r=%(refname) | |
226 | t=%(*objecttype) | |
227 | T=${r#refs/tags/} | |
228 | ||
229 | o=%(*objectname) | |
230 | n=%(*authorname) | |
231 | e=%(*authoremail) | |
232 | s=%(*subject) | |
233 | d=%(*authordate) | |
234 | b=%(*body) | |
235 | ||
236 | kind=Tag | |
237 | if test "z$t" = z | |
238 | then | |
239 | # could be a lightweight tag | |
240 | t=%(objecttype) | |
241 | kind="Lightweight tag" | |
242 | o=%(objectname) | |
243 | n=%(authorname) | |
244 | e=%(authoremail) | |
245 | s=%(subject) | |
246 | d=%(authordate) | |
247 | b=%(body) | |
248 | fi | |
249 | echo "$kind $T points at a $t object $o" | |
250 | if test "z$t" = zcommit | |
251 | then | |
252 | echo "The commit was authored by $n $e | |
253 | at $d, and titled | |
254 | ||
255 | $s | |
256 | ||
257 | Its message reads as: | |
258 | " | |
259 | echo "$b" | sed -e "s/^/ /" | |
260 | echo | |
261 | fi | |
262 | ' | |
263 | ||
b1889c36 | 264 | eval=`git for-each-ref --shell --format="$fmt" \ |
9f613ddd JH |
265 | --sort='*objecttype' \ |
266 | --sort=-taggerdate \ | |
267 | refs/tags` | |
268 | eval "$eval" | |
269 | ------------ | |
621c39de | 270 | |
f21e1c5d MH |
271 | SEE ALSO |
272 | -------- | |
273 | linkgit:git-show-ref[1] | |
274 | ||
621c39de AS |
275 | GIT |
276 | --- | |
277 | Part of the linkgit:git[1] suite |