@matheusbsbs / matheus-bagliano / commits / d9d297a5f7

doc: git-log: convert rev list options to new doc format

- Fix some malformed synopis of options - Use _<placeholder>_ instead of <placeholder> in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. - Add the '%' sign to the characters of keywords. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Jean-Noël Avila committed Jul 7, 2025 at 18:53 UTC d9d297a5f7bef919658976087b740a1c31f653e7

3 files changed +198 -198

Documentation/asciidoc.conf.in

+1 -1

@@ -43,7 +43,7 @@ ifdef::doctype-book[]

43 endif::doctype-book[]

45 [literal-inlinemacro]

46 -{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}

46 +{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$%]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}

48 endif::backend-docbook[]

Documentation/asciidoctor-extensions.rb.in

+2 -2

@@ -73,7 +73,7 @@ module Git

73 elsif type == :monospaced

74 node.text.gsub(/(\.\.\.?)([^\]$\.])/, '<literal>\1</literal>\2')

75 .gsub(/^\.\.\.?$/, '<literal>\0</literal>')

76 - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*]+\.{0,2})+|,)}, '\1<literal>\2</literal>')

76 + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*%]+\.{0,2})+|,)}, '\1<literal>\2</literal>')

77 .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>')

78 else

79 open, close, supports_phrase = QUOTE_TAGS[type]

@@ -102,7 +102,7 @@ module Git

102 if node.type == :monospaced

103 node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')

104 .gsub(/^\.\.\.?$/, '<code>\0</code>')

105 - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>')

105 + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*%]+\.{0,2})+)}, '\1<code>\2</code>')

106 .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>')

107

108 else

Documentation/rev-list-options.adoc

+195 -195

@@ -6,60 +6,60 @@ special notations explained in the description, additional commit

6 limiting may be applied.

8 Using more options generally further limits the output (e.g.

9 -`--since=<date1>` limits to commits newer than `<date1>`, and using it

9 +`--since=<date1>` limits to commits newer than _<date1>_, and using it

10 with `--grep=<pattern>` further limits to commits whose log message

11 -has a line that matches `<pattern>`), unless otherwise noted.

11 +has a line that matches _<pattern>_), unless otherwise noted.

13 Note that these are applied before commit

14 ordering and formatting options, such as `--reverse`.

16 --<number>::

17 --n <number>::

18 ---max-count=<number>::

19 - Limit the number of commits to output.

16 +`-<number>`::

17 +`-n <number>`::

18 +`--max-count=<number>`::

19 + Limit the output to _<number>_ commits.

21 ---skip=<number>::

22 - Skip 'number' commits before starting to show the commit output.

21 +`--skip=<number>`::

22 + Skip _<number>_ commits before starting to show the commit output.

24 ---since=<date>::

25 ---after=<date>::

26 - Show commits more recent than a specific date.

24 +`--since=<date>`::

25 +`--after=<date>`::

26 + Show commits more recent than _<date>_.

28 ---since-as-filter=<date>::

29 - Show all commits more recent than a specific date. This visits

28 +`--since-as-filter=<date>`::

29 + Show all commits more recent than _<date>_. This visits

30 all commits in the range, rather than stopping at the first commit which

31 - is older than a specific date.

31 + is older than _<date>_.

33 ---until=<date>::

34 ---before=<date>::

35 - Show commits older than a specific date.

33 +`--until=<date>`::

34 +`--before=<date>`::

35 + Show commits older than _<date>_.

37 ifdef::git-rev-list[]

38 ---max-age=<timestamp>::

39 ---min-age=<timestamp>::

38 +`--max-age=<timestamp>`::

39 +`--min-age=<timestamp>`::

40 Limit the commits output to specified time range.

41 endif::git-rev-list[]

43 ---author=<pattern>::

44 ---committer=<pattern>::

43 +`--author=<pattern>`::

44 +`--committer=<pattern>`::

45 Limit the commits output to ones with author/committer

46 - header lines that match the specified pattern (regular

47 - expression). With more than one `--author=<pattern>`,

48 - commits whose author matches any of the given patterns are

46 + header lines that match the _<pattern>_ regular

47 + expression. With more than one `--author=<pattern>`,

48 + commits whose author matches any of the _<pattern>_ are

49 chosen (similarly for multiple `--committer=<pattern>`).

51 ---grep-reflog=<pattern>::

51 +`--grep-reflog=<pattern>`::

52 Limit the commits output to ones with reflog entries that

53 - match the specified pattern (regular expression). With

53 + match the _<pattern>_ regular expression. With

54 more than one `--grep-reflog`, commits whose reflog message

55 matches any of the given patterns are chosen. It is an

56 error to use this option unless `--walk-reflogs` is in use.

58 ---grep=<pattern>::

58 +`--grep=<pattern>`::

59 Limit the commits output to ones with a log message that

60 - matches the specified pattern (regular expression). With

60 + matches the _<pattern>_ regular expression. With

61 more than one `--grep=<pattern>`, commits whose message

