RFC patchrevision.c: add --format option for 'git log'

--format=:foo is a shorthand for --pretty=tformat:foo, otherwise this new option acts just like --pretty=foo, except it's more intuitive for users of 'git log'.

As discussed in the mailing list, this is implemented as an undocumented option. The specifics of the implementation were suggested by Junio C Hamano.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 revision.c |   10 ++++++++++
 1 files changed, 10 insertions(+), 0 deletions(-)

Felipe Contreras <felipe.contreras@gmail.com> writes:

It's been quite a long time since the earlier discussion, but I wonder why you need the colon before "foo" for this new shorthand. I *think* you are also introducing "--format=short" as a synonym to "--pretty=short", but I do not think it is necessary.

Maybe somebody wants to document it.

Needs trivial tests.

	struct strbuf fmt = STRBUF_INIT;
        revs->verbose_header = 1;
        strbuf_addf(&fmt, "tformat:%s", arg + 9);
        get_commit_format(fmt.buf, revs);
        strbuf_release(&fmt);

On Sun, Feb 22, 2009 at 6:49 PM, Junio C Hamano <gitster@pobox.com> wrote:

Well, my hope was to replace --pretty=short with --format=short, but you said that would break other scripts.

Ah, I would gladly add the documentation, shall I write that it's an 'alternative' option similar to --pretty?

All right.

Ah, I felt there must be a utility like that but I couldn't find examples of that. Thanks.

Felipe Contreras <felipe.contreras@gmail.com> writes:

It is not just scripts you break. You also break people's trained fingers.

You can specify the kind of canned pretty printing with --pretty=short, and it is not any longer to type than --format. For use in scripts that you write once and forget, there is no need to even apply this patch.

The only reason why new --format=<fmt> could be an useful addition is because --pretty=format:<fmt> may be too long to type interactively.

I do not think we want to introduce a new way to say the same thing for the canned short options; "alternative" is not a good word for it.

Putting it in another way...

The output format is controlled by --pretty, which knows a set of canned output formats. You can specify --format=<fmt> if you want something different from any of the canned format. If your git does not support this new notation, you can say --pretty=tformat:<fmt> to get the same effect. The old --pretty=tformat:<fmt> (and --pretty=format:<fmt>) is not deprecated in any way.

Junio C Hamano <gitster@pobox.com> writes:

An obvious alternative with lessor impact than your patch would be not to introduce an additional option --format, but just make ":" as a synonym to "tformat:". Then you can say "--pretty=:%h %s". You would need to type one colon more but that might conceptually be less confusing, when somebody is starting to learn git *after* this change, without knowing that we did not have --format in earlier versions, from the documentation and existing pages on various web sites.

On Sun, Feb 22, 2009 at 7:53 PM, Junio C Hamano <gitster@pobox.com> wrote:

That's not the main reason I suggested the change.

At least to me (and other people agreed on the original thread), when I want to see the output of 'git log' in a different format the first thing that pops into my mind is 'git log --format=foo'. The other command I can recall right now that has something similar is 'find', which has a 'printf' option, but 'find' can do much more than just output stuff, like -delete, 'git log' on the other hand only prints stuff, so --printf would not make sense, so only the f (format) remains.

'git log --pretty=foo' is very unintuitive, no one would ever find that option by intuition. Are there different kinds of pretties? Is the default behavior --ugly?

Maybe 'git log --pretty' makes sense, but not 'git log --pretty=medium'.

Again, I don't see why 'canned format' == 'pretty' while 'custom format' == 'format'. All this wording seems to suggest the canned formats are pretty, while the custom formats are not.

I understand the option should be kept for people that are used to it, but I don't think new users should suffer because of historic reasons. And actually I believe many current users would not find --pretty=email more natural than --format=email.

Cheers.

Felipe Contreras <felipe.contreras@gmail.com> writes:

It is not just that. New people should learn existing lingo, as that is the word used in the existing documentation and various random web pages, so that they can use the same language when they teach people who are newer than themselves.

If the existing word was not pretty (that came from "pretty-formatting") but something unpronouncible like '--gzxfw=short", then your argument might make some sense, but there is no such "breakage we need to fix" here.

On Sun, Feb 22, 2009 at 8:37 PM, Junio C Hamano <gitster@pobox.com> wrote:

Yes, but the existing lingo is not perfect... I'm proposing this particular lingo to be changed.

It's not breakage that needs to be fixed, it's UI improvement, and one guideline is that the interface needs to be intuitive and natural (when possible). IMO pretty > gzxfw, but format > pretty. Don't you think that --format=email is more natural than --pretty=email? I think you are holding a bit too tight on the code reason why it's called --pretty, but users shouldn't need to see the code in order to understand why the naming of the options in git commands make sense.

