[PATCH] whatchanged: document its historical nature

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 9, 2013, 20:01 UTC
Message-ID: <7v38qi63bn.fsf_-_@alter.siamese.dyndns.org>
In-Reply-To: <7vwqnw9jv6.fsf@alter.siamese.dyndns.org>

After doing a bit of archaeology, I now know why "whatchanged" with an unwieldy long name persisted in the user's mindset for so long.

My conclusions are:

 - It is better to encourage new users to use `log` very early in
   the document;

 - It is not sensible to remove the command at this point yet.
   After having used to `log` that does not take diff options for
   close to a year, it is understandable why there are many people
   who are used to type `whatchanged`.

It could be argued that deprecation and retraining of fingers are doing favors to the long-time users. But the presense of the command is not hurting anybody, other than the new people who may stumble upon both and wonder what their differences are. By clearly indicating that these two are essentially the same, we would help the new people without harming anybody.

-- >8 --
Subject: [PATCH] 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>
---

 Documentation/git-whatchanged.txt | 41 ++++++++-------------------------------
 1 file changed, 8 insertions(+), 33 deletions(-)

diff --git a/Documentation/git-whatchanged.txt b/Documentation/git-whatchanged.txt
index c600b61..6faa200 100644
--- a/Documentation/git-whatchanged.txt
+++ b/Documentation/git-whatchanged.txt
@@ -13,43 +13,18 @@ SYNOPSIS
 
 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]
+run with different defaults that shows a --raw diff outputat the
+end.
 
-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
 --------

-- 
1.8.4-rc2-195-gb76a8e9