62 - matches any of the given patterns are chosen (but see

62 + matches any of the _<pattern>_ are chosen (but see

63 `--all-match`).

64 ifndef::git-rev-list[]

65 +

@@ -67,35 +67,35 @@ When `--notes` is in effect, the message from the notes is

67 matched as if it were part of the log message.

68 endif::git-rev-list[]

70 ---all-match::

70 +`--all-match`::

71 Limit the commits output to ones that match all given `--grep`,

72 instead of ones that match at least one.

74 ---invert-grep::

74 +`--invert-grep`::

75 Limit the commits output to ones with a log message that do not

76 - match the pattern specified with `--grep=<pattern>`.

76 + match the _<pattern>_ specified with `--grep=<pattern>`.

78 --i::

79 ---regexp-ignore-case::

78 +`-i`::

79 +`--regexp-ignore-case`::

80 Match the regular expression limiting patterns without regard to letter

81 case.

83 ---basic-regexp::

83 +`--basic-regexp`::

84 Consider the limiting patterns to be basic regular expressions;

85 this is the default.

87 --E::

88 ---extended-regexp::

87 +`-E`::

88 +`--extended-regexp`::

89 Consider the limiting patterns to be extended regular expressions

90 instead of the default basic regular expressions.

92 --F::

93 ---fixed-strings::

92 +`-F`::

93 +`--fixed-strings`::

94 Consider the limiting patterns to be fixed strings (don't interpret

95 pattern as a regular expression).

97 --P::

98 ---perl-regexp::

97 +`-P`::

98 +`--perl-regexp`::

99 Consider the limiting patterns to be Perl-compatible regular

100 expressions.

101 +

@@ -103,20 +103,20 @@ Support for these types of regular expressions is an optional

103 compile-time dependency. If Git wasn't compiled with support for them

104 providing this option will cause it to die.

105

106 ---remove-empty::

106 +`--remove-empty`::

107 Stop when a given path disappears from the tree.

108

109 ---merges::

109 +`--merges`::

110 Print only merge commits. This is exactly the same as `--min-parents=2`.

111

112 ---no-merges::

112 +`--no-merges`::

113 Do not print commits with more than one parent. This is

114 exactly the same as `--max-parents=1`.

115

116 ---min-parents=<number>::

117 ---max-parents=<number>::

118 ---no-min-parents::

119 ---no-max-parents::

116 +`--min-parents=<number>`::

117 +`--max-parents=<number>`::

118 +`--no-min-parents`::

119 +`--no-max-parents`::

120 Show only commits which have at least (or at most) that many parent

121 commits. In particular, `--max-parents=1` is the same as `--no-merges`,

122 `--min-parents=2` is the same as `--merges`. `--max-parents=0`

@@ -126,7 +126,7 @@ providing this option will cause it to die.

126 again. Equivalent forms are `--min-parents=0` (any commit has 0 or more

127 parents) and `--max-parents=-1` (negative numbers denote no upper limit).

128

129 ---first-parent::

129 +`--first-parent`::

130 When finding commits to include, follow only the first

131 parent commit upon seeing a merge commit. This option

132 can give a better overview when viewing the evolution of

@@ -141,14 +141,14 @@ This option also changes default diff format for merge commits

141 to `first-parent`, see `--diff-merges=first-parent` for details.

142 endif::git-log[]

143

144 ---exclude-first-parent-only::

144 +`--exclude-first-parent-only`::

145 When finding commits to exclude (with a '{caret}'), follow only

146 the first parent commit upon seeing a merge commit.

147 This can be used to find the set of changes in a topic branch

148 from the point where it diverged from the remote branch, given

149 that arbitrary merges can be valid topic branch changes.

150

151 ---not::

151 +`--not`::

152 Reverses the meaning of the '{caret}' prefix (or lack thereof)

153 for all following revision specifiers, up to the next `--not`.

154 When used on the command line before --stdin, the revisions passed

@@ -156,37 +156,37 @@ endif::git-log[]

156 via standard input, the revisions passed on the command line will

157 not be affected by it.

158

159 ---all::

159 +`--all`::

160 Pretend as if all the refs in `refs/`, along with `HEAD`, are

161 - listed on the command line as '<commit>'.

161 + listed on the command line as _<commit>_.

162

163 ---branches[=<pattern>]::

163 +`--branches[=<pattern>]`::

164 Pretend as if all the refs in `refs/heads` are listed

165 - on the command line as '<commit>'. If '<pattern>' is given, limit

166 - branches to ones matching given shell glob. If pattern lacks '?',

165 + on the command line as _<commit>_. If _<pattern>_ is given, limit

166 + branches to ones matching given shell glob. If _<pattern>_ lacks '?',

167 '{asterisk}', or '[', '/{asterisk}' at the end is implied.

168

169 ---tags[=<pattern>]::

169 +`--tags[=<pattern>]`::

170 Pretend as if all the refs in `refs/tags` are listed

171 - on the command line as '<commit>'. If '<pattern>' is given, limit

171 + on the command line as _<commit>_. If _<pattern>_ is given, limit

172 tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}',

173 or '[', '/{asterisk}' at the end is implied.

174

175 ---remotes[=<pattern>]::

175 +`--remotes[=<pattern>]`::

176 Pretend as if all the refs in `refs/remotes` are listed

177 - on the command line as '<commit>'. If '<pattern>' is given, limit

177 + on the command line as _<commit>_. If _<pattern>_ is given, limit

178 remote-tracking branches to ones matching given shell glob.

179 If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied.

180

181 ---glob=<glob-pattern>::

182 - Pretend as if all the refs matching shell glob '<glob-pattern>'

183 - are listed on the command line as '<commit>'. Leading 'refs/',

181 +`--glob=<glob-pattern>`::