Felipe Contreras <felipe.contreras@gmail.com> writes:

That heavily depends on when you ask.

If it _were_ during the period when we were actively building this bikeshed, then I would have said "yeah, that color looks prettier".

But a proposal to repaint the bikeshed in a different color long after it was built needs to be supported by an argument that is much stronger than "I do not like the current one, I am improving it by painting in a better color." IOW, you came too late to just bikeshed.

People already are used to finding the shed in the scenery by looking for that original color, however ugly the color might be. The answer to your question has to become quite different when you take that into account; otherwise you are being irresponsible to your users.

This falls into the "it would have been very nice if it were like that from day one. I'd happily agree with you,... only if we didn't do it the way we originally did" category. You cannot call such a change an improvement without thinking why the above statement is heavily qualified with "if it were" and "only if we didn't".

I am actually Ok with having a synonym --format that works *identically* with how --pretty works, and then update how both of them work to make them better perhaps in a follow-up patch. You accept style names that you recognize as before, and instead of erroring out, if the unrecognized string has % in it, pretend as if "tformat:" was in front of it. It still has the "two keywords for the same thing" misfortune, but that is something you cannot avoid. You yourself would need to say "newer git would accept --format=short, but with the version shipped by your distribution you may have to say --pretty instead" when teaching new people who come after you. Hopefully not many people would complain as long as you do not break the existing --pretty,

Also I like Linus's --oneline === --pretty=oneline, but I haven't audited the list of double-dash options our commands take that are unrelated to pretty-printing styles. If there are ones that look or sound similar to the recognized style names (or if some commands may want to use the word for controlling their own operation that is not related to pretty-printing in their future enhancement), it would cause grief to us down the road. The only one I can think of offhand is --full, so this probably is Ok.

On Mon, Feb 23, 2009 at 8:39 AM, Junio C Hamano <gitster@pobox.com> wrote:

The color of a bikeshed is essentially irrelevant, red vs blue makes almost no difference. Are you suggesting that --pretty and --format are essentially the same and therefore arguing about one vs the other is a waste of time?

Words have associated meaning, choosing one over the other makes a big difference, sometimes huge. Image what would have happened if programming languages would have chosen 'check' instead of 'if'...

I'm saying we should be in point B (--format), you are saying we are already in point A (--pretty), it would have been nicer to choose B since day one, but we didn't.

I'm still saying we should be in point B, even if the path from A to B is unclear, and maybe tedious, it's still an improvement, and as such it must be done eventually.

AFAIK git's user interface is one of the big areas for improvement, and a common complaint from anti-gitters... this is an example of one of the issues.

Perhaps there should be a way to handle this "it would have been very nice if it were like that from day one" cases, maybe queue the patches on a separate branch until some big release? 1.7.x? Or maybe in the meantime generate a warning: X is deprecated, please use Y instead.

The issue that comes into my mind is the old 'git-foo' format. The switch wasn't handled correctly according to many people... most users noticed until it was very late. That's why deprecation warnings make sense.

I would rather say --pretty is history, if you have 1.7.x, use --format.

Yeah, I would like --oneline too.

On Tue, Feb 24, 2009 at 2:56 AM, Felipe Contreras <felipe.contreras@gmail.com> wrote:

People somehow got used to the ugly color, they'll get used to the pretty one, in fact, they would probably like it better, and maybe even thought more than once on changing it.

If they're the kind of people that don't like new things they'll probably not be using git anyway.

Felipe Contreras <felipe.contreras@gmail.com> writes:

You do not have to send two messages in a row to reaffirm that you are of irresponsible kind. I heard you enough already.

Go away.

Quoting Junio C Hamano <gitster@pobox.com>:

Junio, what got into you?

I've always admired your calm and reasoned way to deal with even the most obnoxious people, and unlike more abrasive people on this list I've never seen you say "Go away" to anybody here.

Especially because I agree with you that calling pretty-printing as "pretty" isn't so broken to make such a big deal out of, it would be better not to chase a potentially useful contributor away on such a minor issue.

Nanako Shiraishi <nanako3@lavabit.com> writes:

I may try to be more diplomatic than other people, but it does not mean I do not reserve the right to get annoyed enough from time to time.

When you hear people complain, and you take a poll and see there are many people who agree with you, a naive thing to do is to assume that you now got the majority vote. Over time, you will learn that majority were happy, were not complaining, and they merely did not bother to object to the complainers who want to change things. And the last thing you want is to find these things out the hard way by bringing a sudden change to them and giving them something to compalin about, like we did with 1.6.0. You need to learn to take "let's improve this thing, as many people want it" with a huge grain of salt.

