Matthieu Moy <> writes:

> Junio C Hamano <> writes:
>> It is meant to teach them "if you want to do your own 'git log', you
>> can do so with 'rev-list' piped to 'diff-tree --stdin'".  Changing
>> 'whatchanged' to 'log' in the latter statement is an improvement,
>> but dropping 'can be done by combining rev-list and diff-tree' goes
>> against the objective of the whole document.
> Then, we can keep the "In fact, together with the 'git rev-list'
> program ..." sentence, but drop "A trivial (but very useful)
> script ...", which is both technically incorrect (whatchanged is not a
> script anymore) and misleading because it advertises whatchanged.
> That would look like this:

Yeah, but I think we further can strip it down and remove "git log"
invocation that is done without argument.  This document is not
about teaching "the command you use to view the history is 'log'"
(the new tutorial and the user manuals are), and this subsection is
about diff-tree (in the section about "Inspecting Changes" with
plumbing in the diff family).

How about doing it like this?

-- >8 --
Subject: core-tutorial: trim the section on Inspecting Changes

Back when the core tutorial was written, `log` and `whatchanged`
were scripted Porcelains.  In the "Inspecting Changes" section that
talks about the plumbing commands in the diff family, it made sense
to use `log` and `whatchanged` as good examples of the use of these
plumbing commands, and because even these scripted Porcelains were
novelty (there wasn't the new end-user tutorial written), it made
some sense to illustrate uses of the `git log` (and `git
whatchanged`) scripted Porcelain commands.

But we no longer have scripted `log` and `whatchanged` to serve as
examples, and this document is not where the end users learn what
`git log` command is about.  Stop at briefly mentioning the
possibility of combining rev-list with diff-tree to build your own
log, and leave the end-user documentation of `log` to the new
tutorial and the user manual.

Also resurrect the last version of `git-log`, `git-whatchanged`, and
`git-show` to serve as examples to contrib/examples/ directory.

Signed-off-by: Junio C Hamano <>
 Documentation/gitcore-tutorial.txt  | 39 +++----------------------------------
 contrib/examples/         | 15 ++++++++++++++
 contrib/examples/ | 28 ++++++++++++++++++++++++++
 3 files changed, 46 insertions(+), 36 deletions(-)

diff --git a/Documentation/gitcore-tutorial.txt 
index f538a87..3e83e1e 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -534,42 +534,9 @@ all, but just show the actual commit message.
 In fact, together with the 'git rev-list' program (which generates a
 list of revisions), 'git diff-tree' ends up being a veritable fount of
-changes. A trivial (but very useful) script called 'git whatchanged' is
-included with Git which does exactly this, and shows a log of recent
-To see the whole history of our pitiful little git-tutorial project, you
-can do
-$ git log
-which shows just the log messages, or if we want to see the log together
-with the associated patches use the more complex (and much more
-$ git whatchanged -p
-and you will see exactly what has changed in the repository over its
-short history.
-When using the above two commands, the initial commit will be shown.
-If this is a problem because it is huge, you can hide it by setting
-the log.showroot configuration variable to false. Having this, you
-can still show it for each command just adding the `--root` option,
-which is a flag for 'git diff-tree' accepted by both commands.
-With that, you should now be having some inkling of what Git does, and
-can explore on your own.
-Most likely, you are not directly using the core
-Git Plumbing commands, but using Porcelain such as 'git add', `git-rm'
-and `git-commit'.
+changes.  You can emulate `git log` with a trivial script that pipes
+the output of `git rev-list` to `git diff-tree --stdin`, which was
+exactly how early versions of `git log` were implemented.
 Tagging a version
diff --git a/contrib/examples/ b/contrib/examples/
new file mode 100755
index 0000000..c2ea71c
--- /dev/null
+++ b/contrib/examples/
@@ -0,0 +1,15 @@
+# Copyright (c) 2005 Linus Torvalds
+USAGE='[--max-count=<n>] [<since>..<limit>] [--pretty=<format>] [git-rev-list 
+. git-sh-setup
+revs=$(git-rev-parse --revs-only --no-flags --default HEAD "$@") || exit
+[ "$revs" ] || {
+       die "No HEAD ref"
+git-rev-list --pretty $(git-rev-parse --default HEAD "$@") |
+LESS=-S ${PAGER:-less}
diff --git a/contrib/examples/ 
new file mode 100755
index 0000000..1fb9feb
--- /dev/null
+++ b/contrib/examples/
@@ -0,0 +1,28 @@
+USAGE='[-p] [--max-count=<n>] [<since>..<limit>] [--pretty=<format>] [-m] 
[git-diff-tree options] [git-rev-list options]'
+. git-sh-setup
+diff_tree_flags=$(git-rev-parse --sq --no-revs --flags "$@") || exit
+case "$0" in
+       count=
+       test -z "$diff_tree_flags" &&
+               diff_tree_flags=$(git-repo-config --get whatchanged.difftree)
+       diff_tree_default_flags='-c -M --abbrev' ;;
+       count=-n1
+       test -z "$diff_tree_flags" &&
+               diff_tree_flags=$(git-repo-config --get show.difftree)
+       diff_tree_default_flags='--cc --always' ;;
+test -z "$diff_tree_flags" &&
+       diff_tree_flags="$diff_tree_default_flags"
+rev_list_args=$(git-rev-parse --sq --default HEAD --revs-only "$@") &&
+diff_tree_args=$(git-rev-parse --sq --no-revs --no-flags "$@") &&
+eval "git-rev-list $count $rev_list_args" |
+eval "git-diff-tree --stdin --pretty -r $diff_tree_flags $diff_tree_args" |
+LESS="$LESS -S" ${PAGER:-less}
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to
More majordomo info at

Reply via email to