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

+1 -1

Documentation/asciidoc.conf.in

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

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

+2 -2

Documentation/asciidoctor-extensions.rb.in

··· 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>') 77 .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>') 78 else 79 open, close, supports_phrase = QUOTE_TAGS[type] ··· 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>') 106 .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>') 107 108 else

··· 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>') 77 .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>') 78 else 79 open, close, supports_phrase = QUOTE_TAGS[type] ··· 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>') 106 .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>') 107 108 else

+195 -195

Documentation/rev-list-options.adoc

··· 6 limiting may be applied. 7 8 Using more options generally further limits the output (e.g. 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. 12 13 Note that these are applied before commit 14 ordering and formatting options, such as `--reverse`. 15 16 - -<number>:: 17 - -n <number>:: 18 - --max-count=<number>:: 19 - Limit the number of commits to output. 20 21 - --skip=<number>:: 22 - Skip 'number' commits before starting to show the commit output. 23 24 - --since=<date>:: 25 - --after=<date>:: 26 - Show commits more recent than a specific date. 27 28 - --since-as-filter=<date>:: 29 - Show all commits more recent than a specific date. This visits 30 all commits in the range, rather than stopping at the first commit which 31 - is older than a specific date. 32 33 - --until=<date>:: 34 - --before=<date>:: 35 - Show commits older than a specific date. 36 37 ifdef::git-rev-list[] 38 - --max-age=<timestamp>:: 39 - --min-age=<timestamp>:: 40 Limit the commits output to specified time range. 41 endif::git-rev-list[] 42 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 49 chosen (similarly for multiple `--committer=<pattern>`). 50 51 - --grep-reflog=<pattern>:: 52 Limit the commits output to ones with reflog entries that 53 - match the specified 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. 57 58 - --grep=<pattern>:: 59 Limit the commits output to ones with a log message that 60 - matches the specified pattern (regular expression). With 61 more than one `--grep=<pattern>`, commits whose message 62 - matches any of the given patterns are chosen (but see 63 `--all-match`). 64 ifndef::git-rev-list[] 65 + ··· 67 matched as if it were part of the log message. 68 endif::git-rev-list[] 69 70 - --all-match:: 71 Limit the commits output to ones that match all given `--grep`, 72 instead of ones that match at least one. 73 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>`. 77 78 - -i:: 79 - --regexp-ignore-case:: 80 Match the regular expression limiting patterns without regard to letter 81 case. 82 83 - --basic-regexp:: 84 Consider the limiting patterns to be basic regular expressions; 85 this is the default. 86 87 - -E:: 88 - --extended-regexp:: 89 Consider the limiting patterns to be extended regular expressions 90 instead of the default basic regular expressions. 91 92 - -F:: 93 - --fixed-strings:: 94 Consider the limiting patterns to be fixed strings (don't interpret 95 pattern as a regular expression). 96 97 - -P:: 98 - --perl-regexp:: 99 Consider the limiting patterns to be Perl-compatible regular 100 expressions. 101 + ··· 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:: 107 Stop when a given path disappears from the tree. 108 109 - --merges:: 110 Print only merge commits. This is exactly the same as `--min-parents=2`. 111 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:: 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 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:: 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 to `first-parent`, see `--diff-merges=first-parent` for details. 142 endif::git-log[] 143 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:: 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 via standard input, the revisions passed on the command line will 157 not be affected by it. 158 159 - --all:: 160 Pretend as if all the refs in `refs/`, along with `HEAD`, are 161 - listed on the command line as '<commit>'. 162 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 '?', 167 '{asterisk}', or '[', '/{asterisk}' at the end is implied. 168 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 172 tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', 173 or '[', '/{asterisk}' at the end is implied. 174 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 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/', 184 is automatically prepended if missing. If pattern lacks '?', '{asterisk}', 185 or '[', '/{asterisk}' at the end is implied. 186 187 - --exclude=<glob-pattern>:: 188 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 or `--all`. If a trailing '/{asterisk}' is intended, it must be given 200 explicitly. 201 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 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:: 211 Pretend as if all objects mentioned by reflogs are listed on the 212 - command line as `<commit>`. 213 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 be modified by `core.alternateRefsCommand`, etc. See 220 linkgit:git-config[1]. 221 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 This option forces them to examine the current working tree 228 only. 229 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:: 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:: 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 influence any subsequent command line arguments. 250 251 ifdef::git-rev-list[] 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:: 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 in human-readable string(e.g. 12.24 Kib, 3.50 Mib). 270 endif::git-rev-list[] 271 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:: 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 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:: 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 More precisely, `--cherry-pick --right-only --no-merges` gives the exact 299 list. 300 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:: 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). 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 + 341 Under `--pretty=reference`, this information will not be shown at all. 342 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:: 351 Output excluded boundary commits. Boundary commits are 352 prefixed with `-`. 353 354 ifdef::git-rev-list[] 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>:: 362 Show progress reports on stderr as objects are considered. The 363 `<header>` text will be printed with each progress update. 364 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 398 The following options select the commits to be shown: 399 400 - <paths>:: 401 Commits modifying the given <paths> are selected. 402 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:: 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:: 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:: 423 Same as the default mode, but does not prune some history. 424 425 - --dense:: 426 Only the selected commits are shown, plus some to have a 427 meaningful history. 428 429 - --sparse:: 430 All commits in the simplified history are shown. 431 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, 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 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 450 that modify `foo` !TREESAME, and the rest TREESAME. (In a diff 451 filtered for `foo`, they look different and equal, respectively.) 452 ··· 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 470 commits are compared to an empty tree, so `I` is !TREESAME. 471 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'', 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. 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`. 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 not affect the commits selected in default mode, so we have shown the 518 parent lines. 519 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 about the parent/child relationships between the commits, so we show 537 them disconnected. 538 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 In addition to the above settings, you can change whether TREESAME 561 affects inclusion: 562 563 - --dense:: 564 Commits that are walked are included if they are not TREESAME 565 to any parent. 566 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:: 575 First, build a history graph in the same way that 576 `--full-history` with parent rewriting does (see above). 577 + ··· 618 619 There is another simplification mode available: 620 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> 624 itself. 625 + 626 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 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. 646 excluding `C` and `K`. This is exactly what the `--ancestry-path` 647 - option does. Applied to the 'D..M' range, it results in: 648 + 649 ----------------------------------------------------------------------- 650 E-------F ··· 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 659 explicit. 660 + 661 If we instead are interested in a given topic within this range, and all ··· 770 the change `X` came to override the changes from `A` and `B` in its 771 commit message. 772 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 Bisection Helpers 820 ~~~~~~~~~~~~~~~~~ 821 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 generate and test new 'midpoint's until the commit chain is of length 844 one. 845 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 `bisect_bad`, and the number of commits we are bisecting right now to 856 `bisect_all`. 857 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 879 By default, the commits are shown in reverse chronological order. 880 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:: 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:: 890 Show no parents before all of its children are shown, and 891 avoid showing commits on multiple lines of history 892 intermixed. ··· 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 915 section above) in reverse order. Cannot be combined with 916 `--walk-reflogs`. 917 endif::git-shortlog[] ··· 923 These options are mostly targeted for packing of Git repositories. 924 925 ifdef::git-rev-list[] 926 - --objects:: 927 Print the object IDs of any object referenced by the listed 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. 931 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:: 938 Similar to `--objects`, but also print the IDs of excluded 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:: 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:: 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:: 955 Only useful with `--objects`; print the object IDs that are not 956 in packs. 957 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 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:: 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>:: 974 Only useful with one of the `--objects*`; omits objects (usually 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. 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' 983 is the same as 'blob:limit=1024'. 984 + 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>' 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 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 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 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 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 1008 objects which are accepted by every filter are included. 1009 + 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 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 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 1021 equivalent. 1022 1023 - --no-filter:: 1024 Turn off any previous `--filter=` argument. 1025 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:: 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>:: 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 1040 a missing object is encountered. This is the default action. 1041 + 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 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 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 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 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 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 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:: 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 objects. 1082 endif::git-rev-list[] 1083 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 by commit time. 1091 Cannot be combined with `--graph`. 1092 1093 - --do-walk:: 1094 Overrides a previous `--no-walk`. 1095 endif::git-shortlog[] 1096 ··· 1106 1107 include::pretty-options.adoc[] 1108 1109 - --relative-date:: 1110 Synonym for `--date=relative`. 1111 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 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. 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 1166 format placeholders. When using `-local`, the correct syntax is 1167 - `--date=format-local:...`. 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 -- 1175 1176 ifdef::git-rev-list[] 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:: 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:: 1187 Overrides a previous `--no-commit-header`. 1188 endif::git-rev-list[] 1189 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:: 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:: 1200 Print the raw commit timestamp. 1201 endif::git-rev-list[] 1202 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 -xxxxxxx... 1st on a 1230 ----------------------------------------------------------------------- 1231 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 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 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 1249 is the string that will be shown instead of the default one. 1250 1251 ifdef::git-rev-list[] 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

··· 6 limiting may be applied. 7 8 Using more options generally further limits the output (e.g. 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. 12 13 Note that these are applied before commit 14 ordering and formatting options, such as `--reverse`. 15 16 + `-<number>`:: 17 + `-n <number>`:: 18 + `--max-count=<number>`:: 19 + Limit the output to _<number>_ commits. 20 21 + `--skip=<number>`:: 22 + Skip _<number>_ commits before starting to show the commit output. 23 24 + `--since=<date>`:: 25 + `--after=<date>`:: 26 + Show commits more recent than _<date>_. 27 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 _<date>_. 32 33 + `--until=<date>`:: 34 + `--before=<date>`:: 35 + Show commits older than _<date>_. 36 37 ifdef::git-rev-list[] 38 + `--max-age=<timestamp>`:: 39 + `--min-age=<timestamp>`:: 40 Limit the commits output to specified time range. 41 endif::git-rev-list[] 42 43 + `--author=<pattern>`:: 44 + `--committer=<pattern>`:: 45 Limit the commits output to ones with author/committer 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>`). 50 51 + `--grep-reflog=<pattern>`:: 52 Limit the commits output to ones with reflog entries that 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. 57 58 + `--grep=<pattern>`:: 59 Limit the commits output to ones with a log message that 60 + matches the _<pattern>_ regular expression. With 61 more than one `--grep=<pattern>`, commits whose message 62 + matches any of the _<pattern>_ are chosen (but see 63 `--all-match`). 64 ifndef::git-rev-list[] 65 + ··· 67 matched as if it were part of the log message. 68 endif::git-rev-list[] 69 70 + `--all-match`:: 71 Limit the commits output to ones that match all given `--grep`, 72 instead of ones that match at least one. 73 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>`. 77 78 + `-i`:: 79 + `--regexp-ignore-case`:: 80 Match the regular expression limiting patterns without regard to letter 81 case. 82 83 + `--basic-regexp`:: 84 Consider the limiting patterns to be basic regular expressions; 85 this is the default. 86 87 + `-E`:: 88 + `--extended-regexp`:: 89 Consider the limiting patterns to be extended regular expressions 90 instead of the default basic regular expressions. 91 92 + `-F`:: 93 + `--fixed-strings`:: 94 Consider the limiting patterns to be fixed strings (don't interpret 95 pattern as a regular expression). 96 97 + `-P`:: 98 + `--perl-regexp`:: 99 Consider the limiting patterns to be Perl-compatible regular 100 expressions. 101 + ··· 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`:: 107 Stop when a given path disappears from the tree. 108 109 + `--merges`:: 110 Print only merge commits. This is exactly the same as `--min-parents=2`. 111 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`:: 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 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`:: 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 to `first-parent`, see `--diff-merges=first-parent` for details. 142 endif::git-log[] 143 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`:: 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 via standard input, the revisions passed on the command line will 157 not be affected by it. 158 159 + `--all`:: 160 Pretend as if all the refs in `refs/`, along with `HEAD`, are 161 + listed on the command line as _<commit>_. 162 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 '?', 167 '{asterisk}', or '[', '/{asterisk}' at the end is implied. 168 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 172 tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', 173 or '[', '/{asterisk}' at the end is implied. 174 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 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/', 184 is automatically prepended if missing. If pattern lacks '?', '{asterisk}', 185 or '[', '/{asterisk}' at the end is implied. 186 187 + `--exclude=<glob-pattern>`:: 188 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 or `--all`. If a trailing '/{asterisk}' is intended, it must be given 200 explicitly. 201 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 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`:: 211 Pretend as if all objects mentioned by reflogs are listed on the 212 + command line as _<commit>_. 213 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 be modified by `core.alternateRefsCommand`, etc. See 220 linkgit:git-config[1]. 221 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 This option forces them to examine the current working tree 228 only. 229 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`:: 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`:: 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 influence any subsequent command line arguments. 250 251 ifdef::git-rev-list[] 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`:: 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 in human-readable string(e.g. 12.24 Kib, 3.50 Mib). 270 endif::git-rev-list[] 271 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`:: 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 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`:: 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 More precisely, `--cherry-pick --right-only --no-merges` gives the exact 299 list. 300 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`:: 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, `^<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 + 341 Under `--pretty=reference`, this information will not be shown at all. 342 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`:: 351 Output excluded boundary commits. Boundary commits are 352 prefixed with `-`. 353 354 ifdef::git-rev-list[] 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>`:: 362 Show progress reports on stderr as objects are considered. The 363 `<header>` text will be printed with each progress update. 364 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 398 The following options select the commits to be shown: 399 400 + `<paths>`:: 401 Commits modifying the given <paths> are selected. 402 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`:: 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`:: 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`:: 423 Same as the default mode, but does not prune some history. 424 425 + `--dense`:: 426 Only the selected commits are shown, plus some to have a 427 meaningful history. 428 429 + `--sparse`:: 430 All commits in the simplified history are shown. 431 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> ^<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 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 450 that modify `foo` !TREESAME, and the rest TREESAME. (In a diff 451 filtered for `foo`, they look different and equal, respectively.) 452 ··· 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 470 commits are compared to an empty tree, so `I` is !TREESAME. 471 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`, 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. 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`. 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 not affect the commits selected in default mode, so we have shown the 518 parent lines. 519 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 about the parent/child relationships between the commits, so we show 537 them disconnected. 538 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 In addition to the above settings, you can change whether TREESAME 561 affects inclusion: 562 563 + `--dense`:: 564 Commits that are walked are included if they are not TREESAME 565 to any parent. 566 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`:: 575 First, build a history graph in the same way that 576 `--full-history` with parent rewriting does (see above). 577 + ··· 618 619 There is another simplification mode available: 620 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>_ 624 itself. 625 + 626 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 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. 646 excluding `C` and `K`. This is exactly what the `--ancestry-path` 647 + option does. Applied to the `D..M` range, it results in: 648 + 649 ----------------------------------------------------------------------- 650 E-------F ··· 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 659 explicit. 660 + 661 If we instead are interested in a given topic within this range, and all ··· 770 the change `X` came to override the changes from `A` and `B` in its 771 commit message. 772 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 Bisection Helpers 820 ~~~~~~~~~~~~~~~~~ 821 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 generate and test new 'midpoint's until the commit chain is of length 844 one. 845 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 `bisect_bad`, and the number of commits we are bisecting right now to 856 `bisect_all`. 857 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 879 By default, the commits are shown in reverse chronological order. 880 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`:: 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`:: 890 Show no parents before all of its children are shown, and 891 avoid showing commits on multiple lines of history 892 intermixed. ··· 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' 915 section above) in reverse order. Cannot be combined with 916 `--walk-reflogs`. 917 endif::git-shortlog[] ··· 923 These options are mostly targeted for packing of Git repositories. 924 925 ifdef::git-rev-list[] 926 + `--objects`:: 927 Print the object IDs of any object referenced by the listed 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. 931 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`:: 938 Similar to `--objects`, but also print the IDs of excluded 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`:: 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`:: 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`:: 955 Only useful with `--objects`; print the object IDs that are not 956 in packs. 957 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 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`:: 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>`:: 974 Only useful with one of the `--objects*`; omits objects (usually 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. 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` 983 is the same as 'blob:limit=1024'. 984 + 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>_ 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 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 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 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 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 1008 objects which are accepted by every filter are included. 1009 + 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 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 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 1021 equivalent. 1022 1023 + `--no-filter`:: 1024 Turn off any previous `--filter=` argument. 1025 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`:: 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>`:: 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 1040 a missing object is encountered. This is the default action. 1041 + 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 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 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 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 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 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 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`:: 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 objects. 1082 endif::git-rev-list[] 1083 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 by commit time. 1091 Cannot be combined with `--graph`. 1092 1093 + `--do-walk`:: 1094 Overrides a previous `--no-walk`. 1095 endif::git-shortlog[] 1096 ··· 1106 1107 include::pretty-options.adoc[] 1108 1109 + `--relative-date`:: 1110 Synonym for `--date=relative`. 1111 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 1970). As with `--raw`, this is always in UTC and therefore `-local` 1160 has no effect. 1161 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`(3) manual for a complete list of 1166 format placeholders. When using `-local`, the correct syntax is 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 -- 1175 1176 ifdef::git-rev-list[] 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`:: 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`:: 1187 Overrides a previous `--no-commit-header`. 1188 endif::git-rev-list[] 1189 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`:: 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`:: 1200 Print the raw commit timestamp. 1201 endif::git-rev-list[] 1202 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 -xxxxxxx... 1st on a 1230 ----------------------------------------------------------------------- 1231 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 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 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 1249 is the string that will be shown instead of the default one. 1250 1251 ifdef::git-rev-list[] 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