This cannot be stressed enough; if somebody is incapable of understanding it, then we would be better off without him or her.

I am not so worried about losing Felipe as a contributor, not because I do not think he is useful, but because I do not think he is stupid.

Judging from his other patches, I think he is reasonably capable and intelligent, but just is not experienced enough with the culture around here, especially about taking the existing users extremely seriously. The first patch landed in the git tree from him was in January 2009---perhaps I should have tried to be more diplomatic with him as a newcomer for a bit longer, but I am reasonably sure that he is smart enough to realize the importance of different acceptance criteria between new features and changes to existing interfaces after having time to think about it for a few days, and will come back.

On Tue, Feb 24, 2009 at 10:00 AM, Junio C Hamano <gitster@pobox.com> wrote:

I've discussed with many people regarding git; git-haters, people that don't care about vcs, new git users, etc. So you might say that I have an 'outsider' point of view, that shouldn't necessarily be a bad thing.

The 'problems' about git that I've heard is that #1 lack of win32 support (now fixed), #2 complicated user interface (fixable), #3 lack of storing renames (yes, people do complain about that). I don't really care about #3, but I do care about #2.

Now, a google for 'git user interface' returns a few interesting results, and one of them is Jon Loeliger asking for more grained detail about the areas of improvement in the Git Survey, but somehow nobody listened and now we don't have any nice graph about people wanting UI improvements: http://marc.info/?l=git&m=121691093706811&w=2

However, we do have comments in the survey about how to improve git:
 * #1 documentation #2 interface:  a. having tons of git-* binaries in
/usr/bin confuses tab-completion in the shell  b. the whole index
concept is a major pain point, i'm constantly trying to get around
having to deal with it
 * 1) CLI interface 2) More consistent terminology 3) Better
documentation with examples and use cases
 * a more intuitive command line interface
 * Better consistency of the interface. Documentation intended for
users, rather than being addressed to people who already understand
what a reflog is.
 * Better docs, better official interface
 * better docs, better usage hints, more consistent terminology/interface
 * Better user interface (on command line). More safety against user errors.
 * bzr like plugin ability, consistent interface with all commands as
well as consistent naming of commands.
 * cleaner interface, of course the docs could be better in places.
Better responsiveness: my buddy submitted a patch to add a "git svn
diff" command and received no response from the mailing list, either
positive or negative.
 * Cleaner, more consistent, easier to learn user interface.  Man
pages should be more user-oriented than developer-oriented.  Sparse
checkout can't come soon enough.
 * Cleanup the interface, not so many commands that do the same thing
or almost the same thing.
 * CLI user interface.  git-svn corrupts history if svn repository was
created according to instructions in the svn manual:
https://bugs.launchpad.net/ubuntu/+source/git-core/+bug/163341
Windows support is better than last year, but still causes problems
(especially with ssh keys and line-endings). We can't move to git from
svn until the Windows users are happy too.
...

And the list goes on and on.

One of the lessons learned from the switch from 'git-foo' is that the change should have been more visible to users, a big annoying 'this is deprecated' warning would have been more than enough, because that will force users to shout if they don't like it or accept the resolution once it's finally deprecated. Since can't possibly miss the warning they would have no excuse to shout after the obsolescence.

I understand the "you can't change the status quo so easily kid" argument, and I'm Ok with that. That's why I'm suggesting to deprecate --pretty; users would still be able to use it but will receive a warning. If as you say users are happy with --pretty, then they'll shout when they realize someone is taking their precious option away, we could wait until 1.8.0 to make it obsolete (remove it completely).

IMHO these kinds of improvements *need to be done*, even if they are painful and take a lot of time. That doesn't mean 'git-foo' will be repeated again; we can learn from the mistakes of the past.

Cheers.

Some people prefer to call the pretty-print styles "format", and get annoyed to see "git log --format=short" fail. Introduce it as a synonym to --pretty so that both can be used interchangeably without breaking examples in existing web pages or ppeople's expectations.

Having to say --format="format:%h %s" is redundant because none of the predefined pretty-print styles have per-cent sign in it, so this patch also makes it possible to say --pretty="%h %s" (and --format="%h %s").

Signed-off-by: Nanako Shiraishi <nanako3@lavabit.com>
---

I think doing it this way won't risk any compatibility issue. Please be gentle; this is my first real patch in the C language.

 Documentation/pretty-formats.txt |    9 +++++++++
 Documentation/pretty-options.txt |    1 +
 pretty.c                         |   20 ++++++++++++++------
 revision.c                       |    2 +-
 4 files changed, 25 insertions(+), 7 deletions(-)

