X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Frev-list-options.txt;h=7a42567060bc4c79e5eef00e4cc01a90c9ab39a4;hb=91e811e0e80e55d580ba3601176ac84b28ad4479;hp=1f57aed337e87e8bd2b175ef3fc807288a8256bf;hpb=ad336054068074ed614d0bb54bb169e5263499d7;p=git.git diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 1f57aed33..7a4256706 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -13,7 +13,7 @@ include::pretty-options.txt[] Synonym for `--date=relative`. ---date={relative,local,default,iso,rfc,short,raw}:: +--date=(relative|local|default|iso|rfc|short|raw):: Only takes effect for dates shown in human-readable format, such as when using "--pretty". `log.date` config variable sets a default @@ -45,13 +45,13 @@ endif::git-rev-list[] --parents:: - Print the parents of the commit. Also enables parent - rewriting, see 'History Simplification' below. + Print also the parents of the commit (in the form "commit parent..."). + Also enables parent rewriting, see 'History Simplification' below. --children:: - Print the children of the commit. Also enables parent - rewriting, see 'History Simplification' below. + Print also the children of the commit (in the form "commit child..."). + Also enables parent rewriting, see 'History Simplification' below. ifdef::git-rev-list[] --timestamp:: @@ -98,6 +98,15 @@ you would get an output like this: This implies the '--topo-order' option by default, but the '--date-order' option may also be specified. +ifdef::git-rev-list[] +--count:: + Print a number stating how many commits would have been + listed, and suppress all other output. When used together + with '--left-right', instead print the counts for left and + right commits, separated by a tab. +endif::git-rev-list[] + + ifndef::git-rev-list[] Diff Formatting ~~~~~~~~~~~~~~~ @@ -108,8 +117,8 @@ 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 + With this option, diff output for a merge commit + 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. @@ -121,6 +130,15 @@ options may be given. See linkgit:git-diff-files[1] for more options. the parents have only two variants and the merge result picks one of them without modification. +-m:: + + This flag makes the merge commits show the full diff like + regular commits; for each merge parent, a separate log entry + and diff is generated. An exception is that only diff against + the first parent is shown when '--first-parent' option is given; + in that case, the output represents the changes the merge + brought _into_ the then-current branch. + -r:: Show recursive diffs. @@ -225,30 +243,43 @@ endif::git-rev-list[] --all:: - Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the + Pretend as if all the refs in `refs/` are listed on the command line as ''. ---branches:: +--branches[=]:: - Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed - on the command line as ''. + Pretend as if all the refs in `refs/heads` are listed + on the command line as ''. If '' is given, limit + branches to ones matching given shell glob. If pattern lacks '?', + '*', or '[', '/*' at the end is implied. ---tags:: +--tags[=]:: - Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed - on the command line as ''. + Pretend as if all the refs in `refs/tags` are listed + on the command line as ''. If '' is given, limit + tags to ones matching given shell glob. If pattern lacks '?', '*', + or '[', '/*' at the end is implied. ---remotes:: +--remotes[=]:: + + Pretend as if all the refs in `refs/remotes` are listed + on the command line as ''. If '' is given, limit + remote tracking branches to ones matching given shell glob. + If pattern lacks '?', '*', or '[', '/*' at the end is implied. + +--glob=:: + Pretend as if all the refs matching shell glob '' + are listed on the command line as ''. Leading 'refs/', + is automatically prepended if missing. If pattern lacks '?', '*', + or '[', '/*' at the end is implied. - Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed - on the command line as ''. ifndef::git-rev-list[] --bisect:: - Pretend as if the bad bisection ref `$GIT_DIR/refs/bisect/bad` + Pretend as if the bad bisection ref `refs/bisect/bad` was listed and as if it was followed by `--not` and the good - bisection refs `$GIT_DIR/refs/bisect/good-*` on the command + bisection refs `refs/bisect/good-*` on the command line. endif::git-rev-list[] @@ -290,7 +321,7 @@ excluded from the output. 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). + 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 @@ -362,6 +393,14 @@ Default mode:: merges from the resulting history, as there are no selected commits contributing to this merge. +--ancestry-path:: + + When given a range of commits to display (e.g. 'commit1..commit2' + or 'commit2 {caret}commit1'), only display commits that exist + directly on the ancestry chain between the 'commit1' and + 'commit2', i.e. commits that are both descendants of 'commit1', + and ancestors of 'commit2'. + A more detailed explanation follows. Suppose you specified `foo` as the . We shall call commits @@ -418,7 +457,7 @@ This results in: + ----------------------------------------------------------------------- .-A---N---O - / / + / / / I---------D ----------------------------------------------------------------------- + @@ -489,8 +528,6 @@ Note that without '\--full-history', this still simplifies merges: if one of the parents is TREESAME, we follow only that one, so the other sides of the merge are never walked. -Finally, there is a fourth simplification mode available: - --simplify-merges:: First, build a history graph in the same way that @@ -532,6 +569,46 @@ Note the major differences in `N` and `P` over '\--full-history': removed completely, because it had one parent and is TREESAME. -- +Finally, there is a fifth simplification mode available: + +--ancestry-path:: + + Limit the displayed commits to those directly on the ancestry + chain between the "from" and "to" commits in the given commit + range. I.e. only display commits that are ancestor of the "to" + commit, and descendants of the "from" commit. ++ +As an example use case, consider the following commit history: ++ +----------------------------------------------------------------------- + D---E-------F + / \ \ + B---C---G---H---I---J + / \ + A-------K---------------L--M +----------------------------------------------------------------------- ++ +A regular 'D..M' computes the set of commits that are ancestors of `M`, +but excludes the ones that are ancestors of `D`. This is useful to see +what happened to the history leading to `M` since `D`, in the sense +that "what does `M` have that did not exist in `D`". The result in this +example would be all the commits, except `A` and `B` (and `D` itself, +of course). ++ +When we want to find out what commits in `M` are contaminated with the +bug introduced by `D` and need fixing, however, we might want to view +only the subset of 'D..M' that are actually descendants of `D`, i.e. +excluding `C` and `K`. This is exactly what the '\--ancestry-path' +option does. Applied to the 'D..M' range, it results in: ++ +----------------------------------------------------------------------- + E-------F + \ \ + G---H---I---J + \ + L--M +----------------------------------------------------------------------- + The '\--simplify-by-decoration' option allows you to view only the big picture of the topology of the history, by omitting commits that are not referenced by tags. Commits are marked as !TREESAME @@ -548,10 +625,10 @@ Bisection Helpers Limit output to the one commit object which is roughly halfway between included and excluded commits. Note that the bad bisection ref -`$GIT_DIR/refs/bisect/bad` is added to the included commits (if it -exists) and the good bisection refs `$GIT_DIR/refs/bisect/good-*` are +`refs/bisect/bad` is added to the included commits (if it +exists) and the good bisection refs `refs/bisect/good-*` are added to the excluded commits (if they exist). Thus, supposing there -are no refs in `$GIT_DIR/refs/bisect/`, if +are no refs in `refs/bisect/`, if ----------------------------------------------------------------------- $ git rev-list --bisect foo ^bar ^baz @@ -572,7 +649,7 @@ one. --bisect-vars:: This calculates the same as `--bisect`, except that refs in -`$GIT_DIR/refs/bisect/` are not used, and except that this outputs +`refs/bisect/` are not used, and except that this 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 @@ -586,7 +663,7 @@ number of commits to be tested if `bisect_rev` turns out to be bad to This outputs all the commit objects between the included and excluded commits, ordered by their distance to the included and excluded -commits. Refs in `$GIT_DIR/refs/bisect/` are not used. The farthest +commits. Refs in `refs/bisect/` are not used. The farthest from them is displayed first. (This is the only one displayed by `--bisect`.) +