Merge branch 'lt/decorate'

* lt/decorate:
rev-list documentation: clarify the two parts of history simplification
Document "git log --simplify-by-decoration"
Document "git log --source"
revision traversal: '--simplify-by-decoration'
Make '--decorate' set an explicit 'show_decorations' flag
revision: make tree comparison functions take commits rather than trees
Add a 'source' decorator for commits

Conflicts:
Documentation/rev-list-options.txt

diff --combined Documentation/rev-list-options.txt
index 68a253f9778e50472fcfcf5e3a1690ccdd0492e7,78c381a8e049b3425256d212586b843702aa5661..6d7cf6d51fc5c2511c8ed411ed36aefd93d4ad60
--- 1/Documentation/rev-list-options.txt
--- 2/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@@ -285,8 -285,52 +285,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 -500,14 +500,14 @@@ Note the major differences in `N` and `
    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 -518,14 +518,14 @@@ Limit output to the one commit object w
  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

diff --combined builtin-log.c
index 75d698f0cef491b2c7fdc4920b37cb8e61da5e20,82ea07b1bd7ba03991c1fb3cca40796f21dbaab7..b164717379627b7bfc303bd3fdf360ecd2db152d
--- 1/builtin-log.c
--- 2/builtin-log.c
+++ b/builtin-log.c
@@@ -28,7 -28,6 +28,6 @@@ static void cmd_log_init(int argc, cons
                      struct rev_info *rev)
  {
        int i;
-       int decorate = 0;
  
        rev->abbrev = DEFAULT_ABBREV;
        rev->commit_format = CMIT_FMT_DEFAULT;
@@@ -55,11 -54,12 +54,13 @@@
                const char *arg = argv[i];
                if (!strcmp(arg, "--decorate")) {
                        load_ref_decorations();
-                       decorate = 1;
+                       rev->show_decorations = 1;
+               } else if (!strcmp(arg, "--source")) {
+                       rev->show_source = 1;
                } else
                        die("unrecognized argument: %s", arg);
        }
 +      DIFF_OPT_SET(&rev->diffopt, ALLOW_TEXTCONV);
  }
  
  /*