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

+1 -1

Documentation/asciidoc.conf.in

··· 43 43 endif::doctype-book[] 44 44 45 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])))} 47 47 48 48 endif::backend-docbook[] 49 49

+2 -2

Documentation/asciidoctor-extensions.rb.in

··· 73 73 elsif type == :monospaced 74 74 node.text.gsub(/(\.\.\.?)([^\]$\.])/, '<literal>\1</literal>\2') 75 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 77 .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>') 78 78 else 79 79 open, close, supports_phrase = QUOTE_TAGS[type] ··· 102 102 if node.type == :monospaced 103 103 node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2') 104 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 106 .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>') 107 107 108 108 else

+195 -195

Documentation/rev-list-options.adoc

··· 6 6 limiting may be applied. 7 7 8 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 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. 12 12 13 13 Note that these are applied before commit 14 14 ordering and formatting options, such as `--reverse`. 15 15 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. 20 20 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. 23 23 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>_. 27 27 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 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>_. 32 32 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>_. 36 36 37 37 ifdef::git-rev-list[] 38 - --max-age=<timestamp>:: 39 - --min-age=<timestamp>:: 38 + `--max-age=<timestamp>`:: 39 + `--min-age=<timestamp>`:: 40 40 Limit the commits output to specified time range. 41 41 endif::git-rev-list[] 42 42 43 - --author=<pattern>:: 44 - --committer=<pattern>:: 43 + `--author=<pattern>`:: 44 + `--committer=<pattern>`:: 45 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 49 chosen (similarly for multiple `--committer=<pattern>`). 50 50 51 - --grep-reflog=<pattern>:: 51 + `--grep-reflog=<pattern>`:: 52 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 54 more than one `--grep-reflog`, commits whose reflog message 55 55 matches any of the given patterns are chosen. It is an 56 56 error to use this option unless `--walk-reflogs` is in use. 57 57 58 - --grep=<pattern>:: 58 + `--grep=<pattern>`:: 59 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 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 63 `--all-match`). 64 64 ifndef::git-rev-list[] 65 65 + ··· 67 67 matched as if it were part of the log message. 68 68 endif::git-rev-list[] 69 69 70 - --all-match:: 70 + `--all-match`:: 71 71 Limit the commits output to ones that match all given `--grep`, 72 72 instead of ones that match at least one. 73 73 74 - --invert-grep:: 74 + `--invert-grep`:: 75 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>`. 77 77 78 - -i:: 79 - --regexp-ignore-case:: 78 + `-i`:: 79 + `--regexp-ignore-case`:: 80 80 Match the regular expression limiting patterns without regard to letter 81 81 case. 82 82 83 - --basic-regexp:: 83 + `--basic-regexp`:: 84 84 Consider the limiting patterns to be basic regular expressions; 85 85 this is the default. 86 86 87 - -E:: 88 - --extended-regexp:: 87 + `-E`:: 88 + `--extended-regexp`:: 89 89 Consider the limiting patterns to be extended regular expressions 90 90 instead of the default basic regular expressions. 91 91 92 - -F:: 93 - --fixed-strings:: 92 + `-F`:: 93 + `--fixed-strings`:: 94 94 Consider the limiting patterns to be fixed strings (don't interpret 95 95 pattern as a regular expression). 96 96 97 - -P:: 98 - --perl-regexp:: 97 + `-P`:: 98 + `--perl-regexp`:: 99 99 Consider the limiting patterns to be Perl-compatible regular 100 100 expressions. 101 101 + ··· 103 103 compile-time dependency. If Git wasn't compiled with support for them 104 104 providing this option will cause it to die. 105 105 106 - --remove-empty:: 106 + `--remove-empty`:: 107 107 Stop when a given path disappears from the tree. 108 108 109 - --merges:: 109 + `--merges`:: 110 110 Print only merge commits. This is exactly the same as `--min-parents=2`. 111 111 112 - --no-merges:: 112 + `--no-merges`:: 113 113 Do not print commits with more than one parent. This is 114 114 exactly the same as `--max-parents=1`. 115 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 120 Show only commits which have at least (or at most) that many parent 121 121 commits. In particular, `--max-parents=1` is the same as `--no-merges`, 122 122 `--min-parents=2` is the same as `--merges`. `--max-parents=0` ··· 126 126 again. Equivalent forms are `--min-parents=0` (any commit has 0 or more 127 127 parents) and `--max-parents=-1` (negative numbers denote no upper limit). 128 128 129 - --first-parent:: 129 + `--first-parent`:: 130 130 When finding commits to include, follow only the first 131 131 parent commit upon seeing a merge commit. This option 132 132 can give a better overview when viewing the evolution of ··· 141 141 to `first-parent`, see `--diff-merges=first-parent` for details. 142 142 endif::git-log[] 143 143 144 - --exclude-first-parent-only:: 144 + `--exclude-first-parent-only`:: 145 145 When finding commits to exclude (with a '{caret}'), follow only 146 146 the first parent commit upon seeing a merge commit. 147 147 This can be used to find the set of changes in a topic branch 148 148 from the point where it diverged from the remote branch, given 149 149 that arbitrary merges can be valid topic branch changes. 150 150 151 - --not:: 151 + `--not`:: 152 152 Reverses the meaning of the '{caret}' prefix (or lack thereof) 153 153 for all following revision specifiers, up to the next `--not`. 154 154 When used on the command line before --stdin, the revisions passed ··· 156 156 via standard input, the revisions passed on the command line will 157 157 not be affected by it. 158 158 159 - --all:: 159 + `--all`:: 160 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 162 163 - --branches[=<pattern>]:: 163 + `--branches[=<pattern>]`:: 164 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 167 '{asterisk}', or '[', '/{asterisk}' at the end is implied. 168 168 169 - --tags[=<pattern>]:: 169 + `--tags[=<pattern>]`:: 170 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 172 tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', 173 173 or '[', '/{asterisk}' at the end is implied. 174 174 175 - --remotes[=<pattern>]:: 175 + `--remotes[=<pattern>]`:: 176 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 178 remote-tracking branches to ones matching given shell glob. 179 179 If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. 180 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 184 is automatically prepended if missing. If pattern lacks '?', '{asterisk}', 185 185 or '[', '/{asterisk}' at the end is implied. 186 186 187 - --exclude=<glob-pattern>:: 187 + `--exclude=<glob-pattern>`:: 188 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 190 `--branches`, `--tags`, `--remotes`, or `--glob` would otherwise 191 191 consider. Repetitions of this option accumulate exclusion patterns 192 192 up to the next `--all`, `--branches`, `--tags`, `--remotes`, or ··· 199 199 or `--all`. If a trailing '/{asterisk}' is intended, it must be given 200 200 explicitly. 201 201 202 - --exclude-hidden=[fetch|receive|uploadpack]:: 202 + `--exclude-hidden=(fetch|receive|uploadpack)`:: 203 203 Do not include refs that would be hidden by `git-fetch`, 204 204 `git-receive-pack` or `git-upload-pack` by consulting the appropriate 205 205 `fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs` ··· 207 207 linkgit:git-config[1]). This option affects the next pseudo-ref option 208 208 `--all` or `--glob` and is cleared after processing them. 209 209 210 - --reflog:: 210 + `--reflog`:: 211 211 Pretend as if all objects mentioned by reflogs are listed on the 212 - command line as `<commit>`. 212 + command line as _<commit>_. 213 213 214 - --alternate-refs:: 214 + `--alternate-refs`:: 215 215 Pretend as if all objects mentioned as ref tips of alternate 216 216 repositories were listed on the command line. An alternate 217 217 repository is any repository whose object directory is specified ··· 219 219 be modified by `core.alternateRefsCommand`, etc. See 220 220 linkgit:git-config[1]. 221 221 222 - --single-worktree:: 222 + `--single-worktree`:: 223 223 By default, all working trees will be examined by the 224 224 following options when there are more than one (see 225 225 linkgit:git-worktree[1]): `--all`, `--reflog` and ··· 227 227 This option forces them to examine the current working tree 228 228 only. 229 229 230 - --ignore-missing:: 230 + `--ignore-missing`:: 231 231 Upon seeing an invalid object name in the input, pretend as if 232 232 the bad input was not given. 233 233 234 234 ifndef::git-rev-list[] 235 - --bisect:: 235 + `--bisect`:: 236 236 Pretend as if the bad bisection ref `refs/bisect/bad` 237 237 was listed and as if it was followed by `--not` and the good 238 238 bisection refs `refs/bisect/good-*` on the command 239 239 line. 240 240 endif::git-rev-list[] 241 241 242 - --stdin:: 242 + `--stdin`:: 243 243 In addition to getting arguments from the command line, read 244 244 them from standard input as well. This accepts commits and 245 245 pseudo-options like `--all` and `--glob=`. When a `--` separator ··· 249 249 influence any subsequent command line arguments. 250 250 251 251 ifdef::git-rev-list[] 252 - --quiet:: 252 + `--quiet`:: 253 253 Don't print anything to standard output. This form 254 254 is primarily meant to allow the caller to 255 255 test the exit status to see if a range of objects is fully 256 256 connected (or not). It is faster than redirecting stdout 257 257 to `/dev/null` as the output does not have to be formatted. 258 258 259 - --disk-usage:: 260 - --disk-usage=human:: 259 + `--disk-usage`:: 260 + `--disk-usage=human`:: 261 261 Suppress normal output; instead, print the sum of the bytes used 262 262 for on-disk storage by the selected commits or objects. This is 263 263 equivalent to piping the output into `git cat-file ··· 269 269 in human-readable string(e.g. 12.24 Kib, 3.50 Mib). 270 270 endif::git-rev-list[] 271 271 272 - --cherry-mark:: 272 + `--cherry-mark`:: 273 273 Like `--cherry-pick` (see below) but mark equivalent commits 274 274 with `=` rather than omitting them, and inequivalent ones with `+`. 275 275 276 - --cherry-pick:: 276 + `--cherry-pick`:: 277 277 Omit any commit that introduces the same change as 278 278 another commit on the ``other side'' when the set of 279 279 commits are limited with symmetric difference. ··· 286 286 cherry-picked from branch A). With this option, such pairs of commits are 287 287 excluded from the output. 288 288 289 - --left-only:: 290 - --right-only:: 289 + `--left-only`:: 290 + `--right-only`:: 291 291 List only commits on the respective side of a symmetric difference, 292 292 i.e. only those which would be marked `<` resp. `>` by 293 293 `--left-right`. ··· 298 298 More precisely, `--cherry-pick --right-only --no-merges` gives the exact 299 299 list. 300 300 301 - --cherry:: 301 + `--cherry`:: 302 302 A synonym for `--right-only --cherry-mark --no-merges`; useful to 303 303 limit the output to the commits on our side and mark those that 304 304 have been applied to the other side of a forked history with 305 305 `git log --cherry upstream...mybranch`, similar to 306 306 `git cherry upstream mybranch`. 307 307 308 - -g:: 309 - --walk-reflogs:: 308 + `-g`:: 309 + `--walk-reflogs`:: 310 310 Instead of walking the commit ancestry chain, walk 311 311 reflog entries from the most recent one to older ones. 312 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 315 + 316 316 With `--pretty` format other than `oneline` and `reference` (for obvious reasons), 317 317 this causes the output to have two extra lines of information ··· 340 340 + 341 341 Under `--pretty=reference`, this information will not be shown at all. 342 342 343 - --merge:: 343 + `--merge`:: 344 344 Show commits touching conflicted paths in the range `HEAD...<other>`, 345 345 where `<other>` is the first existing pseudoref in `MERGE_HEAD`, 346 346 `CHERRY_PICK_HEAD`, `REVERT_HEAD` or `REBASE_HEAD`. Only works 347 347 when the index has unmerged entries. This option can be used to show 348 348 relevant commits when resolving conflicts from a 3-way merge. 349 349 350 - --boundary:: 350 + `--boundary`:: 351 351 Output excluded boundary commits. Boundary commits are 352 352 prefixed with `-`. 353 353 354 354 ifdef::git-rev-list[] 355 - --use-bitmap-index:: 355 + `--use-bitmap-index`:: 356 356 357 357 Try to speed up the traversal using the pack bitmap index (if 358 358 one is available). Note that when traversing with `--objects`, 359 359 trees and blobs will not have their associated path printed. 360 360 361 - --progress=<header>:: 361 + `--progress=<header>`:: 362 362 Show progress reports on stderr as objects are considered. The 363 363 `<header>` text will be printed with each progress update. 364 364 365 - -z:: 365 + `-z`:: 366 366 Instead of being newline-delimited, each outputted object and its 367 367 accompanying metadata is delimited using NUL bytes. Output is printed 368 368 in the following form: ··· 397 397 398 398 The following options select the commits to be shown: 399 399 400 - <paths>:: 400 + `<paths>`:: 401 401 Commits modifying the given <paths> are selected. 402 402 403 - --simplify-by-decoration:: 403 + `--simplify-by-decoration`:: 404 404 Commits that are referred by some branch or tag are selected. 405 405 406 406 Note that extra commits can be shown to give a meaningful history. 407 407 408 408 The following options affect the way the simplification is performed: 409 409 410 - Default mode:: 410 + `Default mode`:: 411 411 Simplifies the history to the simplest history explaining the 412 412 final state of the tree. Simplest because it prunes some side 413 413 branches if the end result is the same (i.e. merging branches 414 414 with the same content) 415 415 416 - --show-pulls:: 416 + `--show-pulls`:: 417 417 Include all commits from the default mode, but also any merge 418 418 commits that are not TREESAME to the first parent but are 419 419 TREESAME to a later parent. This mode is helpful for showing 420 420 the merge commits that "first introduced" a change to a branch. 421 421 422 - --full-history:: 422 + `--full-history`:: 423 423 Same as the default mode, but does not prune some history. 424 424 425 - --dense:: 425 + `--dense`:: 426 426 Only the selected commits are shown, plus some to have a 427 427 meaningful history. 428 428 429 - --sparse:: 429 + `--sparse`:: 430 430 All commits in the simplified history are shown. 431 431 432 - --simplify-merges:: 432 + `--simplify-merges`:: 433 433 Additional option to `--full-history` to remove some needless 434 434 merges from the resulting history, as there are no selected 435 435 commits contributing to this merge. 436 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 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 444 times; if so, a commit is included if it is any of the commits 445 445 given or if it is an ancestor or descendant of one of them. 446 446 447 447 A more detailed explanation follows. 448 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 450 that modify `foo` !TREESAME, and the rest TREESAME. (In a diff 451 451 filtered for `foo`, they look different and equal, respectively.) 452 452 ··· 466 466 each merge. The commits are: 467 467 468 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 470 commits are compared to an empty tree, so `I` is !TREESAME. 471 471 472 - * In `A`, `foo` contains just ``foo''. 472 + * In `A`, `foo` contains just `foo`. 473 473 474 474 * `B` contains the same change as `A`. Its merge `M` is trivial and 475 475 hence TREESAME to all parents. 476 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 478 so it is not TREESAME to any parent. 479 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 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 485 486 486 * `X` is an independent root commit that added a new file `side`, and `Y` 487 487 modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and ··· 517 517 not affect the commits selected in default mode, so we have shown the 518 518 parent lines. 519 519 520 - --full-history without parent rewriting:: 520 + `--full-history` without parent rewriting:: 521 521 This mode differs from the default in one point: always follow 522 522 all parents of a merge, even if it is TREESAME to one of them. 523 523 Even if more than one side of the merge has commits that are ··· 536 536 about the parent/child relationships between the commits, so we show 537 537 them disconnected. 538 538 539 - --full-history with parent rewriting:: 539 + `--full-history` with parent rewriting:: 540 540 Ordinary commits are only included if they are !TREESAME 541 541 (though this can be changed, see `--sparse` below). 542 542 + ··· 560 560 In addition to the above settings, you can change whether TREESAME 561 561 affects inclusion: 562 562 563 - --dense:: 563 + `--dense`:: 564 564 Commits that are walked are included if they are not TREESAME 565 565 to any parent. 566 566 567 - --sparse:: 567 + `--sparse`:: 568 568 All commits that are walked are included. 569 569 + 570 570 Note that without `--full-history`, this still simplifies merges: if 571 571 one of the parents is TREESAME, we follow only that one, so the other 572 572 sides of the merge are never walked. 573 573 574 - --simplify-merges:: 574 + `--simplify-merges`:: 575 575 First, build a history graph in the same way that 576 576 `--full-history` with parent rewriting does (see above). 577 577 + ··· 618 618 619 619 There is another simplification mode available: 620 620 621 - --ancestry-path[=<commit>]:: 621 + `--ancestry-path[=<commit>]`:: 622 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 624 itself. 625 625 + 626 626 As an example use case, consider the following commit history: ··· 636 636 A regular 'D..M' computes the set of commits that are ancestors of `M`, 637 637 but excludes the ones that are ancestors of `D`. This is useful to see 638 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 640 example would be all the commits, except `A` and `B` (and `D` itself, 641 641 of course). 642 642 + 643 643 When we want to find out what commits in `M` are contaminated with the 644 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 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 648 + 649 649 ----------------------------------------------------------------------- 650 650 E-------F ··· 655 655 ----------------------------------------------------------------------- 656 656 + 657 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 659 explicit. 660 660 + 661 661 If we instead are interested in a given topic within this range, and all ··· 770 770 the change `X` came to override the changes from `A` and `B` in its 771 771 commit message. 772 772 773 - --show-pulls:: 773 + `--show-pulls`:: 774 774 In addition to the commits shown in the default history, show 775 775 each merge commit that is not TREESAME to its first parent but 776 776 is TREESAME to a later parent. ··· 819 819 Bisection Helpers 820 820 ~~~~~~~~~~~~~~~~~ 821 821 822 - --bisect:: 822 + `--bisect`:: 823 823 Limit output to the one commit object which is roughly halfway between 824 824 included and excluded commits. Note that the bad bisection ref 825 825 `refs/bisect/bad` is added to the included commits (if it ··· 843 843 generate and test new 'midpoint's until the commit chain is of length 844 844 one. 845 845 846 - --bisect-vars:: 846 + `--bisect-vars`:: 847 847 This calculates the same as `--bisect`, except that refs in 848 848 `refs/bisect/` are not used, and except that this outputs 849 849 text ready to be eval'ed by the shell. These lines will assign the ··· 855 855 `bisect_bad`, and the number of commits we are bisecting right now to 856 856 `bisect_all`. 857 857 858 - --bisect-all:: 858 + `--bisect-all`:: 859 859 This outputs all the commit objects between the included and excluded 860 860 commits, ordered by their distance to the included and excluded 861 861 commits. Refs in `refs/bisect/` are not used. The farthest ··· 878 878 879 879 By default, the commits are shown in reverse chronological order. 880 880 881 - --date-order:: 881 + `--date-order`:: 882 882 Show no parents before all of its children are shown, but 883 883 otherwise show commits in the commit timestamp order. 884 884 885 - --author-date-order:: 885 + `--author-date-order`:: 886 886 Show no parents before all of its children are shown, but 887 887 otherwise show commits in the author timestamp order. 888 888 889 - --topo-order:: 889 + `--topo-order`:: 890 890 Show no parents before all of its children are shown, and 891 891 avoid showing commits on multiple lines of history 892 892 intermixed. ··· 910 910 avoid showing the commits from two parallel development track mixed 911 911 together. 912 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 915 section above) in reverse order. Cannot be combined with 916 916 `--walk-reflogs`. 917 917 endif::git-shortlog[] ··· 923 923 These options are mostly targeted for packing of Git repositories. 924 924 925 925 ifdef::git-rev-list[] 926 - --objects:: 926 + `--objects`:: 927 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 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 931 932 - --in-commit-order:: 932 + `--in-commit-order`:: 933 933 Print tree and blob ids in order of the commits. The tree 934 934 and blob ids are printed after they are first referenced 935 935 by a commit. 936 936 937 - --objects-edge:: 937 + `--objects-edge`:: 938 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 940 linkgit:git-pack-objects[1] to build a ``thin'' pack, which records 941 941 objects in deltified form based on objects contained in these 942 942 excluded commits to reduce network traffic. 943 943 944 - --objects-edge-aggressive:: 944 + `--objects-edge-aggressive`:: 945 945 Similar to `--objects-edge`, but it tries harder to find excluded 946 946 commits at the cost of increased time. This is used instead of 947 947 `--objects-edge` to build ``thin'' packs for shallow repositories. 948 948 949 - --indexed-objects:: 949 + `--indexed-objects`:: 950 950 Pretend as if all trees and blobs used by the index are listed 951 951 on the command line. Note that you probably want to use 952 952 `--objects`, too. 953 953 954 - --unpacked:: 954 + `--unpacked`:: 955 955 Only useful with `--objects`; print the object IDs that are not 956 956 in packs. 957 957 958 - --object-names:: 958 + `--object-names`:: 959 959 Only useful with `--objects`; print the names of the object IDs 960 960 that are found. This is the default behavior. Note that the 961 961 "name" of each object is ambiguous, and mostly intended as a ··· 964 964 to remove newlines; and if an object would appear multiple times 965 965 with different names, only one name is shown. 966 966 967 - --no-object-names:: 967 + `--no-object-names`:: 968 968 Only useful with `--objects`; does not print the names of the object 969 969 IDs that are found. This inverts `--object-names`. This flag allows 970 970 the output to be more easily parsed by commands such as 971 971 linkgit:git-cat-file[1]. 972 972 973 - --filter=<filter-spec>:: 973 + `--filter=<filter-spec>`:: 974 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 976 may be one of the following: 977 977 + 978 - The form '--filter=blob:none' omits all blobs. 978 + The form `--filter=blob:none` omits all blobs. 979 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 983 is the same as 'blob:limit=1024'. 984 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 986 which are not of the requested type. 987 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 990 to omit blobs that would not be required for a sparse checkout on 991 991 the requested refs. 992 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 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 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 1000 while also including trees and blobs one more level removed from an 1001 1001 explicitly-given commit or tree. 1002 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 1004 from an arbitrary path on the filesystem has been dropped for security 1005 1005 reasons. 1006 1006 + 1007 - Multiple '--filter=' flags can be specified to combine filters. Only 1007 + Multiple `--filter=` flags can be specified to combine filters. Only 1008 1008 objects which are accepted by every filter are included. 1009 1009 + 1010 - The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be 1010 + The form `--filter=combine:<filter1>+<filter2>+...<filterN>` can also be 1011 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 1013 '{plus}' and individual filters are %-encoded (i.e. URL-encoded). 1014 1014 Besides the '{plus}' and '%' characters, the following characters are 1015 1015 reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+'`+ ··· 1017 1017 space and newline. 1018 1018 + 1019 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 1021 equivalent. 1022 1022 1023 - --no-filter:: 1023 + `--no-filter`:: 1024 1024 Turn off any previous `--filter=` argument. 1025 1025 1026 - --filter-provided-objects:: 1026 + `--filter-provided-objects`:: 1027 1027 Filter the list of explicitly provided objects, which would otherwise 1028 1028 always be printed even if they did not match any of the filters. Only 1029 1029 useful with `--filter=`. 1030 1030 1031 - --filter-print-omitted:: 1031 + `--filter-print-omitted`:: 1032 1032 Only useful with `--filter=`; prints a list of the objects omitted 1033 1033 by the filter. Object IDs are prefixed with a ``~'' character. 1034 1034 1035 - --missing=<missing-action>:: 1035 + `--missing=<missing-action>`:: 1036 1036 A debug option to help with future "partial clone" development. 1037 1037 This option specifies how missing objects are handled. 1038 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 1040 a missing object is encountered. This is the default action. 1041 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 1043 if a missing object is encountered. Missing objects will silently be 1044 1044 omitted from the results. 1045 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 1047 allow object traversal to continue for EXPECTED promisor missing objects. 1048 1048 Unexpected missing objects will raise an error. 1049 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 1051 list of the missing objects. Object IDs are prefixed with a ``?'' character. 1052 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 1054 information about the missing object inferred from its containing object. The 1055 1055 information is all printed on the same line with the missing object ID in the 1056 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 1059 expected to be represented in such a way that the resulting encoded value does 1060 1060 not have either of these two problematic bytes. Each `<token>=<value>` may be 1061 1061 one of the following: 1062 1062 + 1063 1063 -- 1064 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 1066 double-quotes in the C style as needed. 1067 1067 + 1068 1068 * The `type=<type>` shows the type of the missing object inferred from a ··· 1073 1073 considered as missing too, and the traversal will ignore them. In case 1074 1074 we cannot get their Object ID though, an error will be raised. 1075 1075 1076 - --exclude-promisor-objects:: 1076 + `--exclude-promisor-objects`:: 1077 1077 (For internal use only.) Prefilter object traversal at 1078 1078 promisor boundary. This is used with partial clone. This is 1079 1079 stronger than `--missing=allow-promisor` because it limits the ··· 1081 1081 objects. 1082 1082 endif::git-rev-list[] 1083 1083 1084 - --no-walk[=(sorted|unsorted)]:: 1084 + `--no-walk[=(sorted|unsorted)]`:: 1085 1085 Only show the given commits, but do not traverse their ancestors. 1086 1086 This has no effect if a range is specified. If the argument 1087 1087 `unsorted` is given, the commits are shown in the order they were ··· 1090 1090 by commit time. 1091 1091 Cannot be combined with `--graph`. 1092 1092 1093 - --do-walk:: 1093 + `--do-walk`:: 1094 1094 Overrides a previous `--no-walk`. 1095 1095 endif::git-shortlog[] 1096 1096 ··· 1106 1106 1107 1107 include::pretty-options.adoc[] 1108 1108 1109 - --relative-date:: 1109 + `--relative-date`:: 1110 1110 Synonym for `--date=relative`. 1111 1111 1112 - --date=<format>:: 1112 + `--date=<format>`:: 1113 1113 Only takes effect for dates shown in human-readable format, such 1114 1114 as when using `--pretty`. `log.date` config variable sets a default 1115 1115 value for the log command's `--date` option. By default, dates ··· 1159 1159 1970). As with `--raw`, this is always in UTC and therefore `-local` 1160 1160 has no effect. 1161 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 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 1166 format placeholders. When using `-local`, the correct syntax is 1167 - `--date=format-local:...`. 1167 + `--date=format-local:<format>`. 1168 1168 1169 1169 `--date=default` is the default format, and is based on ctime(3) 1170 1170 output. It shows a single line with three-letter day of the week, ··· 1174 1174 -- 1175 1175 1176 1176 ifdef::git-rev-list[] 1177 - --header:: 1177 + `--header`:: 1178 1178 Print the contents of the commit in raw-format; each record is 1179 1179 separated with a NUL character. 1180 1180 1181 - --no-commit-header:: 1181 + `--no-commit-header`:: 1182 1182 Suppress the header line containing "commit" and the object ID printed before 1183 1183 the specified format. This has no effect on the built-in formats; only custom 1184 1184 formats are affected. 1185 1185 1186 - --commit-header:: 1186 + `--commit-header`:: 1187 1187 Overrides a previous `--no-commit-header`. 1188 1188 endif::git-rev-list[] 1189 1189 1190 - --parents:: 1190 + `--parents`:: 1191 1191 Print also the parents of the commit (in the form "commit parent..."). 1192 1192 Also enables parent rewriting, see 'History Simplification' above. 1193 1193 1194 - --children:: 1194 + `--children`:: 1195 1195 Print also the children of the commit (in the form "commit child..."). 1196 1196 Also enables parent rewriting, see 'History Simplification' above. 1197 1197 1198 1198 ifdef::git-rev-list[] 1199 - --timestamp:: 1199 + `--timestamp`:: 1200 1200 Print the raw commit timestamp. 1201 1201 endif::git-rev-list[] 1202 1202 1203 - --left-right:: 1203 + `--left-right`:: 1204 1204 Mark which side of a symmetric difference a commit is reachable from. 1205 1205 Commits from the left side are prefixed with `<` and those from 1206 1206 the right with `>`. If combined with `--boundary`, those ··· 1229 1229 -xxxxxxx... 1st on a 1230 1230 ----------------------------------------------------------------------- 1231 1231 1232 - --graph:: 1232 + `--graph`:: 1233 1233 Draw a text-based graphical representation of the commit history 1234 1234 on the left hand side of the output. This may cause extra lines 1235 1235 to be printed in between commits, in order for the graph history ··· 1241 1241 This implies the `--topo-order` option by default, but the 1242 1242 `--date-order` option may also be specified. 1243 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 1246 which can make it hard to see that the two consecutive commits 1247 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 1249 is the string that will be shown instead of the default one. 1250 1250 1251 1251 ifdef::git-rev-list[] 1252 - --count:: 1252 + `--count`:: 1253 1253 Print a number stating how many commits would have been 1254 1254 listed, and suppress all other output. When used together 1255 1255 with `--left-right`, instead print the counts for left and