On Tue, Feb 24, 2009 at 01:06:26PM +0900, Nanako Shiraishi wrote:

Thinking about this in context of the proposal to support --oneline (et al), I think this part by itself gives confusing behavior. That is, --pretty=oneline can be shortened to --oneline, but --pretty=format:$x cannot be shortened to --format=$x.

But that is modified by what happens next:

This implies that --format=$x is equivalent to --pretty=format:$x, but the patch actually implements the equivalent of --pretty=tformat:$x.

So that raises two concerns:

  1. We have to pick one as the "most common" for this shorthand; are we
     sure tformat is it? (Personally, I think it is, but I think it is a
     subtle point which we should be sure of).

  2. This _almost_ fixes the point I raised above. That is, --format=$x
     would match its longer --pretty=format:$x counterpart. Except that
     --format does _tformat_, which I would have expected to get via
     --tformat under such a proposal.

-Peff

Jeff King <peff@peff.net> writes:

I think the patch suffers from the same problem Felipe's patch had, by conflating two issues. Because it had the ":some string with %" shorthand support in addition to "--format is another way to spell --pretty", and it did that only to "--format" side, I initially misunderstood Felipe's patch as primarily addressing "Why do we have to say '--pretty=format:%h %s' when it is obvious from the context that '%h %s' is a format". It turns out that he did not like "pretty" and wanted to be able to say "format" even for the predefined pretty-print styles.

If we split this round into two patches, one that makes --format a synonym to --pretty, and then another one that allows --{format,pretty}='%h %s', and *stop there*, then we wouldn't have difficulties.

I do not think --oneline is a bad idea, but I do not think we should explain it as "You can write anything that you can write after '--pretty=' without 'pretty=' and they mean the same thing". That's where your concern arises from. You just say "'--pretty=oneline --abbrev-commit' is so often used, so we have a shorthand for the whole thing: --oneline", without implying anything about other things such as --short or --tformat.

On Mon, Feb 23, 2009 at 09:33:59PM -0800, Junio C Hamano wrote:

Yes, I totally agree they are two separate issues, and it should be two patches.

Right, and I am OK with that. I just wanted to make sure we were not painting ourselves into a corner for a "patch 3/2" that has been discussed.

OK. I think that is reasonable. Personally, I would really only care about --oneline, anyway (and I do think a --pretty=%h shorthand should use "tformat"; the extra typing is probably not a big deal if you are doing a big multi-line format).

-Peff

On Tue, Feb 24, 2009 at 3:33 AM, Junio C Hamano <gitster@pobox.com> wrote:

After sending the email I realized I didn't answer your argument about people already used to the existing stuff.

I might sound too aggressive on email, but my intention is not to attack anything or anybody, just improve things.

On Sun, 22 Feb 2009, Felipe Contreras wrote:

Historically, the default behaviour _was_ indeed --ugly.

There was no native "git log" command per se, it was literally a script that did something like

	git-rev-list <rev-opts> |
		git-diff-tree --stdin --pretty |
		$(PAGER)

and the "--pretty" option was to tell git to give human-readable output from git-diff-tree rather than the harsh raw stuff.

So yes, the default for git used to be "low-level plumbing commands for scripting", with some options to turn them pretty for the fleshies.

Then we started having more options, so "--pretty" became "--pretty=xyz".

But I do realize that without the historical background, none of this makes sense. And quite frankly, I do hate "--pretty=xyz" myself. I find myself wishing I could just write

	git log --oneline

instead of "--pretty=oneline", and I wish "shortlog" was a pretty format instead of a command of its own.

So at least personally, I would not object AT ALL to

 - leave the "--pretty=xyz" parsing for historical reasons

 - support "--format=xyz" too, because it does make sense (and it's 
   unambiguous: a format without a '%' sign in it makes no sense, so there 
   is no reason to have "--format=format:%s"

 - if we see an unrecognized "--<option>", and the <option> is a format 
   name, just assume the user was lazy and couldn't be bothered to write 
   out "format="

and then for extra bonus points, make "shortlog" work as a format too.

			Linus

Linus Torvalds <torvalds@linux-foundation.org> writes:

[...]

Well, shortlog is a bit different as it reorders and summarizes log information. But if --stat is format of diff, then I guess shortlog (future log --format=summary) is a format for log...

El 22/2/2009, a las 21:34, Linus Torvalds escribió:

Why not an alias then?

	git oneline

ie. something like this, which I have in my config:

	alias.oneline=log --pretty=oneline --abbrev-commit

Cheers, Wincent