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.

While at it, remove 'whatchanged' from a list of sample commands
that are affected by GIT_FLUSH environment variable. This is not
meant to be an exhaustive list but as a list of typical ones, and an
old command that is kept primarily for backward compatibility does
not belong to it.

Helped-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

4 files changed, 47 insertions, 37 deletions

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 3bdd56e8f4..f53b479a3d 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -818,7 +818,7 @@ for further details.
 'GIT_FLUSH'::
 	If this environment variable is set to "1", then commands such
 	as 'git blame' (in incremental mode), 'git rev-list', 'git log',
-	'git check-attr', 'git check-ignore', and 'git whatchanged' will
+	'git check-attr' and 'git check-ignore' will
 	force a flush of the output stream after each record have been
 	flushed. If this
 	variable is set to "0", the output of these commands will be done
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index f538a870c7..058a352980 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
-activities.
-
-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
-powerful)
-
-----------------
-$ git whatchanged -p
-----------------
-
-and you will see exactly what has changed in the repository over its
-short history.
-
-[NOTE]
-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.
-
-[NOTE]
-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`, `git log -p`, etc. 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/git-log.sh b/contrib/examples/git-log.sh
new file mode 100755
index 0000000000..c2ea71cf14
--- /dev/null
+++ b/contrib/examples/git-log.sh
@@ -0,0 +1,15 @@
+#!/bin/sh
+#
+# Copyright (c) 2005 Linus Torvalds
+#
+
+USAGE='[--max-count=<n>] [<since>..<limit>] [--pretty=<format>] [git-rev-list options]'
+SUBDIRECTORY_OK='Yes'
+. 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/git-whatchanged.sh b/contrib/examples/git-whatchanged.sh
new file mode 100755
index 0000000000..1fb9feb348
--- /dev/null
+++ b/contrib/examples/git-whatchanged.sh
@@ -0,0 +1,28 @@
+#!/bin/sh
+
+USAGE='[-p] [--max-count=<n>] [<since>..<limit>] [--pretty=<format>] [-m] [git-diff-tree options] [git-rev-list options]'
+SUBDIRECTORY_OK='Yes'
+. git-sh-setup
+
+diff_tree_flags=$(git-rev-parse --sq --no-revs --flags "$@") || exit
+case "$0" in
+*whatchanged)
+	count=
+	test -z "$diff_tree_flags" &&
+		diff_tree_flags=$(git-repo-config --get whatchanged.difftree)
+	diff_tree_default_flags='-c -M --abbrev' ;;
+*show)
+	count=-n1
+	test -z "$diff_tree_flags" &&
+		diff_tree_flags=$(git-repo-config --get show.difftree)
+	diff_tree_default_flags='--cc --always' ;;
+esac
+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}