182 + Pretend as if all the refs matching shell glob _<glob-pattern>_

183 + are listed on the command line as _<commit>_. Leading 'refs/',

184 is automatically prepended if missing. If pattern lacks '?', '{asterisk}',

185 or '[', '/{asterisk}' at the end is implied.

186

187 ---exclude=<glob-pattern>::

187 +`--exclude=<glob-pattern>`::

188

189 - Do not include refs matching '<glob-pattern>' that the next `--all`,

189 + Do not include refs matching _<glob-pattern>_ that the next `--all`,

190 `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise

191 consider. Repetitions of this option accumulate exclusion patterns

192 up to the next `--all`, `--branches`, `--tags`, `--remotes`, or

@@ -199,7 +199,7 @@ respectively, and they must begin with `refs/` when applied to `--glob`

199 or `--all`. If a trailing '/{asterisk}' is intended, it must be given

200 explicitly.

201

202 ---exclude-hidden=[fetch|receive|uploadpack]::

202 +`--exclude-hidden=(fetch|receive|uploadpack)`::

203 Do not include refs that would be hidden by `git-fetch`,

204 `git-receive-pack` or `git-upload-pack` by consulting the appropriate

205 `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`

@@ -207,11 +207,11 @@ explicitly.

207 linkgit:git-config[1]). This option affects the next pseudo-ref option

208 `--all` or `--glob` and is cleared after processing them.

209

210 ---reflog::

210 +`--reflog`::

211 Pretend as if all objects mentioned by reflogs are listed on the

212 - command line as `<commit>`.

212 + command line as _<commit>_.

213

214 ---alternate-refs::

214 +`--alternate-refs`::

215 Pretend as if all objects mentioned as ref tips of alternate

216 repositories were listed on the command line. An alternate

217 repository is any repository whose object directory is specified

@@ -219,7 +219,7 @@ explicitly.

219 be modified by `core.alternateRefsCommand`, etc. See

220 linkgit:git-config[1].

221

222 ---single-worktree::

222 +`--single-worktree`::

223 By default, all working trees will be examined by the

224 following options when there are more than one (see

225 linkgit:git-worktree[1]): `--all`, `--reflog` and

@@ -227,19 +227,19 @@ explicitly.

227 This option forces them to examine the current working tree

228 only.

229

230 ---ignore-missing::

230 +`--ignore-missing`::

231 Upon seeing an invalid object name in the input, pretend as if

232 the bad input was not given.

233

234 ifndef::git-rev-list[]

235 ---bisect::

235 +`--bisect`::

236 Pretend as if the bad bisection ref `refs/bisect/bad`

237 was listed and as if it was followed by `--not` and the good

238 bisection refs `refs/bisect/good-*` on the command

239 line.

240 endif::git-rev-list[]

241

242 ---stdin::

242 +`--stdin`::

243 In addition to getting arguments from the command line, read

244 them from standard input as well. This accepts commits and

245 pseudo-options like `--all` and `--glob=`. When a `--` separator

@@ -249,15 +249,15 @@ endif::git-rev-list[]

249 influence any subsequent command line arguments.

250

251 ifdef::git-rev-list[]

252 ---quiet::

252 +`--quiet`::

253 Don't print anything to standard output. This form

254 is primarily meant to allow the caller to

255 test the exit status to see if a range of objects is fully

256 connected (or not). It is faster than redirecting stdout

257 to `/dev/null` as the output does not have to be formatted.

258

259 ---disk-usage::

260 ---disk-usage=human::

259 +`--disk-usage`::

260 +`--disk-usage=human`::

261 Suppress normal output; instead, print the sum of the bytes used

262 for on-disk storage by the selected commits or objects. This is

263 equivalent to piping the output into `git cat-file

@@ -269,11 +269,11 @@ ifdef::git-rev-list[]

269 in human-readable string(e.g. 12.24 Kib, 3.50 Mib).

270 endif::git-rev-list[]

271

272 ---cherry-mark::

272 +`--cherry-mark`::

273 Like `--cherry-pick` (see below) but mark equivalent commits

274 with `=` rather than omitting them, and inequivalent ones with `+`.

275

276 ---cherry-pick::

276 +`--cherry-pick`::

277 Omit any commit that introduces the same change as

278 another commit on the ``other side'' when the set of

279 commits are limited with symmetric difference.

@@ -286,8 +286,8 @@ cherry-picked from the other branch (for example, ``3rd on b'' may be

286 cherry-picked from branch A). With this option, such pairs of commits are

287 excluded from the output.

288

289 ---left-only::

290 ---right-only::

289 +`--left-only`::

290 +`--right-only`::

291 List only commits on the respective side of a symmetric difference,

292 i.e. only those which would be marked `<` resp. `>` by

293 `--left-right`.

@@ -298,20 +298,20 @@ commits from `B` which are in `A` or are patch-equivalent to a commit in

298 More precisely, `--cherry-pick --right-only --no-merges` gives the exact

299 list.

300

301 ---cherry::

301 +`--cherry`::

302 A synonym for `--right-only --cherry-mark --no-merges`; useful to

303 limit the output to the commits on our side and mark those that

304 have been applied to the other side of a forked history with

305 `git log --cherry upstream...mybranch`, similar to

306 `git cherry upstream mybranch`.

307

308 --g::

309 ---walk-reflogs::

308 +`-g`::

309 +`--walk-reflogs`::

310 Instead of walking the commit ancestry chain, walk

