93203872d7 · matheusbsbs/matheus-bagliano

@@ -14,101 +14,98 @@ git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]

14 [--merged[=<object>]] [--no-merged[=<object>]]

15 [--contains[=<object>]] [--no-contains[=<object>]]

16 [(--exclude=<pattern>)...] [--start-after=<marker>]

17 - [ --stdin | <pattern>... ]

17 + [ --stdin | (<pattern>...)]

18

19 DESCRIPTION

20 -----------

21

22 -Iterate over all refs that match `<pattern>` and show them

23 -according to the given `<format>`, after sorting them according

24 -to the given set of `<key>`. If `<count>` is given, stop after

25 -showing that many refs. The interpolated values in `<format>`

22 +Iterate over all refs that match _<pattern>_ and show them

23 +according to the given _<format>_, after sorting them according

24 +to the given set of _<key>_. If _<count>_ is given, stop after

25 +showing that many refs. The interpolated values in _<format>_

26 can optionally be quoted as string literals in the specified

27 host language allowing their direct evaluation in that language.

28

29 OPTIONS

30 -------

31 -<pattern>...::

32 - If one or more patterns are given, only refs are shown that

33 - match against at least one pattern, either using fnmatch(3) or

31 +`<pattern>...`::

32 + If one or more _<pattern>_ parameters are given, only refs are shown that

33 + match against at least one pattern, either using `fnmatch`(3) or

34 literally, in the latter case matching completely or from the

35 beginning up to a slash.

36

37 ---stdin::

38 - If `--stdin` is supplied, then the list of patterns is read from

39 - standard input instead of from the argument list.

37 +`--stdin`::

38 + The list of patterns is read from standard input instead of from

39 + the argument list.

40

41 ---count=<count>::

42 - By default the command shows all refs that match

43 - `<pattern>`. This option makes it stop after showing

44 - that many refs.

41 +`--count=<count>`::

42 + Stop after showing _<count>_ refs.

43

46 ---sort=<key>::

47 - A field name to sort on. Prefix `-` to sort in

44 +`--sort=<key>`::

45 + Sort on the field name _<key>_. Prefix `-` to sort in

46 descending order of the value. When unspecified,

49 - `refname` is used. You may use the --sort=<key> option

47 + `refname` is used. You may use the `--sort=<key>` option

48 multiple times, in which case the last key becomes the primary

49 key.

50

53 ---format=<format>::

51 +`--format[=<format>]`::

52 A string that interpolates `%(fieldname)` from a ref being shown and

53 the object it points at. In addition, the string literal `%%`

54 renders as `%` and `%xx` - where `xx` are hex digits - renders as

55 the character with hex code `xx`. For example, `%00` interpolates to

58 - `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).

59 -+

60 -When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)

56 + `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_).

57 +

58 +When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype)

