whatchanged: document its historical nature

Encourage new users to use 'log' instead.  These days, these
commands are unified and just have different defaults.

'git log' only allowed you to view the log messages and no diffs
when it was added in early June 2005.  It was only in early April
2006 that the command learned to take diff options.  Because of
this, power users tended to use 'whatchanged' that already existed
since mid May 2005 and supported diff options.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt
index c600b61e2b62013366476807c733837c0e854165..8b63ceb00e71a5e2f09cf7686b0978dcf71d1e03 100644 (file)
--- a/Documentation/git-whatchanged.txt
+++ b/Documentation/git-whatchanged.txt
@@ -13,43 +13,17 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
 
 DESCRIPTION
 -----------

-Shows commit logs and diff output each commit introduces.  The
-command internally invokes 'git rev-list' piped to
-'git diff-tree', and takes command line options for both of
-these commands.

 
 

-This manual page describes only the most frequently used options.
+Shows commit logs and diff output each commit introduces.

 
 

+New users are encouraged to use linkgit:git-log[1] instead.  The
+`whatchanged` command is essentially the same as linkgit:git-log[1]
+but defaults to show the raw format diff output and to skip merges.

 
 

-OPTIONS
--------
--p::
-       Show textual diffs, instead of the Git internal diff
-       output format that is useful only to tell the changed
-       paths and their nature of changes.
+The command is kept primarily for historical reasons; fingers of
+many people who learned Git long before `git log` was invented by
+reading Linux kernel mailing list are trained to type it.

 
 

--<n>::
-       Limit output to <n> commits.
-
-<since>..<until>::
-       Limit output to between the two named commits (bottom
-       exclusive, top inclusive).
-
--r::
-       Show Git internal diff output, but for the whole tree,
-       not just the top level.
-
--m::
-       By default, differences for merge commits are not shown.
-       With this flag, show differences to that commit from all
-       of its parents.
-+
-However, it is not very useful in general, although it
-*is* useful on a file-by-file basis.
-
-include::pretty-options.txt[]
-
-include::pretty-formats.txt[]

 
 Examples
 --------
 
 Examples
 --------