311 reflog entries from the most recent one to older ones.

312 When this option is used you cannot specify commits to

313 - exclude (that is, '{caret}commit', 'commit1..commit2',

314 - and 'commit1\...commit2' notations cannot be used).

313 + exclude (that is, `^<commit>`, `<commit1>..<commit2>`,

314 + and `<commit1>...<commit2>` notations cannot be used).

315 +

316 With `--pretty` format other than `oneline` and `reference` (for obvious reasons),

317 this causes the output to have two extra lines of information

@@ -340,29 +340,29 @@ See also linkgit:git-reflog[1].

340 +

341 Under `--pretty=reference`, this information will not be shown at all.

342

343 ---merge::

343 +`--merge`::

344 Show commits touching conflicted paths in the range `HEAD...<other>`,

345 where `<other>` is the first existing pseudoref in `MERGE_HEAD`,

346 `CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works

347 when the index has unmerged entries. This option can be used to show

348 relevant commits when resolving conflicts from a 3-way merge.

349

350 ---boundary::

350 +`--boundary`::

351 Output excluded boundary commits. Boundary commits are

352 prefixed with `-`.

353

354 ifdef::git-rev-list[]

355 ---use-bitmap-index::

355 +`--use-bitmap-index`::

356

357 Try to speed up the traversal using the pack bitmap index (if

358 one is available). Note that when traversing with `--objects`,

359 trees and blobs will not have their associated path printed.

360

361 ---progress=<header>::

361 +`--progress=<header>`::

362 Show progress reports on stderr as objects are considered. The

363 `<header>` text will be printed with each progress update.

364

365 --z::

365 +`-z`::

366 Instead of being newline-delimited, each outputted object and its

367 accompanying metadata is delimited using NUL bytes. Output is printed

368 in the following form:

@@ -397,56 +397,56 @@ is how to do it, as there are various strategies to simplify the history.

397

398 The following options select the commits to be shown:

399

400 -<paths>::

400 +`<paths>`::

401 Commits modifying the given <paths> are selected.

402

403 ---simplify-by-decoration::

403 +`--simplify-by-decoration`::

404 Commits that are referred by some branch or tag are selected.

405

406 Note that extra commits can be shown to give a meaningful history.

407

408 The following options affect the way the simplification is performed:

409

410 -Default mode::

410 +`Default mode`::

411 Simplifies the history to the simplest history explaining the

412 final state of the tree. Simplest because it prunes some side

413 branches if the end result is the same (i.e. merging branches

414 with the same content)

415

416 ---show-pulls::

416 +`--show-pulls`::

417 Include all commits from the default mode, but also any merge

418 commits that are not TREESAME to the first parent but are

419 TREESAME to a later parent. This mode is helpful for showing

420 the merge commits that "first introduced" a change to a branch.

421

422 ---full-history::

422 +`--full-history`::

423 Same as the default mode, but does not prune some history.

424

425 ---dense::

425 +`--dense`::

426 Only the selected commits are shown, plus some to have a

427 meaningful history.

428

429 ---sparse::

429 +`--sparse`::

430 All commits in the simplified history are shown.

431

432 ---simplify-merges::

432 +`--simplify-merges`::

433 Additional option to `--full-history` to remove some needless

434 merges from the resulting history, as there are no selected

435 commits contributing to this merge.

436

437 ---ancestry-path[=<commit>]::

438 - When given a range of commits to display (e.g. 'commit1..commit2'

439 - or 'commit2 {caret}commit1'), and a commit <commit> in that range,

437 +`--ancestry-path[=<commit>]`::

438 + When given a range of commits to display (e.g. `<commit1>..<commit2>`

439 + or `<commit2> ^<commit1>`), and a commit _<commit>_ in that range,

440 only display commits in that range

441 - that are ancestors of <commit>, descendants of <commit>, or

442 - <commit> itself. If no commit is specified, use 'commit1' (the

443 - excluded part of the range) as <commit>. Can be passed multiple

441 + that are ancestors of _<commit>_, descendants of _<commit>_, or

442 + _<commit>_ itself. If no commit is specified, use _<commit1>_ (the

443 + excluded part of the range) as _<commit>_. Can be passed multiple

444 times; if so, a commit is included if it is any of the commits

445 given or if it is an ancestor or descendant of one of them.

446

447 A more detailed explanation follows.

448

449 -Suppose you specified `foo` as the <paths>. We shall call commits

449 +Suppose you specified `foo` as the _<paths>_. We shall call commits

450 that modify `foo` !TREESAME, and the rest TREESAME. (In a diff

451 filtered for `foo`, they look different and equal, respectively.)

452

@@ -466,22 +466,22 @@ The horizontal line of history A---Q is taken to be the first parent of

466 each merge. The commits are:

467

468 * `I` is the initial commit, in which `foo` exists with contents

469 - ``asdf'', and a file `quux` exists with contents ``quux''. Initial

469 + `asdf`, and a file `quux` exists with contents `quux`. Initial

470 commits are compared to an empty tree, so `I` is !TREESAME.

471

472 -* In `A`, `foo` contains just ``foo''.

472 +* In `A`, `foo` contains just `foo`.

473

474 * `B` contains the same change as `A`. Its merge `M` is trivial and

475 hence TREESAME to all parents.

476

477 -* `C` does not change `foo`, but its merge `N` changes it to ``foobar'',

477 +* `C` does not change `foo`, but its merge `N` changes it to `foobar`,

478 so it is not TREESAME to any parent.

479

480 -* `D` sets `foo` to ``baz''. Its merge `O` combines the strings from

481 - `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent.