59 TAB %(refname)`.

60

63 ---color[=<when>]::

61 +`--color[=<when>]`::

62 Respect any colors specified in the `--format` option. The

65 - `<when>` field must be one of `always`, `never`, or `auto` (if

63 + _<when__ field must be one of `always`, `never`, or `auto` (if

64 `<when>` is absent, behave as if `always` was given).

65

68 ---shell::

69 ---perl::

70 ---python::

71 ---tcl::

66 +`--shell`::

67 +`--perl`::

68 +`--python`::

69 +`--tcl`::

70 If given, strings that substitute `%(fieldname)`

71 placeholders are quoted as string literals suitable for

72 the specified host language. This is meant to produce

75 - a scriptlet that can directly be `eval`ed.

73 + a scriptlet that can directly be "eval"ed.

74

77 ---points-at=<object>::

75 +`--points-at=<object>`::

76 Only list refs which points at the given object.

77

80 ---merged[=<object>]::

78 +`--merged[=<object>]`::

79 Only list refs whose tips are reachable from the

82 - specified commit (HEAD if not specified).

83 -

84 ---no-merged[=<object>]::

85 - Only list refs whose tips are not reachable from the

86 - specified commit (HEAD if not specified).

80 + specified commit (`HEAD` if not specified).

81

88 ---contains[=<object>]::

89 - Only list refs which contain the specified commit (HEAD if not

82 +`--no-merged[=<object>]`::

83 + Only list refs whose tips are not reachable from _<object>_(`HEAD` if not

84 specified).

85

92 ---no-contains[=<object>]::

93 - Only list refs which don't contain the specified commit (HEAD

86 +`--contains[=<object>]`::

87 + Only list refs which contain _<object>_(`HEAD` if not specified).

88 +

89 +`--no-contains[=<object>]`::

90 + Only list refs which don't contain _<object>_ (`HEAD`

91 if not specified).

92

96 ---ignore-case::

93 +`--ignore-case`::

94 Sorting and filtering refs are case insensitive.

95

99 ---omit-empty::

96 +`--omit-empty`::

97 Do not print a newline after formatted refs where the format expands

98 to the empty string.

99

103 ---exclude=<pattern>::

104 - If one or more patterns are given, only refs which do not match

105 - any excluded pattern(s) are shown. Matching is done using the

106 - same rules as `<pattern>` above.

100 +`--exclude=<excluded-pattern>`::

101 + If one or more `--exclude` options are given, only refs which do not

102 + match any _<excluded-pattern>_ parameters are shown. Matching is done

103 + using the same rules as _<pattern>_ above.

104

108 ---include-root-refs::

109 - List root refs (HEAD and pseudorefs) apart from regular refs.

105 +`--include-root-refs`::

106 + List root refs (`HEAD` and pseudorefs) apart from regular refs.

107

111 ---start-after=<marker>::

108 +`--start-after=<marker>`::

109 Allows paginating the output by skipping references up to and including the

110 specified marker. When paging, it should be noted that references may be

111 deleted, modified or added between invocations. Output will only yield those

@@ -126,44 +123,44 @@ keys.

123

124 For all objects, the following names can be used:

125

129 -refname::

130 - The name of the ref (the part after $GIT_DIR/).

126 +`refname`::

127 + The name of the ref (the part after `$GIT_DIR/`).

128 For a non-ambiguous short name of the ref append `:short`.

132 - The option core.warnAmbiguousRefs is used to select the strict

133 - abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>`

129 + The option `core.warnAmbiguousRefs` is used to select the strict

130 + abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_

131 slash-separated path components from the front (back) of the refname

