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
~~~~~~~~~~~~~~~
-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.
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.
Stop when a given path disappears from the tree.
+--merges::
+
+ Print only merge commits.
+
--no-merges::
Do not print commits with more than one parent.
--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 '<commit>'.
---branches::
+--branches[=pattern]::
- Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed
- on the command line as '<commit>'.
+ Pretend as if all the refs in `refs/heads` are listed
+ on the command line as '<commit>'. If `pattern` is given, limit
+ branches to ones matching given shell glob. If pattern lacks '?',
+ '*', or '[', '/*' at the end is implied.
---tags::
+--tags[=pattern]::
- Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed
- on the command line as '<commit>'.
+ Pretend as if all the refs in `refs/tags` are listed
+ on the command line as '<commit>'. If `pattern` is given, limit
+ tags to ones matching given shell glob. If pattern lacks '?', '*',
+ or '[', '/*' at the end is implied.
---remotes::
+--remotes[=pattern]::
- Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed
- on the command line as '<commit>'.
+ Pretend as if all the refs in `refs/remotes` are listed
+ on the command line as '<commit>'. If `pattern`is given, limit
+ remote tracking branches to ones matching given shell glob.
+ If pattern lacks '?', '*', or '[', '/*' at the end is implied.
+
+--glob=glob-pattern::
+ Pretend as if all the refs matching shell glob `glob-pattern`
+ are listed on the command line as '<commit>'. Leading 'refs/',
+ is automatically prepended if missing. If pattern lacks '?', '*',
+ or '[', '/*' at the end is implied.
+
+
+ifndef::git-rev-list[]
+--bisect::
+
+ 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 `refs/bisect/good-*` on the command
+ line.
+endif::git-rev-list[]
-ifdef::git-rev-list[]
--stdin::
In addition to the '<commit>' listed on the command
- line, read them from the standard input.
+ line, read them from the standard input. If a '--' separator is
+ seen, stop reading commits and start reading paths to limit the
+ result.
+ifdef::git-rev-list[]
--quiet::
Don't print anything to standard output. This form
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 <paths>. We shall call commits
+
-----------------------------------------------------------------------
.-A---N---O
- / /
+ / / /
I---------D
-----------------------------------------------------------------------
+
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
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
--bisect::
Limit output to the one commit object which is roughly halfway between
-the included and excluded commits. Thus, if
+included and excluded commits. Note that the bad bisection ref
+`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 `refs/bisect/`, if
-----------------------------------------------------------------------
$ git rev-list --bisect foo ^bar ^baz
--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`.
+This calculates the same as `--bisect`, except that refs in
+`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
+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`.)
+commits. Refs in `refs/bisect/` are not used. 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