480 +* `D` sets `foo` to `baz`. Its merge `O` combines the strings from

481 + `N` and `D` to `foobarbaz`; i.e., it is not TREESAME to any parent.

482

483 -* `E` changes `quux` to ``xyzzy'', and its merge `P` combines the

484 - strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`.

483 +* `E` changes `quux` to `xyzzy`, and its merge `P` combines the

484 + strings to `quux xyzzy`. `P` is TREESAME to `O`, but not to `E`.

485

486 * `X` is an independent root commit that added a new file `side`, and `Y`

487 modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and

@@ -517,7 +517,7 @@ Parent/child relations are only visible with `--parents`, but that does

517 not affect the commits selected in default mode, so we have shown the

518 parent lines.

519

520 ---full-history without parent rewriting::

520 +`--full-history` without parent rewriting::

521 This mode differs from the default in one point: always follow

522 all parents of a merge, even if it is TREESAME to one of them.

523 Even if more than one side of the merge has commits that are

@@ -536,7 +536,7 @@ Note that without parent rewriting, it is not really possible to talk

536 about the parent/child relationships between the commits, so we show

537 them disconnected.

538

539 ---full-history with parent rewriting::

539 +`--full-history` with parent rewriting::

540 Ordinary commits are only included if they are !TREESAME

541 (though this can be changed, see `--sparse` below).

542 +

@@ -560,18 +560,18 @@ rewritten to contain `E`'s parent `I`. The same happened for `C` and

560 In addition to the above settings, you can change whether TREESAME

561 affects inclusion:

562

563 ---dense::

563 +`--dense`::

564 Commits that are walked are included if they are not TREESAME

565 to any parent.

566

567 ---sparse::

567 +`--sparse`::

568 All commits that are walked are included.

569 +

570 Note that without `--full-history`, this still simplifies merges: if

571 one of the parents is TREESAME, we follow only that one, so the other

572 sides of the merge are never walked.

573

574 ---simplify-merges::

574 +`--simplify-merges`::

575 First, build a history graph in the same way that

576 `--full-history` with parent rewriting does (see above).

577 +

@@ -618,9 +618,9 @@ Note the major differences in `N`, `P`, and `Q` over `--full-history`:

618

619 There is another simplification mode available:

620

621 ---ancestry-path[=<commit>]::

621 +`--ancestry-path[=<commit>]`::

622 Limit the displayed commits to those which are an ancestor of

623 - <commit>, or which are a descendant of <commit>, or are <commit>

623 + _<commit>_, or which are a descendant of _<commit>_, or are _<commit>_

624 itself.

625 +

626 As an example use case, consider the following commit history:

@@ -636,15 +636,15 @@ As an example use case, consider the following commit history:

636 A regular 'D..M' computes the set of commits that are ancestors of `M`,

637 but excludes the ones that are ancestors of `D`. This is useful to see

638 what happened to the history leading to `M` since `D`, in the sense

639 -that ``what does `M` have that did not exist in `D`''. The result in this

639 +that "what does `M` have that did not exist in `D`". The result in this

640 example would be all the commits, except `A` and `B` (and `D` itself,

641 of course).

642 +

643 When we want to find out what commits in `M` are contaminated with the

644 bug introduced by `D` and need fixing, however, we might want to view

645 -only the subset of 'D..M' that are actually descendants of `D`, i.e.

645 +only the subset of `D..M` that are actually descendants of `D`, i.e.

646 excluding `C` and `K`. This is exactly what the `--ancestry-path`

647 -option does. Applied to the 'D..M' range, it results in:

647 +option does. Applied to the `D..M` range, it results in:

648 +

649 -----------------------------------------------------------------------

650 E-------F

@@ -655,7 +655,7 @@ option does. Applied to the 'D..M' range, it results in:

655 -----------------------------------------------------------------------

656 +

657 We can also use `--ancestry-path=D` instead of `--ancestry-path` which

658 -means the same thing when applied to the 'D..M' range but is just more

658 +means the same thing when applied to the `D..M` range but is just more

659 explicit.

660 +

661 If we instead are interested in a given topic within this range, and all

@@ -770,7 +770,7 @@ into the important branch. This commit may have information about why

770 the change `X` came to override the changes from `A` and `B` in its

771 commit message.

772

773 ---show-pulls::

773 +`--show-pulls`::

774 In addition to the commits shown in the default history, show

775 each merge commit that is not TREESAME to its first parent but

776 is TREESAME to a later parent.

@@ -819,7 +819,7 @@ ifdef::git-rev-list[]

819 Bisection Helpers

820 ~~~~~~~~~~~~~~~~~

821

822 ---bisect::

822 +`--bisect`::

823 Limit output to the one commit object which is roughly halfway between

824 included and excluded commits. Note that the bad bisection ref

825 `refs/bisect/bad` is added to the included commits (if it

@@ -843,7 +843,7 @@ introduces a regression is thus reduced to a binary search: repeatedly

843 generate and test new 'midpoint's until the commit chain is of length

844 one.

845

846 ---bisect-vars::

846 +`--bisect-vars`::

847 This calculates the same as `--bisect`, except that refs in

848 `refs/bisect/` are not used, and except that this outputs

849 text ready to be eval'ed by the shell. These lines will assign the

@@ -855,7 +855,7 @@ one.

855 `bisect_bad`, and the number of commits we are bisecting right now to

856 `bisect_all`.

857

858 ---bisect-all::

858 +`--bisect-all`::

859 This outputs all the commit objects between the included and excluded

860 commits, ordered by their distance to the included and excluded

861 commits. Refs in `refs/bisect/` are not used. The farthest

@@ -878,15 +878,15 @@ Commit Ordering

878

879 By default, the commits are shown in reverse chronological order.

880

881 ---date-order::

881 +`--date-order`::

882 Show no parents before all of its children are shown, but

883 otherwise show commits in the commit timestamp order.

884

885 ---author-date-order::

885 +`--author-date-order`::

886 Show no parents before all of its children are shown, but

887 otherwise show commits in the author timestamp order.

888

889 ---topo-order::

889 +`--topo-order`::

890 Show no parents before all of its children are shown, and

891 avoid showing commits on multiple lines of history

892 intermixed.

@@ -910,8 +910,8 @@ With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5

910 avoid showing the commits from two parallel development track mixed

911 together.

912

913 ---reverse::

914 - Output the commits chosen to be shown (see Commit Limiting

913 +`--reverse`::

914 + Output the commits chosen to be shown (see 'Commit Limiting'

915 section above) in reverse order. Cannot be combined with

916 `--walk-reflogs`.

917 endif::git-shortlog[]

@@ -923,39 +923,39 @@ Object Traversal

923 These options are mostly targeted for packing of Git repositories.

924

925 ifdef::git-rev-list[]

926 ---objects::

926 +`--objects`::

927 Print the object IDs of any object referenced by the listed

928 - commits. `--objects foo ^bar` thus means ``send me

928 + commits. `--objects foo ^bar` thus means "send me

929 all object IDs which I need to download if I have the commit

930 - object _bar_ but not _foo_''. See also `--object-names` below.

930 + object `bar` but not `foo`". See also `--object-names` below.

931

932 ---in-commit-order::

932 +`--in-commit-order`::

933 Print tree and blob ids in order of the commits. The tree

934 and blob ids are printed after they are first referenced

935 by a commit.

936

937 ---objects-edge::

937 +`--objects-edge`::

938 Similar to `--objects`, but also print the IDs of excluded

939 - commits prefixed with a ``-'' character. This is used by

939 + commits prefixed with a "`-`" character. This is used by

940 linkgit:git-pack-objects[1] to build a ``thin'' pack, which records

941 objects in deltified form based on objects contained in these

942 excluded commits to reduce network traffic.

943

944 ---objects-edge-aggressive::

944 +`--objects-edge-aggressive`::

945 Similar to `--objects-edge`, but it tries harder to find excluded

946 commits at the cost of increased time. This is used instead of

947 `--objects-edge` to build ``thin'' packs for shallow repositories.

948

949 ---indexed-objects::

949 +`--indexed-objects`::

950 Pretend as if all trees and blobs used by the index are listed

951 on the command line. Note that you probably want to use

952 `--objects`, too.

953

954 ---unpacked::

954 +`--unpacked`::

955 Only useful with `--objects`; print the object IDs that are not

956 in packs.

957

958 ---object-names::

958 +`--object-names`::

959 Only useful with `--objects`; print the names of the object IDs

960 that are found. This is the default behavior. Note that the

961 "name" of each object is ambiguous, and mostly intended as a

@@ -964,52 +964,52 @@ ifdef::git-rev-list[]

964 to remove newlines; and if an object would appear multiple times

965 with different names, only one name is shown.

966

967 ---no-object-names::

967 +`--no-object-names`::

968 Only useful with `--objects`; does not print the names of the object

969 IDs that are found. This inverts `--object-names`. This flag allows

970 the output to be more easily parsed by commands such as

971 linkgit:git-cat-file[1].

972

973 ---filter=<filter-spec>::

973 +`--filter=<filter-spec>`::

974 Only useful with one of the `--objects*`; omits objects (usually

975 - blobs) from the list of printed objects. The '<filter-spec>'

975 + blobs) from the list of printed objects. The _<filter-spec>_

976 may be one of the following:

977 +

978 -The form '--filter=blob:none' omits all blobs.

978 +The form `--filter=blob:none` omits all blobs.

979 +

980 -The form '--filter=blob:limit=<n>[kmg]' omits blobs of size at least n

981 -bytes or units. n may be zero. The suffixes k, m, and g can be used

982 -to name units in KiB, MiB, or GiB. For example, 'blob:limit=1k'

980 +The form `--filter=blob:limit=<n>[kmg]` omits blobs of size at least _<n>_

981 +bytes or units. _<n>_ may be zero. The suffixes `k`, `m`, and `g` can be used

982 +to name units in KiB, MiB, or GiB. For example, `blob:limit=1k`

983 is the same as 'blob:limit=1024'.

984 +

985 -The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects

985 +The form `--filter=object:type=(tag|commit|tree|blob)` omits all objects

986 which are not of the requested type.

987 +

988 -The form '--filter=sparse:oid=<blob-ish>' uses a sparse-checkout

989 -specification contained in the blob (or blob-expression) '<blob-ish>'

988 +The form `--filter=sparse:oid=<blob-ish>` uses a sparse-checkout

989 +specification contained in the blob (or blob-expression) _<blob-ish>_

990 to omit blobs that would not be required for a sparse checkout on

991 the requested refs.

992 +

993 -The form '--filter=tree:<depth>' omits all blobs and trees whose depth

994 -from the root tree is >= <depth> (minimum depth if an object is located

995 -at multiple depths in the commits traversed). <depth>=0 will not include

993 +The form `--filter=tree:<depth>` omits all blobs and trees whose depth

994 +from the root tree is >= _<depth>_ (minimum depth if an object is located

995 +at multiple depths in the commits traversed). _<depth>_=0 will not include

996 any trees or blobs unless included explicitly in the command-line (or

997 -standard input when --stdin is used). <depth>=1 will include only the

997 +standard input when `--stdin` is used). _<depth>_=1 will include only the

998 tree and blobs which are referenced directly by a commit reachable from

999 -<commit> or an explicitly-given object. <depth>=2 is like <depth>=1

999 +_<commit>_ or an explicitly-given object. _<depth>_=2 is like <depth>=1

1000 while also including trees and blobs one more level removed from an

1001 explicitly-given commit or tree.

1002 +

1003 -Note that the form '--filter=sparse:path=<path>' that wants to read

1003 +Note that the form `--filter=sparse:path=<path>` that wants to read

1004 from an arbitrary path on the filesystem has been dropped for security

1005 reasons.

1006 +

1007 -Multiple '--filter=' flags can be specified to combine filters. Only

1007 +Multiple `--filter=` flags can be specified to combine filters. Only

1008 objects which are accepted by every filter are included.

1009 +

1010 -The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be

1010 +The form `--filter=combine:<filter1>+<filter2>+...<filterN>` can also be

1011 used to combined several filters, but this is harder than just repeating

1012 -the '--filter' flag and is usually not necessary. Filters are joined by

1012 +the `--filter` flag and is usually not necessary. Filters are joined by

1013 '{plus}' and individual filters are %-encoded (i.e. URL-encoded).

1014 Besides the '{plus}' and '%' characters, the following characters are

1015 reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+'`+

