Merge branch 'maint'

[git.git] / Documentation / rev-list-options.txt

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 966276b169d6fb09c571a05257dfbc1fe3bd4f03..b9f6e4d1b7564480fac9c4e355fdc4936f6fa3db 100644 (file)
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -222,6 +222,21 @@ endif::git-rev-list[]
        Pretend as if all the refs in `$GIT_DIR/refs/` are listed on the
        command line as '<commit>'.
 
+--branches::
+
+       Pretend as if all the refs in `$GIT_DIR/refs/heads` are listed
+       on the command line as '<commit>'.
+
+--tags::
+
+       Pretend as if all the refs in `$GIT_DIR/refs/tags` are listed
+       on the command line as '<commit>'.
+
+--remotes::
+
+       Pretend as if all the refs in `$GIT_DIR/refs/remotes` are listed
+       on the command line as '<commit>'.
+
 ifdef::git-rev-list[]
 --stdin::
 
@@ -285,8 +300,52 @@ See also linkgit:git-reflog[1].
 History Simplification
 ~~~~~~~~~~~~~~~~~~~~~~
 
-When optional paths are given, 'git-rev-list' simplifies commits with
-various strategies, according to the options you have selected.
+Sometimes you are only interested in parts of the history, for example the
+commits modifying a particular <path>. But there are two parts of
+'History Simplification', one part is selecting the commits and the other
+is how to do it, as there are various strategies to simplify the history.
+
+The following options select the commits to be shown:
+
+<paths>::
+
+       Commits modifying the given <paths> are selected.
+
+--simplify-by-decoration::
+
+       Commits that are referred by some branch or tag are selected.
+
+Note that extra commits can be shown to give a meaningful history.
+
+The following options affect the way the simplification is performed:
+
+Default mode::
+
+       Simplifies the history to the simplest history explaining the
+       final state of the tree. Simplest because it prunes some side
+       branches if the end result is the same (i.e. merging branches
+       with the same content)
+
+--full-history::
+
+       As the default mode but does not prune some history.
+
+--dense::
+
+       Only the selected commits are shown, plus some to have a
+       meaningful history.
+
+--sparse::
+
+       All commits in the simplified history are shown.
+
+--simplify-merges::
+
+       Additional option to '--full-history' to remove some needless
+       merges from the resulting history, as there are no selected
+       commits contributing to this merge.
+
+A more detailed explanation follows.
 
 Suppose you specified `foo` as the <paths>.  We shall call commits
 that modify `foo` !TREESAME, and the rest TREESAME.  (In a diff
@@ -456,6 +515,14 @@ Note the major differences in `N` and `P` over '\--full-history':
   removed completely, because it had one parent and is 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
+(in other words, kept after history simplification rules described
+above) if (1) they are referenced by tags, or (2) they change the
+contents of the paths given on the command line.  All other
+commits are marked as TREESAME (subject to be simplified away).
+
 ifdef::git-rev-list[]
 Bisection Helpers
 ~~~~~~~~~~~~~~~~~
@@ -466,14 +533,14 @@ 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
+       $ 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
+       $ git rev-list foo ^midpoint
+       $ git rev-list midpoint ^bar ^baz
 -----------------------------------------------------------------------
 
 would be of roughly the same length.  Finding the change which