132 (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and

133 `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).

137 - If `<N>` is a negative number, strip as many path components as

138 - necessary from the specified end to leave `-<N>` path components

134 + If _<n>_ is a negative number, strip as many path components as

135 + necessary from the specified end to leave `-<n>` path components

136 (e.g. `%(refname:lstrip=-2)` turns

137 `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`

138 turns `refs/tags/foo` into `refs`). When the ref does not have

139 enough components, the result becomes an empty string if

143 - stripping with positive <N>, or it becomes the full refname if

144 - stripping with negative <N>. Neither is an error.

140 + stripping with positive _<n>_, or it becomes the full refname if

141 + stripping with negative _<N>_. Neither is an error.

142 +

143 `strip` can be used as a synonym to `lstrip`.

144

148 -objecttype::

145 +`objecttype`::

146 The type of the object (`blob`, `tree`, `commit`, `tag`).

147

151 -objectsize::

148 +`objectsize`::

149 The size of the object (the same as 'git cat-file -s' reports).

150 Append `:disk` to get the size, in bytes, that the object takes up on

154 - disk. See the note about on-disk sizes in the `CAVEATS` section below.

155 -objectname::

151 + disk. See the note about on-disk sizes in the 'CAVEATS' section below.

152 +`objectname`::

153 The object name (aka SHA-1).

154 For a non-ambiguous abbreviation of the object name append `:short`.

155 For an abbreviation of the object name with desired length append

159 - `:short=<length>`, where the minimum length is MINIMUM_ABBREV. The

156 + `:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The

157 length may be exceeded to ensure unique object names.

161 -deltabase::

158 +`deltabase`::

159 This expands to the object name of the delta base for the

160 given object, if it is stored as a delta. Otherwise it

161 expands to the null object name (all zeroes).

162

166 -upstream::

163 +`upstream`::

164 The name of a local ref which can be considered ``upstream''

165 from the displayed ref. Respects `:short`, `:lstrip` and

166 `:rstrip` in the same way as `refname` above. Additionally

@@ -185,100 +182,103 @@ Has no effect if the ref does not have tracking information associated

182 with it. All the options apart from `nobracket` are mutually exclusive,

183 but if used together the last option is selected.

184

188 -push::

185 +`push`::

186 The name of a local ref which represents the `@{push}`

187 location for the displayed ref. Respects `:short`, `:lstrip`,

188 `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref`

189 options as `upstream` does. Produces an empty string if no `@{push}`

190 ref is configured.

191

195 -HEAD::

196 - '*' if HEAD matches current ref (the checked out branch), ' '

192 +`HEAD`::

193 + `*` if `HEAD` matches current ref (the checked out branch), ' '

194 otherwise.

195

199 -color::

196 +`color`::

197 Change output color. Followed by `:<colorname>`, where color

198 names are described under Values in the "CONFIGURATION FILE"

199 section of linkgit:git-config[1]. For example,

200 `%(color:bold red)`.

201

205 -align::

202 +`align`::

203 Left-, middle-, or right-align the content between

207 - %(align:...) and %(end). The "align:" is followed by

204 + `%(align:...)` and `%(end)`. The "`align:`" is followed by

205 `width=<width>` and `position=<position>` in any order

209 - separated by a comma, where the `<position>` is either left,

210 - right or middle, default being left and `<width>` is the total

206 + separated by a comma, where the _<position>_ is either `left`,

207 + `right` or `middle`, default being `left` and _<width>_ is the total

208 length of the content with alignment. For brevity, the

209 "width=" and/or "position=" prefixes may be omitted, and bare

213 - <width> and <position> used instead. For instance,

210 + _<width>_ and _<position>_ used instead. For instance,

211 `%(align:<width>,<position>)`. If the contents length is more

212 than the width then no alignment is performed. If used with

216 - `--quote` everything in between %(align:...) and %(end) is

213 + `--quote` everything in between `%(align:...)` and `%(end)` is

214 quoted, but if nested then only the topmost level performs

215 quoting.

216

220 -if::

221 - Used as %(if)...%(then)...%(end) or

222 - %(if)...%(then)...%(else)...%(end). If there is an atom with

223 - value or string literal after the %(if) then everything after

224 - the %(then) is printed, else if the %(else) atom is used, then

217 +`if`::

218 + Used as `%(if)...%(then)...%(end)` or

219 + `%(if)...%(then)...%(else)...%(end)`. If there is an atom with

220 + value or string literal after the `%(if)` then everything after

221 + the `%(then)` is printed, else if the `%(else)` atom is used, then

222 everything after %(else) is printed. We ignore space when

226 - evaluating the string before %(then), this is useful when we

227 - use the %(HEAD) atom which prints either "*" or " " and we

228 - want to apply the 'if' condition only on the 'HEAD' ref.

229 - Append ":equals=<string>" or ":notequals=<string>" to compare

230 - the value between the %(if:...) and %(then) atoms with the

223 + evaluating the string before `%(then)`, this is useful when we

224 + use the `%(HEAD)` atom which prints either "`*`" or " " and we

225 + want to apply the 'if' condition only on the `HEAD` ref.

226 + Append "`:equals=<string>`" or "`:notequals=<string>`" to compare

227 + the value between the `%(if:...)` and `%(then)` atoms with the

228 given string.

229

233 -symref::

230 +`symref`::

231 The ref which the given symbolic ref refers to. If not a

232 symbolic ref, nothing is printed. Respects the `:short`,

233 `:lstrip` and `:rstrip` options in the same way as `refname`

234 above.

235

239 -signature::

236 +`signature`::

237 The GPG signature of a commit.

238

242 -signature:grade::

243 - Show "G" for a good (valid) signature, "B" for a bad

244 - signature, "U" for a good signature with unknown validity, "X"

245 - for a good signature that has expired, "Y" for a good

246 - signature made by an expired key, "R" for a good signature

247 - made by a revoked key, "E" if the signature cannot be

248 - checked (e.g. missing key) and "N" for no signature.

249 -

250 -signature:signer::

239 +`signature:grade`::

240 + Show

241 +`G`;; for a good (valid) signature

242 +`B`;; for a bad signature

243 +`U`;; for a good signature with unknown validity

244 +`X`;; for a good signature that has expired

245 +`Y`;; for a good signature made by an expired key

246 +`R`;; for a good signature made by a revoked key

247 +`E`;; if the signature cannot be checked (e.g. missing key)

248 +`N`;; for no signature.

249 +

250 +`signature:signer`::

251 The signer of the GPG signature of a commit.

252

253 -signature:key::

253 +`signature:key`::

254 The key of the GPG signature of a commit.

255

256 -signature:fingerprint::

256 +`signature:fingerprint`::

257 The fingerprint of the GPG signature of a commit.

258

259 -signature:primarykeyfingerprint::

259 +`signature:primarykeyfingerprint`::

260 The primary key fingerprint of the GPG signature of a commit.

261

262 -signature:trustlevel::

262 +`signature:trustlevel`::

263 The trust level of the GPG signature of a commit. Possible

264 outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`.

265

266 -worktreepath::

266 +`worktreepath`::

267 The absolute path to the worktree in which the ref is checked

268 out, if it is checked out in any linked worktree. Empty string

269 otherwise.

270

271 -ahead-behind:<committish>::

271 +`ahead-behind:<commit-ish>`::

272 Two integers, separated by a space, demonstrating the number of

273 commits ahead and behind, respectively, when comparing the output

274 - ref to the `<committish>` specified in the format.

274 + ref to the _<committish>_ specified in the format.

275

276 -is-base:<committish>::

277 - In at most one row, `(<committish>)` will appear to indicate the ref

276 +`is-base:<commit-ish>`::

277 + In at most one row, `(<commit-ish>)` will appear to indicate the ref

278 that is most likely the ref used as a starting point for the branch

279 - that produced `<committish>`. This choice is made using a heuristic:

279 + that produced _<commit-ish>_. This choice is made using a heuristic:

280 choose the ref that minimizes the number of commits in the

281 - first-parent history of `<committish>` and not in the first-parent

281 + first-parent history of _<commit-ish>_ and not in the first-parent

282 history of the ref.

283 +

284 For example, consider the following figure of first-parent histories of

@@ -312,29 +312,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the

312 earliest ref in the sorted order.

313 +

314 Note that this token will not appear if the first-parent history of

315 -`<committish>` does not intersect the first-parent histories of the

315 +_<commit-ish>_ does not intersect the first-parent histories of the

316 filtered refs.

317

318 -describe[:options]::

318 +`describe[:<option>,...]`::

319 A human-readable name, like linkgit:git-describe[1];

320 empty string for undescribable commits. The `describe` string may

321 be followed by a colon and one or more comma-separated options.

322 +

323 --

324 -tags=<bool-value>;;

324 +`tags=<bool-value>`;;

325 Instead of only considering annotated tags, consider

326 lightweight tags as well; see the corresponding option in

327 linkgit:git-describe[1] for details.

328 -abbrev=<number>;;

329 - Use at least <number> hexadecimal digits; see the corresponding

328 +`abbrev=<number>`;;

329 + Use at least _<number>_ hexadecimal digits; see the corresponding

330 option in linkgit:git-describe[1] for details.

331 -match=<pattern>;;

332 - Only consider tags matching the given `glob(7)` pattern,

333 - excluding the "refs/tags/" prefix; see the corresponding option

331 +`match=<pattern>`;;

332 + Only consider tags matching the `glob`(7) _<pattern>_,

333 + excluding the `refs/tags/` prefix; see the corresponding option

334 in linkgit:git-describe[1] for details.

335 -exclude=<pattern>;;

336 - Do not consider tags matching the given `glob(7)` pattern,

337 - excluding the "refs/tags/" prefix; see the corresponding option

335 +`exclude=<pattern>`;;

336 + Do not consider tags matching the `glob`(7) _<pattern>_,

337 + excluding the `refs/tags/` prefix; see the corresponding option

338 in linkgit:git-describe[1] for details.

339 --

340

@@ -366,7 +366,7 @@ variable (see linkgit:gitmailmap[5]).

366

367 The raw data in an object is `raw`.

368

369 -raw:size::

369 +`raw:size`::

370 The raw data size of the object.

371

372 Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`,

@@ -376,10 +376,10 @@ variable type.

376 The message in a commit or a tag object is `contents`, from which

377 `contents:<part>` can be used to extract various parts out of:

378

379 -contents:size::

379 +`contents:size`::

380 The size in bytes of the commit or tag message.

381

382 -contents:subject::

382 +`contents:subject`::

383 The first paragraph of the message, which typically is a

384 single line, is taken as the "subject" of the commit or the

385 tag message.

@@ -387,19 +387,19 @@ contents:subject::

387 obtain same results. `:sanitize` can be appended to `subject` for

388 subject line suitable for filename.

389

390 -contents:body::

390 +`contents:body`::

391 The remainder of the commit or the tag message that follows

392 the "subject".

393

394 -contents:signature::

394 +`contents:signature`::

395 The optional GPG signature of the tag.

396

397 -contents:lines=N::

398 - The first `N` lines of the message.

397 +`contents:lines=<n>`::

398 + The first _<n>_ lines of the message.

399

400 Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]