@@ -1017,52 +1017,52 @@ as well as all characters with ASCII code <= `0x20`, which includes

1017 space and newline.

1018 +

1019 Other arbitrary characters can also be encoded. For instance,

1020 -'combine:tree:3+blob:none' and 'combine:tree%3A3+blob%3Anone' are

1020 +`combine:tree:3+blob:none` and `combine:tree%3A3+blob%3Anone` are

1021 equivalent.

1022

1023 ---no-filter::

1023 +`--no-filter`::

1024 Turn off any previous `--filter=` argument.

1025

1026 ---filter-provided-objects::

1026 +`--filter-provided-objects`::

1027 Filter the list of explicitly provided objects, which would otherwise

1028 always be printed even if they did not match any of the filters. Only

1029 useful with `--filter=`.

1030

1031 ---filter-print-omitted::

1031 +`--filter-print-omitted`::

1032 Only useful with `--filter=`; prints a list of the objects omitted

1033 by the filter. Object IDs are prefixed with a ``~'' character.

1034

1035 ---missing=<missing-action>::

1035 +`--missing=<missing-action>`::

1036 A debug option to help with future "partial clone" development.

1037 This option specifies how missing objects are handled.

1038 +

1039 -The form '--missing=error' requests that rev-list stop with an error if

1039 +The form `--missing=error` requests that rev-list stop with an error if

