Re: [PATCH] whatchanged: document its historical nature

[John Keeping <john@keeping.me.uk>]

On Fri, Aug 09, 2013 at 01:01:48PM -0700, Junio C Hamano wrote:
> 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

s/outputat/output at/

Although I wonder if it would be better to say

    New users are encouraged to use linkgit:git-log[1] instead.  The
    `whatchanged` command is essentially the same as linkgit:git-log[1]
    with the `--raw` option specified.

> +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