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