1040 a missing object is encountered. This is the default action.

1041 +

1042 -The form '--missing=allow-any' will allow object traversal to continue

1042 +The form `--missing=allow-any` will allow object traversal to continue

1043 if a missing object is encountered. Missing objects will silently be

1044 omitted from the results.

1045 +

1046 -The form '--missing=allow-promisor' is like 'allow-any', but will only

1046 +The form `--missing=allow-promisor` is like `allow-any`, but will only

1047 allow object traversal to continue for EXPECTED promisor missing objects.

1048 Unexpected missing objects will raise an error.

1049 +

1050 -The form '--missing=print' is like 'allow-any', but will also print a

1050 +The form `--missing=print` is like `allow-any`, but will also print a

1051 list of the missing objects. Object IDs are prefixed with a ``?'' character.

1052 +

1053 -The form '--missing=print-info' is like 'print', but will also print additional

1053 +The form `--missing=print-info` is like `print`, but will also print additional

1054 information about the missing object inferred from its containing object. The

1055 information is all printed on the same line with the missing object ID in the

1056 form: `?<oid> [<token>=<value>]...`. The `<token>=<value>` pairs containing

1057 -additional information are separated from each other by a SP. The value is

1058 -encoded in a token specific fashion, but SP or LF contained in value are always

1057 +additional information are separated from each other by a _SP_. The value is

1058 +encoded in a token specific fashion, but _SP_ or _LF_ contained in value are always

1059 expected to be represented in such a way that the resulting encoded value does

1060 not have either of these two problematic bytes. Each `<token>=<value>` may be

1061 one of the following:

1062 +

1063 --

1064 * The `path=<path>` shows the path of the missing object inferred from a

1065 - containing object. A path containing SP or special characters is enclosed in

1065 + containing object. A path containing _SP_ or special characters is enclosed in

1066 double-quotes in the C style as needed.

1067 +

1068 * The `type=<type>` shows the type of the missing object inferred from a