401 -are obtained as `trailers[:options]` (or by using the historical alias

402 -`contents:trailers[:options]`). For valid [:option] values see `trailers`

401 +are obtained as `trailers[:<option>,...]` (or by using the historical alias

402 +`contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers`

403 section of linkgit:git-log[1].

404

405 For sorting purposes, fields with numeric values sort in numeric order

@@ -419,8 +419,8 @@ option to linkgit:git-rev-list[1] takes). If this formatting is provided in

419 a `--sort` key, references will be sorted according to the byte-value of the

420 formatted string rather than the numeric value of the underlying timestamp.

421

422 -Some atoms like %(align) and %(if) always require a matching %(end).

423 -We call them "opening atoms" and sometimes denote them as %($open).

422 +Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`.

423 +We call them "opening atoms" and sometimes denote them as `%($open)`.

424

425 When a scripting language specific quoting is in effect, everything

426 between a top-level opening atom and its matching %(end) is evaluated

@@ -438,7 +438,7 @@ An example directly producing formatted text. Show the most recent

438 #!/bin/sh

439

440 git for-each-ref --count=3 --sort='-*authordate' \

441 ---format='From: %(*authorname) %(*authoremail)

441 +`--format='From: %(*authorname) %(*authoremail)

442 Subject: %(*subject)

443 Date: %(*authordate)

444 Ref: %(*refname)

@@ -449,7 +449,7 @@ Ref: %(*refname)

449

450

451 A simple example showing the use of shell eval on the output,

452 -demonstrating the use of --shell. List the prefixes of all heads:

452 +demonstrating the use of `--shell`. List the prefixes of all heads:

453

454 ------------

455 #!/bin/sh

@@ -517,7 +517,7 @@ eval "$eval"

517 ------------

518

519

520 -An example to show the usage of %(if)...%(then)...%(else)...%(end).

520 +An example to show the usage of `%(if)...%(then)...%(else)...%(end)`.

521 This prefixes the current branch with a star.

522

523 ------------

@@ -525,7 +525,7 @@ git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)"

525 ------------

526

527

528 -An example to show the usage of %(if)...%(then)...%(end).

528 +An example to show the usage of `%(if)...%(then)...%(end)`.

529 This prints the authorname, if present.

530

531 ------------

doc:git-for-each-ref: fix styling and typos