* Remove old forgotten command: whatchanged @ 2013-08-07 16:00 Ramkumar Ramachandra 2013-08-07 16:51 ` Stefan Beller 2013-08-07 18:01 ` Kyle J. McKay 0 siblings, 2 replies; 31+ messages in thread From: Ramkumar Ramachandra @ 2013-08-07 16:00 UTC (permalink / raw) To: Git List Hi, This is the difference between whatchanged and log: diff --git a/whatchanged b/log index fa1b223..004d9aa 100644 --- a/tmp/whatchanged +++ b/tmp/log @@ -1,4 +1,4 @@ -int cmd_whatchanged(int argc, const char **argv, const char *prefix) +int cmd_log(int argc, const char **argv, const char *prefix) { struct rev_info rev; struct setup_revision_opt opt; @@ -7,13 +7,10 @@ int cmd_whatchanged(int argc, const char **argv, const char *prefix) git_config(git_log_config, NULL); init_revisions(&rev, prefix); - rev.diff = 1; - rev.simplify_history = 0; + rev.always_show_header = 1; memset(&opt, 0, sizeof(opt)); opt.def = "HEAD"; opt.revarg_opt = REVARG_COMMITTISH; cmd_log_init(argc, argv, prefix, &rev, &opt); - if (!rev.diffopt.output_format) - rev.diffopt.output_format = DIFF_FORMAT_RAW; return cmd_log_walk(&rev); } Should we remove it? Ram ^ permalink raw reply related [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-07 16:00 Remove old forgotten command: whatchanged Ramkumar Ramachandra @ 2013-08-07 16:51 ` Stefan Beller 2013-08-07 17:50 ` Junio C Hamano 2013-08-07 18:01 ` Kyle J. McKay 1 sibling, 1 reply; 31+ messages in thread From: Stefan Beller @ 2013-08-07 16:51 UTC (permalink / raw) To: Ramkumar Ramachandra; +Cc: Git List [-- Attachment #1: Type: text/plain, Size: 1492 bytes --] On 08/07/2013 06:00 PM, Ramkumar Ramachandra wrote: > Hi, > > This is the difference between whatchanged and log: > > diff --git a/whatchanged b/log > index fa1b223..004d9aa 100644 > --- a/tmp/whatchanged > +++ b/tmp/log > @@ -1,4 +1,4 @@ > -int cmd_whatchanged(int argc, const char **argv, const char *prefix) > +int cmd_log(int argc, const char **argv, const char *prefix) > { > struct rev_info rev; > struct setup_revision_opt opt; > @@ -7,13 +7,10 @@ int cmd_whatchanged(int argc, const char **argv, > const char *prefix) > git_config(git_log_config, NULL); > > init_revisions(&rev, prefix); > - rev.diff = 1; > - rev.simplify_history = 0; > + rev.always_show_header = 1; > memset(&opt, 0, sizeof(opt)); > opt.def = "HEAD"; > opt.revarg_opt = REVARG_COMMITTISH; > cmd_log_init(argc, argv, prefix, &rev, &opt); > - if (!rev.diffopt.output_format) > - rev.diffopt.output_format = DIFF_FORMAT_RAW; > return cmd_log_walk(&rev); > } > > Should we remove it? I'd deprecate it first for a year or such and remove it then. In the meantime we could implement already remove the code and change it to: + int cmd_whatchanged(int argc, const char **argv, const char *prefix) + { + return cmd_log(argc, argv, prefix) + } Also we should make sure everything git whatchanged can do, can easily be done with git log <options>. Stefan [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 899 bytes --] ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-07 16:51 ` Stefan Beller @ 2013-08-07 17:50 ` Junio C Hamano 2013-08-07 21:50 ` Stefan Beller 2013-08-08 4:30 ` Ramkumar Ramachandra 0 siblings, 2 replies; 31+ messages in thread From: Junio C Hamano @ 2013-08-07 17:50 UTC (permalink / raw) To: Stefan Beller; +Cc: Ramkumar Ramachandra, Git List Stefan Beller <stefanbeller@googlemail.com> writes: > I'd deprecate it first for a year or such and remove it then. > In the meantime we could implement already remove the code > and change it to: > > + int cmd_whatchanged(int argc, const char **argv, const char *prefix) > + { > + return cmd_log(argc, argv, prefix) > + } > > Also we should make sure everything git whatchanged can do, > can easily be done with git log <options>. That's even worse than "deprecating". Your first step already changes the behaviour for people who really use the command, without telling them _why_ the behaviour has suddenly changed at all, while not helping *ANYBODY*. The only thing it does is to scratch an irrelevant itch by people who peek the codebase and find an old command whose existence does not even hurt them. They may have too much time on their hand, but that is not an excuse to waste other people's time by adding extra makework on our plate, or changing the behaviour for people who use the command without explanation. Feeling irritated somewhat... ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-07 17:50 ` Junio C Hamano @ 2013-08-07 21:50 ` Stefan Beller 2013-08-08 6:39 ` Junio C Hamano 2013-08-08 4:30 ` Ramkumar Ramachandra 1 sibling, 1 reply; 31+ messages in thread From: Stefan Beller @ 2013-08-07 21:50 UTC (permalink / raw) To: Junio C Hamano; +Cc: Ramkumar Ramachandra, Git List [-- Attachment #1: Type: text/plain, Size: 1566 bytes --] On 08/07/2013 07:50 PM, Junio C Hamano wrote: > Stefan Beller <stefanbeller@googlemail.com> writes: > >> I'd deprecate it first for a year or such and remove it then. >> In the meantime we could implement already remove the code >> and change it to: >> >> + int cmd_whatchanged(int argc, const char **argv, const char *prefix) >> + { >> + return cmd_log(argc, argv, prefix) >> + } >> >> Also we should make sure everything git whatchanged can do, >> can easily be done with git log <options>. > > That's even worse than "deprecating". > > Your first step already changes the behaviour for people who really > use the command, without telling them _why_ the behaviour has > suddenly changed at all, while not helping *ANYBODY*. > > The only thing it does is to scratch an irrelevant itch by people > who peek the codebase and find an old command whose existence does > not even hurt them. They may have too much time on their hand, but > that is not an excuse to waste other people's time by adding extra > makework on our plate, or changing the behaviour for people who use > the command without explanation. > > Feeling irritated somewhat... > Well if we make sure the whatchanged command can easily be reproduced with the log command, we could add the missing parameters to it, hence no change for the user. (git whatchanged == git log --raw --no-merges or git log --wc [to be done yet]). So I did not mean to introduce a change for users! But in general I like the idea to *remove* lines of code. Stefan [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 899 bytes --] ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-07 21:50 ` Stefan Beller @ 2013-08-08 6:39 ` Junio C Hamano 0 siblings, 0 replies; 31+ messages in thread From: Junio C Hamano @ 2013-08-08 6:39 UTC (permalink / raw) To: Stefan Beller; +Cc: Ramkumar Ramachandra, Git List Stefan Beller <stefanbeller@googlemail.com> writes: > Well if we make sure the whatchanged command can easily be reproduced > with the log command, we could add the missing parameters to it, hence > no change for the user. (git whatchanged == git log --raw --no-merges or > git log --wc [to be done yet]). > > So I did not mean to introduce a change for users! I certainly did *not* read that from between the lines of what you wrote: + int cmd_whatchanged(int argc, const char **argv, const char *prefix) + { + return cmd_log(argc, argv, prefix) + } In principle, I agree that it is a good idea to try to share enough code, while keeping the flexiblity and clarity of the code for maintainability. In the extreme, you could rewrite these two functions like so: static int cmd_lw_helper( int argc, const char **argv, const char *prefix, int whoami) { struct rev_info rev; struct setup_revision_opt opt; init_grep_defaults(); git_config(git_log_config, NULL); init_revisions(&rev, prefix); if (whoami == 'l') { /* log */ rev.always_show_header = always_show_header; } else { /* whatchanged */ rev.diff = diff; rev.simplify_history = simplify_history; } memset(opt, 0, sizeof(opt)); opt.def = "HEAD"; opt.revarg_opt = REVARG_COMMITTISH; cmd_log_init(argc, argv, prefix, &rev, &opt); if (whoami == 'w') { if (!rev.diffopt.output_format) rev.diffopt.output_format = DIFF_FORMAT_RAW; } return cmd_log_walk(&rev); } int cmd_log(int argc, const char **argv, const char *prefix) { return cmd_lw_helper(argc, argv, prefix, 'l'); } int cmd_whatchanged(int argc, const char **argv, const char *prefix) { return cmd_lw_helper(argc, argv, prefix, 'w'); } but at that point, the cost you have to pay when you need to update one of them but not the other becomes higher. As whatchanged is kept primarily for people who learned Git by word of mouth reading the kernel mailing list and are used to that command. Its external interface and what it does is not likely to drastically change. On the other hand, "log" is a primary Porcelain and we would expect constant improvements. Between the "share more code for reuse" and "keep the flexibility and clarity for maintainability", it is a subtle balancing act. Personally I think the current code strikes a good balance by not going to the extreme, given that "change one (i.e. log) but not the other" is a very likely pattern for the evolution of these two commands. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-07 17:50 ` Junio C Hamano 2013-08-07 21:50 ` Stefan Beller @ 2013-08-08 4:30 ` Ramkumar Ramachandra 2013-08-08 15:03 ` Matthieu Moy 1 sibling, 1 reply; 31+ messages in thread From: Ramkumar Ramachandra @ 2013-08-08 4:30 UTC (permalink / raw) To: Junio C Hamano; +Cc: Stefan Beller, Git List Junio C Hamano wrote: > The only thing it does is to scratch an irrelevant itch by people > who peek the codebase and find an old command whose existence does > not even hurt them. They may have too much time on their hand, but > that is not an excuse to waste other people's time by adding extra > makework on our plate, or changing the behaviour for people who use > the command without explanation. It's a maintenance burden that confuses users. I'd encourage you to read git-whatchanged(1), and tell me why nobody has updated it. We're not maintaining a museum. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 4:30 ` Ramkumar Ramachandra @ 2013-08-08 15:03 ` Matthieu Moy 2013-08-08 15:13 ` Ramkumar Ramachandra 2013-08-08 17:51 ` Remove old forgotten command: whatchanged Damien Robert 0 siblings, 2 replies; 31+ messages in thread From: Matthieu Moy @ 2013-08-08 15:03 UTC (permalink / raw) To: Ramkumar Ramachandra; +Cc: Junio C Hamano, Stefan Beller, Git List Ramkumar Ramachandra <artagnon@gmail.com> writes: > Junio C Hamano wrote: >> The only thing it does is to scratch an irrelevant itch by people >> who peek the codebase and find an old command whose existence does >> not even hurt them. They may have too much time on their hand, but >> that is not an excuse to waste other people's time by adding extra >> makework on our plate, or changing the behaviour for people who use >> the command without explanation. > > It's a maintenance burden I'm not really worried about the maintainance of a 20-lines long function ... > that confuses users. ... but I do agree that the doc is really confusing. It would be much better if the doc could be reduced to: "This is a synonym for linkgit:git-log[1] --raw --some --other ---options. Please refer to the documentation of that command." -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 15:03 ` Matthieu Moy @ 2013-08-08 15:13 ` Ramkumar Ramachandra 2013-08-08 15:24 ` Matthieu Moy 2013-08-08 17:51 ` Remove old forgotten command: whatchanged Damien Robert 1 sibling, 1 reply; 31+ messages in thread From: Ramkumar Ramachandra @ 2013-08-08 15:13 UTC (permalink / raw) To: Matthieu Moy; +Cc: Junio C Hamano, Stefan Beller, Git List Matthieu Moy wrote: > ... but I do agree that the doc is really confusing. It would be much > better if the doc could be reduced to: > > "This is a synonym for linkgit:git-log[1] --raw --some --other ---options. > Please refer to the documentation of that command." I don't think there's an exact correspondence with any combination of command-line options. Perhaps we can describe it in words, and ask people to use log instead? ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 15:13 ` Ramkumar Ramachandra @ 2013-08-08 15:24 ` Matthieu Moy 2013-08-08 17:23 ` Junio C Hamano 0 siblings, 1 reply; 31+ messages in thread From: Matthieu Moy @ 2013-08-08 15:24 UTC (permalink / raw) To: Ramkumar Ramachandra; +Cc: Junio C Hamano, Stefan Beller, Git List Ramkumar Ramachandra <artagnon@gmail.com> writes: > Matthieu Moy wrote: >> ... but I do agree that the doc is really confusing. It would be much >> better if the doc could be reduced to: >> >> "This is a synonym for linkgit:git-log[1] --raw --some --other ---options. >> Please refer to the documentation of that command." > > I don't think there's an exact correspondence with any combination of > command-line options. Perhaps we can describe it in words, and ask > people to use log instead? I'd say either this, or add the missing features to "git log" to make my suggestion possible (after all, if some people like "git whatchanged", then maybe the feature would be of interest to "git log" users ?). -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 15:24 ` Matthieu Moy @ 2013-08-08 17:23 ` Junio C Hamano 2013-08-09 20:01 ` [PATCH] whatchanged: document its historical nature Junio C Hamano 0 siblings, 1 reply; 31+ messages in thread From: Junio C Hamano @ 2013-08-08 17:23 UTC (permalink / raw) To: Matthieu Moy; +Cc: Ramkumar Ramachandra, Stefan Beller, Git List Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes: > I'd say either this, or add the missing features to "git log" to make my > suggestion possible (after all, if some people like "git whatchanged", > then maybe the feature would be of interest to "git log" users ?). There is no _missing feature_ per se. whatchanged by default (1) gives diffs, (2) does not show empty commits, and (3) uses raw format for its diff output. I am fuzzy about where the name of the command and its default behaviour came from (I suspect it may have been modelled after another SCM kernel folks were familiar with), but I do not mind if somebody does an archaeology (read: ask Linus) and reduce the document to something like this: git-whatchanged(1) ================== NAME ---- git-whatchanged - Show logs with difference each commit introduces SYNOPSIS -------- [verse] 'git whatchanged' <option>... DESCRIPTION ----------- Shows commit logs and diff output each commit introduces. This is essentially the same as linkgit:git-log[1] run with different defaults. The command name and behaviour were originally borrowed from XXXX and the command is kept primarily for historical reasons (fingers of many people who learned Git by reading Linux kernel mailing list are trained to type it before `git log` was invented). New users are encouraged to use linkgit:git-log[1] instead. Examples -------- `git whatchanged -p v2.6.12.. include/scsi drivers/scsi`:: Show as patches the commits since version 'v2.6.12' that changed any file in the include/scsi or drivers/scsi subdirectories `git whatchanged --since="2 weeks ago" -- gitk`:: Show the changes during the last two weeks to the file 'gitk'. The "--" is necessary to avoid confusion with the *branch* named 'gitk' GIT --- Part of the linkgit:git[1] suite ^ permalink raw reply [flat|nested] 31+ messages in thread
* [PATCH] whatchanged: document its historical nature 2013-08-08 17:23 ` Junio C Hamano @ 2013-08-09 20:01 ` Junio C Hamano 2013-08-09 20:14 ` John Keeping 2013-08-10 7:04 ` Ramkumar Ramachandra 0 siblings, 2 replies; 31+ messages in thread From: Junio C Hamano @ 2013-08-09 20:01 UTC (permalink / raw) To: Matthieu Moy; +Cc: Ramkumar Ramachandra, Stefan Beller, Git List 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 ^ permalink raw reply related [flat|nested] 31+ messages in thread
* Re: [PATCH] whatchanged: document its historical nature 2013-08-09 20:01 ` [PATCH] whatchanged: document its historical nature Junio C Hamano @ 2013-08-09 20:14 ` John Keeping 2013-08-09 20:57 ` Junio C Hamano 2013-08-10 7:04 ` Ramkumar Ramachandra 1 sibling, 1 reply; 31+ messages in thread From: John Keeping @ 2013-08-09 20:14 UTC (permalink / raw) To: Junio C Hamano Cc: Matthieu Moy, Ramkumar Ramachandra, Stefan Beller, Git List 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 ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH] whatchanged: document its historical nature 2013-08-09 20:14 ` John Keeping @ 2013-08-09 20:57 ` Junio C Hamano 2013-08-12 7:50 ` John Keeping 0 siblings, 1 reply; 31+ messages in thread From: Junio C Hamano @ 2013-08-09 20:57 UTC (permalink / raw) To: John Keeping; +Cc: Matthieu Moy, Ramkumar Ramachandra, Stefan Beller, Git List John Keeping <john@keeping.me.uk> writes: >> +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/ Thanks. > 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. But that is different from the truth, no? "git whatchanged -p" will not behave as if "git whatchanged -p" with the "--raw" specified. The 'raw' kicks in only as a default. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH] whatchanged: document its historical nature 2013-08-09 20:57 ` Junio C Hamano @ 2013-08-12 7:50 ` John Keeping 2013-08-13 15:56 ` Junio C Hamano 0 siblings, 1 reply; 31+ messages in thread From: John Keeping @ 2013-08-12 7:50 UTC (permalink / raw) To: Junio C Hamano Cc: Matthieu Moy, Ramkumar Ramachandra, Stefan Beller, Git List On Fri, Aug 09, 2013 at 01:57:19PM -0700, Junio C Hamano wrote: > John Keeping <john@keeping.me.uk> writes: > > >> +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/ > > Thanks. > > > 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. > > But that is different from the truth, no? "git whatchanged -p" will > not behave as if "git whatchanged -p" with the "--raw" specified. > The 'raw' kicks in only as a default. Hmm, I hadn't realised that specifying "-p" would disable the "--raw". I still find the last sentence of the original patch slightly awkward though. How about 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 ``raw'' diff output and does not show merge commits. ? ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH] whatchanged: document its historical nature 2013-08-12 7:50 ` John Keeping @ 2013-08-13 15:56 ` Junio C Hamano 0 siblings, 0 replies; 31+ messages in thread From: Junio C Hamano @ 2013-08-13 15:56 UTC (permalink / raw) To: John Keeping; +Cc: Matthieu Moy, Ramkumar Ramachandra, Stefan Beller, Git List John Keeping <john@keeping.me.uk> writes: > Hmm, I hadn't realised that specifying "-p" would disable the "--raw". > I still find the last sentence of the original patch slightly awkward > though. How about > > 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 ``raw'' diff output and does not show merge > commits. > > ? I've pushed out a new version with slight rewording based on your version. Thanks. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: [PATCH] whatchanged: document its historical nature 2013-08-09 20:01 ` [PATCH] whatchanged: document its historical nature Junio C Hamano 2013-08-09 20:14 ` John Keeping @ 2013-08-10 7:04 ` Ramkumar Ramachandra 1 sibling, 0 replies; 31+ messages in thread From: Ramkumar Ramachandra @ 2013-08-10 7:04 UTC (permalink / raw) To: Junio C Hamano; +Cc: Matthieu Moy, Stefan Beller, Git List Junio C Hamano wrote: > Documentation/git-whatchanged.txt | 41 ++++++++------------------------------- > 1 file changed, 8 insertions(+), 33 deletions(-) Looks good. Thanks for doing this. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 15:03 ` Matthieu Moy 2013-08-08 15:13 ` Ramkumar Ramachandra @ 2013-08-08 17:51 ` Damien Robert 2013-08-08 18:05 ` Ramkumar Ramachandra ` (2 more replies) 1 sibling, 3 replies; 31+ messages in thread From: Damien Robert @ 2013-08-08 17:51 UTC (permalink / raw) To: git Matthieu Moy wrote in message <vpqfvukdy39.fsf@anie.imag.fr>: >> that confuses users. > > ... but I do agree that the doc is really confusing. It would be much > better if the doc could be reduced to: > > "This is a synonym for linkgit:git-log[1] --raw --some --other ---options. > Please refer to the documentation of that command." If I may chime in as a user: what really confused me about git whatchanged is this part of man gitcore-tutorial: To see the whole history of our pitiful little git-tutorial project, you can do $ git log which shows just the log messages, or if we want to see the log together with the associated patches use the more complex (and much more powerful) $ git whatchanged -p and you will see exactly what has changed in the repository over its short history. I had to go look at the source code to realize that nowadays git log and git whatchanged are basically the same functions with different defaults. A pointer to that in the man page of git whatchanged would definitively be helpful. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 17:51 ` Remove old forgotten command: whatchanged Damien Robert @ 2013-08-08 18:05 ` Ramkumar Ramachandra 2013-08-08 18:06 ` Matthieu Moy 2013-08-08 19:19 ` Junio C Hamano 2 siblings, 0 replies; 31+ messages in thread From: Ramkumar Ramachandra @ 2013-08-08 18:05 UTC (permalink / raw) To: Damien Robert; +Cc: git Damien Robert wrote: > If I may chime in as a user By all means. Do not feel inhibited to state your problems because you are a "user": we are all users; we eventually became contributors because we found certain things that needed fixing, and fixed them little by little. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 17:51 ` Remove old forgotten command: whatchanged Damien Robert 2013-08-08 18:05 ` Ramkumar Ramachandra @ 2013-08-08 18:06 ` Matthieu Moy 2013-08-08 19:09 ` John Keeping 2013-08-08 19:27 ` Junio C Hamano 2013-08-08 19:19 ` Junio C Hamano 2 siblings, 2 replies; 31+ messages in thread From: Matthieu Moy @ 2013-08-08 18:06 UTC (permalink / raw) To: Damien Robert; +Cc: git Damien Robert <damien.olivier.robert+gmane@gmail.com> writes: > Matthieu Moy wrote in message <vpqfvukdy39.fsf@anie.imag.fr>: >>> that confuses users. >> >> ... but I do agree that the doc is really confusing. It would be much >> better if the doc could be reduced to: >> >> "This is a synonym for linkgit:git-log[1] --raw --some --other ---options. >> Please refer to the documentation of that command." > > If I may chime in as a user: what really confused me about git whatchanged > is this part of man gitcore-tutorial: Indeed. How about applying this, to reduce the number of references to whatchanged in the docs? diff --git a/Documentation/git.txt b/Documentation/git.txt index 3bdd56e..486a58b 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -818,7 +818,7 @@ for further details. 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', - 'git check-attr', 'git check-ignore', and 'git whatchanged' will + 'git check-attr', and 'git check-ignore' will force a flush of the output stream after each record have been flushed. If this variable is set to "0", the output of these commands will be done diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f538a87..c6a1677 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -532,12 +532,7 @@ commit, and you can tell it to show a whole series of diffs. Alternatively, you can tell it to be "silent", and not show the diffs at all, but just show the actual commit message. -In fact, together with the 'git rev-list' program (which generates a -list of revisions), 'git diff-tree' ends up being a veritable fount of -changes. A trivial (but very useful) script called 'git whatchanged' is -included with Git which does exactly this, and shows a log of recent -activities. - +'git log' can also be used to display changes introduced by some commits. To see the whole history of our pitiful little git-tutorial project, you can do @@ -550,7 +545,7 @@ with the associated patches use the more complex (and much more powerful) ---------------- -$ git whatchanged -p +$ git log --raw -p ---------------- and you will see exactly what has changed in the repository over its -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply related [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 18:06 ` Matthieu Moy @ 2013-08-08 19:09 ` John Keeping 2013-08-08 19:27 ` Junio C Hamano 1 sibling, 0 replies; 31+ messages in thread From: John Keeping @ 2013-08-08 19:09 UTC (permalink / raw) To: Matthieu Moy; +Cc: Damien Robert, git On Thu, Aug 08, 2013 at 08:06:09PM +0200, Matthieu Moy wrote: > --- a/Documentation/gitcore-tutorial.txt > +++ b/Documentation/gitcore-tutorial.txt > @@ -532,12 +532,7 @@ commit, and you can tell it to show a whole series of diffs. > Alternatively, you can tell it to be "silent", and not show the diffs at > all, but just show the actual commit message. > > -In fact, together with the 'git rev-list' program (which generates a > -list of revisions), 'git diff-tree' ends up being a veritable fount of > -changes. A trivial (but very useful) script called 'git whatchanged' is > -included with Git which does exactly this, and shows a log of recent > -activities. > - > +'git log' can also be used to display changes introduced by some commits. > To see the whole history of our pitiful little git-tutorial project, you > can do > > @@ -550,7 +545,7 @@ with the associated patches use the more complex (and much more > powerful) Isn't this paragraph slightly misleading now? We're not using a different command any more so this could say: which shows just the log messages, or if we want to see the log together with the associated patches use the `--patch` option > ---------------- > -$ git whatchanged -p > +$ git log --raw -p > ---------------- Then this can be "git log --patch", since it seems that the surrounding text doesn't actually care that whatchanged prints the raw diffstat. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 18:06 ` Matthieu Moy 2013-08-08 19:09 ` John Keeping @ 2013-08-08 19:27 ` Junio C Hamano 2013-08-09 8:29 ` Matthieu Moy 1 sibling, 1 reply; 31+ messages in thread From: Junio C Hamano @ 2013-08-08 19:27 UTC (permalink / raw) To: Matthieu Moy; +Cc: Damien Robert, git Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes: > Damien Robert <damien.olivier.robert+gmane@gmail.com> writes: > >> Matthieu Moy wrote in message <vpqfvukdy39.fsf@anie.imag.fr>: >>>> that confuses users. >>> >>> ... but I do agree that the doc is really confusing. It would be much >>> better if the doc could be reduced to: >>> >>> "This is a synonym for linkgit:git-log[1] --raw --some --other ---options. >>> Please refer to the documentation of that command." >> >> If I may chime in as a user: what really confused me about git whatchanged >> is this part of man gitcore-tutorial: > > Indeed. > > How about applying this, to reduce the number of references to > whatchanged in the docs? I fully agree with the change to git.txt I am slightly negative about the rest. gitcore-tutorial is about teaching people who want to script around plumbing to do their own Porcelain. It is *not* about teaching them "if you want to see the history, use 'git log'". It is meant to teach them "if you want to do your own 'git log', you can do so with 'rev-list' piped to 'diff-tree --stdin'". Changing 'whatchanged' to 'log' in the latter statement is an improvement, but dropping 'can be done by combining rev-list and diff-tree' goes against the objective of the whole document. If we were to be spending more braincycles to update the latter, I think we should enrich it by finding ways to resurrect good examples that were lost over time due to "rewrite in C and make them builtin" process. > diff --git a/Documentation/git.txt b/Documentation/git.txt > index 3bdd56e..486a58b 100644 > --- a/Documentation/git.txt > +++ b/Documentation/git.txt > @@ -818,7 +818,7 @@ for further details. > 'GIT_FLUSH':: > If this environment variable is set to "1", then commands such > as 'git blame' (in incremental mode), 'git rev-list', 'git log', > - 'git check-attr', 'git check-ignore', and 'git whatchanged' will > + 'git check-attr', and 'git check-ignore' will > force a flush of the output stream after each record have been > flushed. If this > variable is set to "0", the output of these commands will be done > diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt > index f538a87..c6a1677 100644 > --- a/Documentation/gitcore-tutorial.txt > +++ b/Documentation/gitcore-tutorial.txt > @@ -532,12 +532,7 @@ commit, and you can tell it to show a whole series of diffs. > Alternatively, you can tell it to be "silent", and not show the diffs at > all, but just show the actual commit message. > > -In fact, together with the 'git rev-list' program (which generates a > -list of revisions), 'git diff-tree' ends up being a veritable fount of > -changes. A trivial (but very useful) script called 'git whatchanged' is > -included with Git which does exactly this, and shows a log of recent > -activities. > - > +'git log' can also be used to display changes introduced by some commits. > To see the whole history of our pitiful little git-tutorial project, you > can do > > @@ -550,7 +545,7 @@ with the associated patches use the more complex (and much more > powerful) > > ---------------- > -$ git whatchanged -p > +$ git log --raw -p > ---------------- > > and you will see exactly what has changed in the repository over its ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 19:27 ` Junio C Hamano @ 2013-08-09 8:29 ` Matthieu Moy 2013-08-09 17:28 ` Junio C Hamano 0 siblings, 1 reply; 31+ messages in thread From: Matthieu Moy @ 2013-08-09 8:29 UTC (permalink / raw) To: Junio C Hamano; +Cc: Damien Robert, git Junio C Hamano <gitster@pobox.com> writes: > It is meant to teach them "if you want to do your own 'git log', you > can do so with 'rev-list' piped to 'diff-tree --stdin'". Changing > 'whatchanged' to 'log' in the latter statement is an improvement, > but dropping 'can be done by combining rev-list and diff-tree' goes > against the objective of the whole document. Then, we can keep the "In fact, together with the 'git rev-list' program ..." sentence, but drop "A trivial (but very useful) script ...", which is both technically incorrect (whatchanged is not a script anymore) and misleading because it advertises whatchanged. That would look like this: diff --git a/Documentation/git.txt b/Documentation/git.txt index 3bdd56e..486a58b 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -818,7 +818,7 @@ for further details. 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', - 'git check-attr', 'git check-ignore', and 'git whatchanged' will + 'git check-attr', and 'git check-ignore' will force a flush of the output stream after each record have been flushed. If this variable is set to "0", the output of these commands will be done diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f538a87..8e53560 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -534,9 +534,8 @@ all, but just show the actual commit message. In fact, together with the 'git rev-list' program (which generates a list of revisions), 'git diff-tree' ends up being a veritable fount of -changes. A trivial (but very useful) script called 'git whatchanged' is -included with Git which does exactly this, and shows a log of recent -activities. +changes. The porcelain command 'git log' can also be used to display +changes introduced by some commits. To see the whole history of our pitiful little git-tutorial project, you can do @@ -546,11 +545,10 @@ $ git log ---------------- which shows just the log messages, or if we want to see the log together -with the associated patches use the more complex (and much more -powerful) +with the associated patches, use the `--patch` option: ---------------- -$ git whatchanged -p +$ git log -p ---------------- and you will see exactly what has changed in the repository over its -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply related [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-09 8:29 ` Matthieu Moy @ 2013-08-09 17:28 ` Junio C Hamano 2013-08-13 7:58 ` Matthieu Moy 0 siblings, 1 reply; 31+ messages in thread From: Junio C Hamano @ 2013-08-09 17:28 UTC (permalink / raw) To: Matthieu Moy; +Cc: Damien Robert, git Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes: > Junio C Hamano <gitster@pobox.com> writes: > >> It is meant to teach them "if you want to do your own 'git log', you >> can do so with 'rev-list' piped to 'diff-tree --stdin'". Changing >> 'whatchanged' to 'log' in the latter statement is an improvement, >> but dropping 'can be done by combining rev-list and diff-tree' goes >> against the objective of the whole document. > > Then, we can keep the "In fact, together with the 'git rev-list' > program ..." sentence, but drop "A trivial (but very useful) > script ...", which is both technically incorrect (whatchanged is not a > script anymore) and misleading because it advertises whatchanged. > > That would look like this: Yeah, but I think we further can strip it down and remove "git log" invocation that is done without argument. This document is not about teaching "the command you use to view the history is 'log'" (the new tutorial and the user manuals are), and this subsection is about diff-tree (in the section about "Inspecting Changes" with plumbing in the diff family). How about doing it like this? -- >8 -- Subject: core-tutorial: trim the section on Inspecting Changes Back when the core tutorial was written, `log` and `whatchanged` were scripted Porcelains. In the "Inspecting Changes" section that talks about the plumbing commands in the diff family, it made sense to use `log` and `whatchanged` as good examples of the use of these plumbing commands, and because even these scripted Porcelains were novelty (there wasn't the new end-user tutorial written), it made some sense to illustrate uses of the `git log` (and `git whatchanged`) scripted Porcelain commands. But we no longer have scripted `log` and `whatchanged` to serve as examples, and this document is not where the end users learn what `git log` command is about. Stop at briefly mentioning the possibility of combining rev-list with diff-tree to build your own log, and leave the end-user documentation of `log` to the new tutorial and the user manual. Also resurrect the last version of `git-log`, `git-whatchanged`, and `git-show` to serve as examples to contrib/examples/ directory. Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/gitcore-tutorial.txt | 39 +++---------------------------------- contrib/examples/git-log.sh | 15 ++++++++++++++ contrib/examples/git-whatchanged.sh | 28 ++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 36 deletions(-) diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index f538a87..3e83e1e 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -534,42 +534,9 @@ all, but just show the actual commit message. In fact, together with the 'git rev-list' program (which generates a list of revisions), 'git diff-tree' ends up being a veritable fount of -changes. A trivial (but very useful) script called 'git whatchanged' is -included with Git which does exactly this, and shows a log of recent -activities. - -To see the whole history of our pitiful little git-tutorial project, you -can do - ----------------- -$ git log ----------------- - -which shows just the log messages, or if we want to see the log together -with the associated patches use the more complex (and much more -powerful) - ----------------- -$ git whatchanged -p ----------------- - -and you will see exactly what has changed in the repository over its -short history. - -[NOTE] -When using the above two commands, the initial commit will be shown. -If this is a problem because it is huge, you can hide it by setting -the log.showroot configuration variable to false. Having this, you -can still show it for each command just adding the `--root` option, -which is a flag for 'git diff-tree' accepted by both commands. - -With that, you should now be having some inkling of what Git does, and -can explore on your own. - -[NOTE] -Most likely, you are not directly using the core -Git Plumbing commands, but using Porcelain such as 'git add', `git-rm' -and `git-commit'. +changes. You can emulate `git log` with a trivial script that pipes +the output of `git rev-list` to `git diff-tree --stdin`, which was +exactly how early versions of `git log` were implemented. Tagging a version diff --git a/contrib/examples/git-log.sh b/contrib/examples/git-log.sh new file mode 100755 index 0000000..c2ea71c --- /dev/null +++ b/contrib/examples/git-log.sh @@ -0,0 +1,15 @@ +#!/bin/sh +# +# Copyright (c) 2005 Linus Torvalds +# + +USAGE='[--max-count=<n>] [<since>..<limit>] [--pretty=<format>] [git-rev-list options]' +SUBDIRECTORY_OK='Yes' +. git-sh-setup + +revs=$(git-rev-parse --revs-only --no-flags --default HEAD "$@") || exit +[ "$revs" ] || { + die "No HEAD ref" +} +git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | +LESS=-S ${PAGER:-less} diff --git a/contrib/examples/git-whatchanged.sh b/contrib/examples/git-whatchanged.sh new file mode 100755 index 0000000..1fb9feb --- /dev/null +++ b/contrib/examples/git-whatchanged.sh @@ -0,0 +1,28 @@ +#!/bin/sh + +USAGE='[-p] [--max-count=<n>] [<since>..<limit>] [--pretty=<format>] [-m] [git-diff-tree options] [git-rev-list options]' +SUBDIRECTORY_OK='Yes' +. git-sh-setup + +diff_tree_flags=$(git-rev-parse --sq --no-revs --flags "$@") || exit +case "$0" in +*whatchanged) + count= + test -z "$diff_tree_flags" && + diff_tree_flags=$(git-repo-config --get whatchanged.difftree) + diff_tree_default_flags='-c -M --abbrev' ;; +*show) + count=-n1 + test -z "$diff_tree_flags" && + diff_tree_flags=$(git-repo-config --get show.difftree) + diff_tree_default_flags='--cc --always' ;; +esac +test -z "$diff_tree_flags" && + diff_tree_flags="$diff_tree_default_flags" + +rev_list_args=$(git-rev-parse --sq --default HEAD --revs-only "$@") && +diff_tree_args=$(git-rev-parse --sq --no-revs --no-flags "$@") && + +eval "git-rev-list $count $rev_list_args" | +eval "git-diff-tree --stdin --pretty -r $diff_tree_flags $diff_tree_args" | +LESS="$LESS -S" ${PAGER:-less} ^ permalink raw reply related [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-09 17:28 ` Junio C Hamano @ 2013-08-13 7:58 ` Matthieu Moy 2013-08-13 16:00 ` Junio C Hamano 0 siblings, 1 reply; 31+ messages in thread From: Matthieu Moy @ 2013-08-13 7:58 UTC (permalink / raw) To: Junio C Hamano; +Cc: Damien Robert, git Junio C Hamano <gitster@pobox.com> writes: > +changes. You can emulate `git log` with a trivial script that pipes I'd say "You can emulate `git log` and `git log -p`" here, but I'm fine with your version too. > -[NOTE] > -Most likely, you are not directly using the core > -Git Plumbing commands, but using Porcelain such as 'git add', `git-rm' > -and `git-commit'. This removal sounds unrelated, but I don't understand what this note was doing here anyway, so it's good to remove it. Thanks, -- Matthieu Moy http://www-verimag.imag.fr/~moy/ ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-13 7:58 ` Matthieu Moy @ 2013-08-13 16:00 ` Junio C Hamano 0 siblings, 0 replies; 31+ messages in thread From: Junio C Hamano @ 2013-08-13 16:00 UTC (permalink / raw) To: Matthieu Moy; +Cc: Damien Robert, git Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes: > Junio C Hamano <gitster@pobox.com> writes: > >> +changes. You can emulate `git log` with a trivial script that pipes > > I'd say "You can emulate `git log` and `git log -p`" here, but I'm fine > with your version too. By `git log`, I meant "`git log` with its various options", as it felt unnecessary to single `-p` out. But will reword anyway. >> -[NOTE] >> -Most likely, you are not directly using the core >> -Git Plumbing commands, but using Porcelain such as 'git add', `git-rm' >> -and `git-commit'. > > This removal sounds unrelated, but I don't understand what this note was > doing here anyway, so it's good to remove it. Yeah, the removal is part of "...and this document is not where the end users learn what `git log` command is about. Stop at briefly mentioning the possibility of combining rev-list with diff-tree to build your own log, and leave the end-user documentation of `log` to the new tutorial and the user manual". Thanks. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 17:51 ` Remove old forgotten command: whatchanged Damien Robert 2013-08-08 18:05 ` Ramkumar Ramachandra 2013-08-08 18:06 ` Matthieu Moy @ 2013-08-08 19:19 ` Junio C Hamano 2013-08-09 0:04 ` Damien Robert 2 siblings, 1 reply; 31+ messages in thread From: Junio C Hamano @ 2013-08-08 19:19 UTC (permalink / raw) To: Damien Robert; +Cc: git Damien Robert <damien.olivier.robert+gmane@gmail.com> writes: > Matthieu Moy wrote in message <vpqfvukdy39.fsf@anie.imag.fr>: >>> that confuses users. >> >> ... but I do agree that the doc is really confusing. It would be much >> better if the doc could be reduced to: >> >> "This is a synonym for linkgit:git-log[1] --raw --some --other ---options. >> Please refer to the documentation of that command." > > If I may chime in as a user: what really confused me about git whatchanged > is this part of man gitcore-tutorial: > > To see the whole history of our pitiful little git-tutorial project, > you can do > > $ git log > > > which shows just the log messages, or if we want to see the log > together with the associated patches use the more complex (and much > more powerful) > > $ git whatchanged -p > > > and you will see exactly what has changed in the repository over its > short history. > > I had to go look at the source code to realize that nowadays git log and > git whatchanged are basically the same functions with different defaults. A > pointer to that in the man page of git whatchanged would definitively be > helpful. The "tutorial" was written in fairly early days of Git's history, in order to primarily help those who want to use the plumbing command to script their own Porcelain commands. As it says at the very beginning, the end-user tutorial to use Git's Porcelain is gittutorial.txt and the user manual, not this document. The above section primarily explains the use of diff-tree and it was appropriate back when git-whatchanged was a script. The intent of the whole document, not just this section, was to tickle the curiousity of the users and encourage them to see how the above "much more powerful" whatchanged was implemented by going to the source. Which no longer is easy to do, as we have many Porcelains reimplemented in C. I think a good way forward is to rewrite the above to: To see the whole history of our pitiful little git-tutorial project, you can do $ git log which shows just the log messages, or if we want to see the log together with the associated patches, use $ git log -p and you will see exactly what has changed in the repository over its short history. and show a skeleton scripted implementation of "git log" using the plumbing commands which would be essentially "git rev-list" piped to "git diff-tree --stdin". Either have it as an example under contrib/examples, or as part of the text in this section of this document. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-08 19:19 ` Junio C Hamano @ 2013-08-09 0:04 ` Damien Robert 2013-08-09 0:11 ` Junio C Hamano 0 siblings, 1 reply; 31+ messages in thread From: Damien Robert @ 2013-08-09 0:04 UTC (permalink / raw) To: git Junio C Hamano wrote in message <7v61vg9eht.fsf@alter.siamese.dyndns.org>: > The "tutorial" was written in fairly early days of Git's history, in > order to primarily help those who want to use the plumbing command > to script their own Porcelain commands. As it says at the very > beginning, the end-user tutorial to use Git's Porcelain is > gittutorial.txt and the user manual, not this document. Yes, and even if it's old, it is a really well done tutorial to understand the internals of git. I read it after gittutorial and gittutorial-2. It's just that I was surprised to learn about this command, "much more powerful" than git-log. To me it looked a lot like git log --raw, and I found git log -p more useful, so I was wondering what I was missing until I read the source to see that nowadays the two commands were mostly the same. > The above section primarily explains the use of diff-tree and it was > appropriate back when git-whatchanged was a script. The intent of > the whole document, not just this section, was to tickle the > curiousity of the users and encourage them to see how the above > "much more powerful" whatchanged was implemented by going to the > source. Well in this case you can say that the intent was successful since it made me read the source code ;) ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-09 0:04 ` Damien Robert @ 2013-08-09 0:11 ` Junio C Hamano 0 siblings, 0 replies; 31+ messages in thread From: Junio C Hamano @ 2013-08-09 0:11 UTC (permalink / raw) To: Damien Robert; +Cc: git >> The above section primarily explains the use of diff-tree and it was >> appropriate back when git-whatchanged was a script. The intent of >> the whole document, not just this section, was to tickle the >> curiousity of the users and encourage them to see how the above >> "much more powerful" whatchanged was implemented by going to the >> source. > > Well in this case you can say that the intent was successful since it made > me read the source code ;) No, it is a failure. "By going to the source" was meant for "git-whatchanged.sh" source, a scripted version of Porcelain, so that users can mimic what is done in their script. Reading C source would not help them. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-07 16:00 Remove old forgotten command: whatchanged Ramkumar Ramachandra 2013-08-07 16:51 ` Stefan Beller @ 2013-08-07 18:01 ` Kyle J. McKay 2013-08-07 18:31 ` John Keeping 1 sibling, 1 reply; 31+ messages in thread From: Kyle J. McKay @ 2013-08-07 18:01 UTC (permalink / raw) To: Ramkumar Ramachandra; +Cc: Git List On Aug 7, 2013, at 09:00, Ramkumar Ramachandra wrote: > Hi, > > This is the difference between whatchanged and log: > > diff --git a/whatchanged b/log > index fa1b223..004d9aa 100644 > --- a/tmp/whatchanged > +++ b/tmp/log > @@ -1,4 +1,4 @@ > -int cmd_whatchanged(int argc, const char **argv, const char *prefix) > +int cmd_log(int argc, const char **argv, const char *prefix) > { > struct rev_info rev; > struct setup_revision_opt opt; > @@ -7,13 +7,10 @@ int cmd_whatchanged(int argc, const char **argv, > const char *prefix) > git_config(git_log_config, NULL); > > init_revisions(&rev, prefix); > - rev.diff = 1; > - rev.simplify_history = 0; > + rev.always_show_header = 1; > memset(&opt, 0, sizeof(opt)); > opt.def = "HEAD"; > opt.revarg_opt = REVARG_COMMITTISH; > cmd_log_init(argc, argv, prefix, &rev, &opt); > - if (!rev.diffopt.output_format) > - rev.diffopt.output_format = DIFF_FORMAT_RAW; > return cmd_log_walk(&rev); > } > > Should we remove it? I use it all the time. Is there some log option to get exactly the same output? It doesn't appear that there is. The closest looks like "log --name-status" but it omits the modes and hash values. ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-07 18:01 ` Kyle J. McKay @ 2013-08-07 18:31 ` John Keeping 2013-08-07 18:48 ` Kyle J. McKay 0 siblings, 1 reply; 31+ messages in thread From: John Keeping @ 2013-08-07 18:31 UTC (permalink / raw) To: Kyle J. McKay; +Cc: Ramkumar Ramachandra, Git List On Wed, Aug 07, 2013 at 11:01:57AM -0700, Kyle J. McKay wrote: > On Aug 7, 2013, at 09:00, Ramkumar Ramachandra wrote: > > Hi, > > > > This is the difference between whatchanged and log: > > > > diff --git a/whatchanged b/log > > index fa1b223..004d9aa 100644 > > --- a/tmp/whatchanged > > +++ b/tmp/log > > @@ -1,4 +1,4 @@ > > -int cmd_whatchanged(int argc, const char **argv, const char *prefix) > > +int cmd_log(int argc, const char **argv, const char *prefix) > > { > > struct rev_info rev; > > struct setup_revision_opt opt; > > @@ -7,13 +7,10 @@ int cmd_whatchanged(int argc, const char **argv, > > const char *prefix) > > git_config(git_log_config, NULL); > > > > init_revisions(&rev, prefix); > > - rev.diff = 1; > > - rev.simplify_history = 0; > > + rev.always_show_header = 1; > > memset(&opt, 0, sizeof(opt)); > > opt.def = "HEAD"; > > opt.revarg_opt = REVARG_COMMITTISH; > > cmd_log_init(argc, argv, prefix, &rev, &opt); > > - if (!rev.diffopt.output_format) > > - rev.diffopt.output_format = DIFF_FORMAT_RAW; > > return cmd_log_walk(&rev); > > } > > > > Should we remove it? > > I use it all the time. Is there some log option to get exactly the > same output? It doesn't appear that there is. The closest looks like > "log --name-status" but it omits the modes and hash values. Is it not identical to "log --raw --no-merges"? A quick test says "mostly", but whatchanged doesn't show empty commits whereas log does seem to; e.g. in git.git: diff -u <(git whatchanged) <(git log --raw --no-merges) ^ permalink raw reply [flat|nested] 31+ messages in thread
* Re: Remove old forgotten command: whatchanged 2013-08-07 18:31 ` John Keeping @ 2013-08-07 18:48 ` Kyle J. McKay 0 siblings, 0 replies; 31+ messages in thread From: Kyle J. McKay @ 2013-08-07 18:48 UTC (permalink / raw) To: John Keeping; +Cc: Ramkumar Ramachandra, Git List On Aug 7, 2013, at 11:31, John Keeping wrote: > On Wed, Aug 07, 2013 at 11:01:57AM -0700, Kyle J. McKay wrote: >> On Aug 7, 2013, at 09:00, Ramkumar Ramachandra wrote: >>> Hi, >>> >>> This is the difference between whatchanged and log: >>> >>> diff --git a/whatchanged b/log >>> index fa1b223..004d9aa 100644 >>> --- a/tmp/whatchanged >>> +++ b/tmp/log >>> @@ -1,4 +1,4 @@ >>> -int cmd_whatchanged(int argc, const char **argv, const char >>> *prefix) >>> +int cmd_log(int argc, const char **argv, const char *prefix) >>> { >>> struct rev_info rev; >>> struct setup_revision_opt opt; >>> @@ -7,13 +7,10 @@ int cmd_whatchanged(int argc, const char **argv, >>> const char *prefix) >>> git_config(git_log_config, NULL); >>> >>> init_revisions(&rev, prefix); >>> - rev.diff = 1; >>> - rev.simplify_history = 0; >>> + rev.always_show_header = 1; >>> memset(&opt, 0, sizeof(opt)); >>> opt.def = "HEAD"; >>> opt.revarg_opt = REVARG_COMMITTISH; >>> cmd_log_init(argc, argv, prefix, &rev, &opt); >>> - if (!rev.diffopt.output_format) >>> - rev.diffopt.output_format = DIFF_FORMAT_RAW; >>> return cmd_log_walk(&rev); >>> } >>> >>> Should we remove it? >> >> I use it all the time. Is there some log option to get exactly the >> same output? It doesn't appear that there is. The closest looks >> like >> "log --name-status" but it omits the modes and hash values. > > Is it not identical to "log --raw --no-merges"? > > A quick test says "mostly", but whatchanged doesn't show empty commits > whereas log does seem to; e.g. in git.git: > > diff -u <(git whatchanged) <(git log --raw --no-merges) That's probably close enough, but if that's all "whatchanged" does is basically be an alias for "log --raw --no-merges" that skips commits with no changes then the help for whatchanged ought to mention that. I still think "git whatchanged" is a lot clearer than "git log --raw -- no-merges" though. ^ permalink raw reply [flat|nested] 31+ messages in thread
end of thread, other threads:[~2013-08-13 16:01 UTC | newest] Thread overview: 31+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2013-08-07 16:00 Remove old forgotten command: whatchanged Ramkumar Ramachandra 2013-08-07 16:51 ` Stefan Beller 2013-08-07 17:50 ` Junio C Hamano 2013-08-07 21:50 ` Stefan Beller 2013-08-08 6:39 ` Junio C Hamano 2013-08-08 4:30 ` Ramkumar Ramachandra 2013-08-08 15:03 ` Matthieu Moy 2013-08-08 15:13 ` Ramkumar Ramachandra 2013-08-08 15:24 ` Matthieu Moy 2013-08-08 17:23 ` Junio C Hamano 2013-08-09 20:01 ` [PATCH] whatchanged: document its historical nature Junio C Hamano 2013-08-09 20:14 ` John Keeping 2013-08-09 20:57 ` Junio C Hamano 2013-08-12 7:50 ` John Keeping 2013-08-13 15:56 ` Junio C Hamano 2013-08-10 7:04 ` Ramkumar Ramachandra 2013-08-08 17:51 ` Remove old forgotten command: whatchanged Damien Robert 2013-08-08 18:05 ` Ramkumar Ramachandra 2013-08-08 18:06 ` Matthieu Moy 2013-08-08 19:09 ` John Keeping 2013-08-08 19:27 ` Junio C Hamano 2013-08-09 8:29 ` Matthieu Moy 2013-08-09 17:28 ` Junio C Hamano 2013-08-13 7:58 ` Matthieu Moy 2013-08-13 16:00 ` Junio C Hamano 2013-08-08 19:19 ` Junio C Hamano 2013-08-09 0:04 ` Damien Robert 2013-08-09 0:11 ` Junio C Hamano 2013-08-07 18:01 ` Kyle J. McKay 2013-08-07 18:31 ` John Keeping 2013-08-07 18:48 ` Kyle J. McKay
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.