@@ -1073,7 +1073,7 @@ If some tips passed to the traversal are missing, they will be

1073 considered as missing too, and the traversal will ignore them. In case

1074 we cannot get their Object ID though, an error will be raised.

1075

1076 ---exclude-promisor-objects::

1076 +`--exclude-promisor-objects`::

1077 (For internal use only.) Prefilter object traversal at

1078 promisor boundary. This is used with partial clone. This is

1079 stronger than `--missing=allow-promisor` because it limits the

@@ -1081,7 +1081,7 @@ we cannot get their Object ID though, an error will be raised.

1081 objects.

1082 endif::git-rev-list[]

1083

1084 ---no-walk[=(sorted|unsorted)]::

1084 +`--no-walk[=(sorted|unsorted)]`::

1085 Only show the given commits, but do not traverse their ancestors.

1086 This has no effect if a range is specified. If the argument

1087 `unsorted` is given, the commits are shown in the order they were

@@ -1090,7 +1090,7 @@ endif::git-rev-list[]

1090 by commit time.

1091 Cannot be combined with `--graph`.

1092

1093 ---do-walk::

1093 +`--do-walk`::

1094 Overrides a previous `--no-walk`.

1095 endif::git-shortlog[]

1096

@@ -1106,10 +1106,10 @@ endif::git-rev-list[]

1106

1107 include::pretty-options.adoc[]

1108

1109 ---relative-date::

1109 +`--relative-date`::

1110 Synonym for `--date=relative`.

1111

1112 ---date=<format>::

1112 +`--date=<format>`::

1113 Only takes effect for dates shown in human-readable format, such

1114 as when using `--pretty`. `log.date` config variable sets a default

1115 value for the log command's `--date` option. By default, dates

@@ -1159,12 +1159,12 @@ omitted.

1159 1970). As with `--raw`, this is always in UTC and therefore `-local`

1160 has no effect.

1161

1162 -`--date=format:...` feeds the format `...` to your system `strftime`,

1163 -except for %s, %z, and %Z, which are handled internally.

1162 +`--date=format:<format>` feeds the _<format>_ to your system `strftime`,

1163 +except for `%s`, `%z`, and `%Z`, which are handled internally.

1164 Use `--date=format:%c` to show the date in your system locale's

1165 -preferred format. See the `strftime` manual for a complete list of

1165 +preferred format. See the `strftime`(3) manual for a complete list of

1166 format placeholders. When using `-local`, the correct syntax is

1167 -`--date=format-local:...`.

1167 +`--date=format-local:<format>`.

1168

1169 `--date=default` is the default format, and is based on ctime(3)

1170 output. It shows a single line with three-letter day of the week,

@@ -1174,33 +1174,33 @@ the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`.

1174 --

1175

1176 ifdef::git-rev-list[]

1177 ---header::

1177 +`--header`::

1178 Print the contents of the commit in raw-format; each record is

1179 separated with a NUL character.

1180

1181 ---no-commit-header::

1181 +`--no-commit-header`::

1182 Suppress the header line containing "commit" and the object ID printed before

1183 the specified format. This has no effect on the built-in formats; only custom

1184 formats are affected.

1185

1186 ---commit-header::

1186 +`--commit-header`::

1187 Overrides a previous `--no-commit-header`.

1188 endif::git-rev-list[]

1189

1190 ---parents::

1190 +`--parents`::

1191 Print also the parents of the commit (in the form "commit parent...").

1192 Also enables parent rewriting, see 'History Simplification' above.

1193

1194 ---children::

1194 +`--children`::

1195 Print also the children of the commit (in the form "commit child...").

1196 Also enables parent rewriting, see 'History Simplification' above.

1197

1198 ifdef::git-rev-list[]

1199 ---timestamp::

1199 +`--timestamp`::

1200 Print the raw commit timestamp.

1201 endif::git-rev-list[]

1202

1203 ---left-right::

1203 +`--left-right`::

1204 Mark which side of a symmetric difference a commit is reachable from.

1205 Commits from the left side are prefixed with `<` and those from

1206 the right with `>`. If combined with `--boundary`, those

@@ -1229,7 +1229,7 @@ you would get an output like this:

1229 -xxxxxxx... 1st on a

1230 -----------------------------------------------------------------------

1231

1232 ---graph::

1232 +`--graph`::

1233 Draw a text-based graphical representation of the commit history

1234 on the left hand side of the output. This may cause extra lines

1235 to be printed in between commits, in order for the graph history

@@ -1241,15 +1241,15 @@ This enables parent rewriting, see 'History Simplification' above.

1241 This implies the `--topo-order` option by default, but the

1242 `--date-order` option may also be specified.

1243

1244 ---show-linear-break[=<barrier>]::

1245 - When --graph is not used, all history branches are flattened

1244 +`--show-linear-break[=<barrier>]`::

1245 + When `--graph` is not used, all history branches are flattened

1246 which can make it hard to see that the two consecutive commits

1247 do not belong to a linear branch. This option puts a barrier

1248 - in between them in that case. If `<barrier>` is specified, it

1248 + in between them in that case. If _<barrier>_ is specified, it

1249 is the string that will be shown instead of the default one.

1250

1251 ifdef::git-rev-list[]

1252 ---count::

1252 +`--count`::

1253 Print a number stating how many commits would have been

1254 listed, and suppress all other output. When used together

1255 with `--left-right`, instead print the counts for left and