![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index 1f57aed337e87e8bd2b175ef3fc807288a8256bf..7a42567060bc4c79e5eef00e4cc01a90c9ab39a4 100644 (file)
Synonym for `--date=relative`.
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
Only takes effect for dates shown in human-readable format, such
as when using "--pretty". `log.date` config variable sets a default
--parents::
--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::
--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::
ifdef::git-rev-list[]
--timestamp::
This implies the '--topo-order' option by default, but the
'--date-order' option may also be specified.
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
~~~~~~~~~~~~~~~
ifndef::git-rev-list[]
Diff Formatting
~~~~~~~~~~~~~~~
-c::
-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.
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.
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.
-r::
Show recursive diffs.
--all::
--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>'.
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 `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.
- Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed
- on the command line as '<commit>'.
ifndef::git-rev-list[]
--bisect::
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
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[]
line.
endif::git-rev-list[]
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',
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
+
With '\--pretty' format other than oneline (for obvious reasons),
this causes the output to have two extra lines of information
merges from the resulting history, as there are no selected
commits contributing to this merge.
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 more detailed explanation follows.
Suppose you specified `foo` as the <paths>. We shall call commits
+
-----------------------------------------------------------------------
.-A---N---O
+
-----------------------------------------------------------------------
.-A---N---O
- / /
+ / / /
I---------D
-----------------------------------------------------------------------
+
I---------D
-----------------------------------------------------------------------
+
one of the parents is TREESAME, we follow only that one, so the other
sides of the merge are never walked.
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
--simplify-merges::
First, build a history graph in the same way that
removed completely, because it had one parent and is TREESAME.
--
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
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
Limit output to the one commit object which is roughly halfway between
included and excluded commits. Note that the bad bisection ref
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
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
-----------------------------------------------------------------------
$ git rev-list --bisect foo ^bar ^baz
--bisect-vars::
This calculates the same as `--bisect`, except that refs in
--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
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
This outputs all the commit objects between the included and excluded
commits, ordered by their distance to the included and excluded
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`.)
+
from them is displayed first. (This is the only one displayed by
`--bisect`.)
+