X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-rev-list.txt;h=5b96eabfce9eecbfccaff16096c616105a040c3d;hb=fdcf39e59b98536d2d65b26a59925dc1dea421d4;hp=485280423e90bac43b4c372bbc8d350c34cf4fa8;hpb=3d66dc9657f195cb241387a87bcdd5709abd8a21;p=git.git diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 485280423..5b96eabfc 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -15,11 +15,13 @@ SYNOPSIS [ \--min-age=timestamp ] [ \--sparse ] [ \--no-merges ] + [ \--first-parent ] [ \--remove-empty ] [ \--full-history ] [ \--not ] [ \--all ] [ \--stdin ] + [ \--quiet ] [ \--topo-order ] [ \--parents ] [ \--timestamp ] @@ -77,355 +79,17 @@ between the two operands. The following two commands are equivalent: $ git-rev-list A...B ----------------------------------------------------------------------- -gitlink:git-rev-list[1] is a very essential git program, since it +linkgit:git-rev-list[1] is a very essential git program, since it provides the ability to build and traverse commit ancestry graphs. For this reason, it has a lot of different options that enables it to be -used by commands as different as gitlink:git-bisect[1] and -gitlink:git-repack[1]. +used by commands as different as linkgit:git-bisect[1] and +linkgit:git-repack[1]. OPTIONS ------- -Commit Formatting -~~~~~~~~~~~~~~~~~ - -Using these options, gitlink:git-rev-list[1] will act similar to the -more specialized family of commit log tools: gitlink:git-log[1], -gitlink:git-show[1], and gitlink:git-whatchanged[1] - -include::pretty-options.txt[] - ---relative-date:: - - Synonym for `--date=relative`. - ---date={relative,local,default,iso,rfc}:: - - Only takes effect for dates shown in human-readable format, such - as when using "--pretty". -+ -`--date=relative` shows dates relative to the current time, -e.g. "2 hours ago". -+ -`--date=local` shows timestamps in user's local timezone. -+ -`--date=iso` (or `--date=iso8601`) shows timestamps in ISO 8601 format. -+ -`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822 -format, often found in E-mail messages. -+ -`--date=short` shows only date but not time, in `YYYY-MM-DD` format. -+ -`--date=default` shows timestamps in the original timezone -(either committer's or author's). - ---header:: - - Print the contents of the commit in raw-format; each record is - separated with a NUL character. - ---parents:: - - Print the parents of the commit. - ---timestamp:: - Print the raw commit timestamp. - ---left-right:: - - Mark which side of a symmetric diff a commit is reachable from. - Commits from the left side are prefixed with `<` and those from - the right with `>`. If combined with `--boundary`, those - commits are prefixed with `-`. -+ -For example, if you have this topology: -+ ------------------------------------------------------------------------ - y---b---b branch B - / \ / - / . - / / \ - o---x---a---a branch A ------------------------------------------------------------------------ -+ -you would get an output line this: -+ ------------------------------------------------------------------------ - $ git rev-list --left-right --boundary --pretty=oneline A...B - - >bbbbbbb... 3rd on b - >bbbbbbb... 2nd on b - '. - ---stdin:: - - In addition to the '' listed on the command - line, read them from the standard input. - ---cherry-pick:: - - Omit any commit that introduces the same change as - another commit on the "other side" when the set of - commits are limited with symmetric difference. -+ -For example, if you have two branches, `A` and `B`, a usual way -to list all commits on only one side of them is with -`--left-right`, like the example above in the description of -that option. It however shows the commits that were cherry-picked -from the other branch (for example, "3rd on b" may be cherry-picked -from branch A). With this option, such pairs of commits are -excluded from the output. - --g, --walk-reflogs:: - - Instead of walking the commit ancestry chain, walk - reflog entries from the most recent one to older ones. - When this option is used you cannot specify commits to - exclude (that is, '{caret}commit', 'commit1..commit2', - nor 'commit1...commit2' notations cannot be used). -+ -With '\--pretty' format other than oneline (for obvious reasons), -this causes the output to have two extra lines of information -taken from the reflog. By default, 'commit@\{Nth}' notation is -used in the output. When the starting commit is specified as -'commit@{now}', output also uses 'commit@\{timestamp}' notation -instead. Under '\--pretty=oneline', the commit message is -prefixed with this information on the same line. - -Cannot be combined with '\--reverse'. - ---merge:: - - After a failed merge, show refs that touch files having a - conflict and don't exist on all heads to merge. - ---boundary:: - - Output uninteresting commits at the boundary, which are usually - not shown. - ---dense, --sparse:: - -When optional paths are given, the default behaviour ('--dense') is to -only output commits that changes at least one of them, and also ignore -merges that do not touch the given paths. - -Use the '--sparse' flag to makes the command output all eligible commits -(still subject to count and age limitation), but apply merge -simplification nevertheless. - ---bisect:: - -Limit output to the one commit object which is roughly halfway between -the included and excluded commits. Thus, if - ------------------------------------------------------------------------ - $ git-rev-list --bisect foo ^bar ^baz ------------------------------------------------------------------------ - -outputs 'midpoint', the output of the two commands - ------------------------------------------------------------------------ - $ git-rev-list foo ^midpoint - $ git-rev-list midpoint ^bar ^baz ------------------------------------------------------------------------ - -would be of roughly the same length. Finding the change which -introduces a regression is thus reduced to a binary search: repeatedly -generate and test new 'midpoint's until the commit chain is of length -one. - ---bisect-vars:: - -This calculates the same as `--bisect`, but outputs text ready -to be eval'ed by the shell. These lines will assign the name of -the midpoint revision to the variable `bisect_rev`, and the -expected number of commits to be tested after `bisect_rev` is -tested to `bisect_nr`, the expected number of commits to be -tested if `bisect_rev` turns out to be good to `bisect_good`, -the expected number of commits to be tested if `bisect_rev` -turns out to be bad to `bisect_bad`, and the number of commits -we are bisecting right now to `bisect_all`. - ---bisect-all:: - -This outputs all the commit objects between the included and excluded -commits, ordered by their distance to the included and excluded -commits. The farthest from them is displayed first. (This is the only -one displayed by `--bisect`.) - -This is useful because it makes it easy to choose a good commit to -test when you want to avoid to test some of them for some reason (they -may not compile for example). - -This option can be used along with `--bisect-vars`, in this case, -after all the sorted commit objects, there will be the same text as if -`--bisect-vars` had been used alone. - --- - -Commit Ordering -~~~~~~~~~~~~~~~ - -By default, the commits are shown in reverse chronological order. - ---topo-order:: - - This option makes them appear in topological order (i.e. - descendant commits are shown before their parents). - ---date-order:: - - This option is similar to '--topo-order' in the sense that no - parent comes before all of its children, but otherwise things - are still ordered in the commit timestamp order. - ---reverse:: - - Output the commits in reverse order. - Cannot be combined with '\--walk-reflogs'. - -Object Traversal -~~~~~~~~~~~~~~~~ - -These options are mostly targeted for packing of git repositories. - ---objects:: - - Print the object IDs of any object referenced by the listed - commits. 'git-rev-list --objects foo ^bar' thus means "send me - all object IDs which I need to download if I have the commit - object 'bar', but not 'foo'". - ---objects-edge:: - - Similar to '--objects', but also print the IDs of excluded - commits prefixed with a "-" character. This is used by - gitlink:git-pack-objects[1] to build "thin" pack, which records - objects in deltified form based on objects contained in these - excluded commits to reduce network traffic. - ---unpacked:: - - Only useful with '--objects'; print the object IDs that are not - in packs. - ---no-walk:: - - Only show the given revs, but do not traverse their ancestors. - ---do-walk:: - - Overrides a previous --no-walk. - +:git-rev-list: 1 +include::rev-list-options.txt[] include::pretty-formats.txt[] @@ -441,4 +105,4 @@ and the git-list . GIT --- -Part of the gitlink:git[7] suite +Part of the linkgit:git[7] suite