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@xxxxxxxxx>
> ---
>
> 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html