diff options
| -rw-r--r-- | Documentation/git-log.txt | 21 | ||||
| -rw-r--r-- | Documentation/git-rev-list.txt | 359 | ||||
| -rw-r--r-- | Documentation/rev-list-options.txt | 361 |
3 files changed, 365 insertions, 376 deletions
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 5985f4739..ebaee4b33 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -19,14 +19,10 @@ command to control what is shown and how, and options applicable to the linkgit:git-diff-tree[1] commands to control how the changes each commit introduces are shown. -This manual page describes only the most frequently used options. - OPTIONS ------- -include::pretty-options.txt[] - :git-log: 1 include::diff-options.txt[] @@ -41,21 +37,6 @@ include::diff-options.txt[] and <until>, see "SPECIFYING REVISIONS" section in linkgit:git-rev-parse[1]. ---first-parent:: - Follow only the first parent commit upon seeing a merge - commit. This option can give a better overview when - viewing the evolution of a particular topic branch, - because merges into a topic branch tend to be only about - adjusting to updated upstream from time to time, and - this option allows you to ignore the individual commits - brought in to your history by such a merge. - --g, \--walk-reflogs:: - Show commits as they were recorded in the reflog. The log contains - a record about how the tip of a reference was changed. - Cannot be combined with --reverse. - See also linkgit:git-reflog[1]. - --decorate:: Print out the ref names of any commits that are shown. @@ -80,6 +61,8 @@ include::diff-options.txt[] Show only commits that affect the specified paths. +include::rev-list-options.txt[] + include::pretty-formats.txt[] include::diff-generate-patch.txt[] diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index db42cd8a9..5b96eabfc 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -88,363 +88,8 @@ linkgit:git-repack[1]. OPTIONS ------- -Commit Formatting -~~~~~~~~~~~~~~~~~ - -Using these options, linkgit:git-rev-list[1] will act similar to the -more specialized family of commit log tools: linkgit:git-log[1], -linkgit:git-show[1], and linkgit: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 - <aaaaaaa... 3rd on a - <aaaaaaa... 2nd on a - -yyyyyyy... 1st on b - -xxxxxxx... 1st on a ------------------------------------------------------------------------ - -Diff Formatting -~~~~~~~~~~~~~~~ - -Below are listed options that control the formatting of diff output. -Some of them are specific to linkgit:git-rev-list[1], however other diff -options may be given. See linkgit:git-diff-files[1] for more options. - --c:: - - This flag changes the way a merge commit is displayed. It shows - the differences from each of the parents to the merge result - simultaneously instead of showing pairwise diff between a parent - and the result one at a time. Furthermore, it lists only files - which were modified from all parents. - ---cc:: - - This flag implies the '-c' options and further compresses the - patch output by omitting hunks that show differences from only - one parent, or show the same change from all but one parent for - an Octopus merge. - --r:: - - Show recursive diffs. - --t:: - - Show the tree objects in the diff output. This implies '-r'. - -Commit Limiting -~~~~~~~~~~~~~~~ - -Besides specifying a range of commits that should be listed using the -special notations explained in the description, additional commit -limiting may be applied. - --- - --n 'number', --max-count='number':: - - Limit the number of commits output. - ---skip='number':: - - Skip 'number' commits before starting to show the commit output. - ---since='date', --after='date':: - - Show commits more recent than a specific date. - ---until='date', --before='date':: - - Show commits older than a specific date. - ---max-age='timestamp', --min-age='timestamp':: - - Limit the commits output to specified time range. - ---author='pattern', --committer='pattern':: - - Limit the commits output to ones with author/committer - header lines that match the specified pattern (regular expression). - ---grep='pattern':: - - Limit the commits output to ones with log message that - matches the specified pattern (regular expression). - --i, --regexp-ignore-case:: - - Match the regexp limiting patterns without regard to letters case. - --E, --extended-regexp:: - - Consider the limiting patterns to be extended regular expressions - instead of the default basic regular expressions. - ---remove-empty:: - - Stop when a given path disappears from the tree. - ---full-history:: - - Show also parts of history irrelevant to current state of a given - path. This turns off history simplification, which removed merges - which didn't change anything at all at some child. It will still actually - simplify away merges that didn't change anything at all into either - child. - ---no-merges:: - - Do not print commits with more than one parent. - ---first-parent:: - Follow only the first parent commit upon seeing a merge - commit. This option can give a better overview when - viewing the evolution of a particular topic branch, - because merges into a topic branch tend to be only about - adjusting to updated upstream from time to time, and - this option allows you to ignore the individual commits - brought in to your history by such a merge. - ---not:: - - Reverses the meaning of the '{caret}' prefix (or lack thereof) - for all following revision specifiers, up to the next '--not'. - ---all:: - - Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the - command line as '<commit>'. - ---stdin:: - - In addition to the '<commit>' listed on the command - line, read them from the standard input. - ---quiet:: - - Don't print anything to standard output. This form of - git-rev-list is primarily meant to allow the caller to - test the exit status to see if a range of objects is fully - connected (or not). It is faster than redirecting stdout - to /dev/null as the output does not have to be formatted. - ---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 - linkgit: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[] diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt new file mode 100644 index 000000000..a8138e27a --- /dev/null +++ b/Documentation/rev-list-options.txt @@ -0,0 +1,361 @@ +Commit Formatting +~~~~~~~~~~~~~~~~~ + +ifdef::git-rev-list[] +Using these options, linkgit:git-rev-list[1] will act similar to the +more specialized family of commit log tools: linkgit:git-log[1], +linkgit:git-show[1], and linkgit:git-whatchanged[1] +endif::git-rev-list[] + +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 + <aaaaaaa... 3rd on a + <aaaaaaa... 2nd on a + -yyyyyyy... 1st on b + -xxxxxxx... 1st on a +----------------------------------------------------------------------- + +Diff Formatting +~~~~~~~~~~~~~~~ + +Below are listed options that control the formatting of diff output. +Some of them are specific to linkgit:git-rev-list[1], however other diff +options may be given. See linkgit:git-diff-files[1] for more options. + +-c:: + + This flag changes the way a merge commit is displayed. It shows + the differences from each of the parents to the merge result + simultaneously instead of showing pairwise diff between a parent + and the result one at a time. Furthermore, it lists only files + which were modified from all parents. + +--cc:: + + This flag implies the '-c' options and further compresses the + patch output by omitting hunks that show differences from only + one parent, or show the same change from all but one parent for + an Octopus merge. + +-r:: + + Show recursive diffs. + +-t:: + + Show the tree objects in the diff output. This implies '-r'. + +Commit Limiting +~~~~~~~~~~~~~~~ + +Besides specifying a range of commits that should be listed using the +special notations explained in the description, additional commit +limiting may be applied. + +-- + +-n 'number', --max-count='number':: + + Limit the number of commits output. + +--skip='number':: + + Skip 'number' commits before starting to show the commit output. + +--since='date', --after='date':: + + Show commits more recent than a specific date. + +--until='date', --before='date':: + + Show commits older than a specific date. + +--max-age='timestamp', --min-age='timestamp':: + + Limit the commits output to specified time range. + +--author='pattern', --committer='pattern':: + + Limit the commits output to ones with author/committer + header lines that match the specified pattern (regular expression). + +--grep='pattern':: + + Limit the commits output to ones with log message that + matches the specified pattern (regular expression). + +-i, --regexp-ignore-case:: + + Match the regexp limiting patterns without regard to letters case. + +-E, --extended-regexp:: + + Consider the limiting patterns to be extended regular expressions + instead of the default basic regular expressions. + +--remove-empty:: + + Stop when a given path disappears from the tree. + +--full-history:: + + Show also parts of history irrelevant to current state of a given + path. This turns off history simplification, which removed merges + which didn't change anything at all at some child. It will still actually + simplify away merges that didn't change anything at all into either + child. + +--no-merges:: + + Do not print commits with more than one parent. + +--first-parent:: + Follow only the first parent commit upon seeing a merge + commit. This option can give a better overview when + viewing the evolution of a particular topic branch, + because merges into a topic branch tend to be only about + adjusting to updated upstream from time to time, and + this option allows you to ignore the individual commits + brought in to your history by such a merge. + +--not:: + + Reverses the meaning of the '{caret}' prefix (or lack thereof) + for all following revision specifiers, up to the next '--not'. + +--all:: + + Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the + command line as '<commit>'. + +--stdin:: + + In addition to the '<commit>' listed on the command + line, read them from the standard input. + +--quiet:: + + Don't print anything to standard output. This form + is primarily meant to allow the caller to + test the exit status to see if a range of objects is fully + connected (or not). It is faster than redirecting stdout + to /dev/null as the output does not have to be formatted. + +--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'. +See also linkgit:git-reflog[1]. + +--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. + +ifdef::git-rev-list[] +--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. +endif::git-rev-list[] + +-- + +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. '--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 + linkgit: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. |