About git pretty

About git pretty

[Felipe Contreras]

Hi,

Please read aloud the following commands:
git log --pretty=short
git log --pretty=full
git log --pretty=format:%s

It is just me or 'pretty full' doesn't exactly convey the meaning of
the action to execute?

How about:
git log --format=short
git log --format=full
git log --format=custom:%s

If you like the idea I can work on a patch.

Best regards.

-- 
Felipe Contreras

Re: About git pretty

[Junio C Hamano]

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

> Please read aloud the following commands:
> git log --pretty=short
> git log --pretty=full
> git log --pretty=format:%s
>
> It is just me or 'pretty full' doesn't exactly convey the meaning of
> the action to execute?
>
> How about:
> git log --format=short
> git log --format=full
> git log --format=custom:%s
>
> If you like the idea I can work on a patch.

FWIW, I don't like it.

Re: About git pretty

[David Tweed]

On Sat, Aug 23, 2008 at 12:41 AM, Junio C Hamano <gitster@pobox.com> wrote:
> "Felipe Contreras" <felipe.contreras@gmail.com> writes:
>> It is just me or 'pretty full' doesn't exactly convey the meaning of
>> the action to execute?
[snip]
>> If you like the idea I can work on a patch.
>
> FWIW, I don't like it.

It's probably much too late to change conventions given the number of
deployed scripts, but one of the annoyances for me about git is that a
lot of the commands/options names are based on what the code does/is
written rather than relating to what a user who doesn't know or care
about the inner workings expects as output. For instance, I imagine
the --pretty gets its name because a pretty printing routine, called
pretty_print_commit in the code, was written but the name probably
doesn't make much sense to anyone who's not from a computer science
background. Likewise the options --hard, --soft and --mixed to git
reset lack any natural mnemonic structure. (I'm sure one can be
contrived, but I doubt it'd be particularly natural.) Then there's
git-fsck and gitk.

It's not remotely a big problem but it is something that I'd imagine
would have been done differently with hindsight.

-- 
cheers, dave tweed__________________________
david.tweed@gmail.com
Rm 124, School of Systems Engineering, University of Reading.
"while having code so boring anyone can maintain it, use Python." --
attempted insult seen on slashdot

Re: About git pretty

[Junio C Hamano]

"David Tweed" <david.tweed@gmail.com> writes:

> On Sat, Aug 23, 2008 at 12:41 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> "Felipe Contreras" <felipe.contreras@gmail.com> writes:
>>> It is just me or 'pretty full' doesn't exactly convey the meaning of
>>> the action to execute?
> [snip]
>>> If you like the idea I can work on a patch.
>>
>> FWIW, I don't like it.
>
> It's probably much too late to change conventions given the number of
> deployed scripts, but one of the annoyances for me about git is that a
> lot of the commands/options names are based on what the code does/is
> written rather than relating to what a user who doesn't know or care
> about the inner workings expects as output. For instance, I imagine
> the --pretty gets its name because a pretty printing routine, called
> pretty_print_commit in the code,...

It's the other way around.  We name function pretty_print_commit() because
we would want to pretty print out output and the option to trigger the
behaviour then is named --pretty.

Re: About git pretty

[David Tweed]

On Sat, Aug 23, 2008 at 1:12 AM, Junio C Hamano <gitster@pobox.com> wrote:
> "David Tweed" <david.tweed@gmail.com> writes:
>
>> On Sat, Aug 23, 2008 at 12:41 AM, Junio C Hamano <gitster@pobox.com> wrote:
>>> "Felipe Contreras" <felipe.contreras@gmail.com> writes:
>>>> It is just me or 'pretty full' doesn't exactly convey the meaning of
>>>> the action to execute?
>> [snip]
>>>> If you like the idea I can work on a patch.
>>>
>>> FWIW, I don't like it.
>>
>> It's probably much too late to change conventions given the number of
>> deployed scripts, but one of the annoyances for me about git is that a
>> lot of the commands/options names are based on what the code does/is
>> written rather than relating to what a user who doesn't know or care
>> about the inner workings expects as output. For instance, I imagine
>> the --pretty gets its name because a pretty printing routine, called
>> pretty_print_commit in the code,...
>
> It's the other way around.  We name function pretty_print_commit() because
> we would want to pretty print out output and the option to trigger the
> behaviour then is named --pretty.

The point I was making is that, to my understanding, pretty-printing
is the "standard" term _programmers_ think of when they're thinking
about writing routines for doing sophisticated output formatting. I
doubt that anyone who isn't an experienced programmer associates the
term "pretty printing" naturally with "configuring output layout". I
was talking about options that would make sense for someone who's not
a hardcore programmer but for whom using git would be beneficial, so I
didn't include git-diff for criticism because to be able to use the
output you've got to be familiar with the diff program already, and
hence know the name.

(My undergrad degree was in mathematics and I only slowly picked up
computer jargon as I moved into computer research. Git would have been
useful to me long before I happened across some papers on pretty
printing, and I ended up learning what fsck in general  means from
trying to figure out what the hell the faux-swearing you get on the
internet was. I could probably have gone on in ignorance of the
concept unix people encapsulate with "fsck" otherwise.)

My point is that the terms that come naturally to hardcore programmers
are opaque to people who might benefit from git.

Being honest, my only serious issue was with git reset. The about the
first five times I knew the "operation" I wanted to perform by
carefully checked the man-page because I wasn't sure whether --hard or
--soft corresponded to the operation I wanted.



-- 
cheers, dave tweed__________________________
david.tweed@gmail.com
Rm 124, School of Systems Engineering, University of Reading.
"while having code so boring anyone can maintain it, use Python." --
attempted insult seen on slashdot

Re: About git pretty

[David Tweed]

On Sat, Aug 23, 2008 at 1:34 AM, David Tweed <david.tweed@gmail.com> wrote:
> Being honest, my only serious issue was with git reset. The about the
> first five times I knew the "operation" I wanted to perform by
> carefully checked the man-page because I wasn't sure whether --hard or
> --soft corresponded to the operation I wanted.

It's too late for me to make sense :-) . An ungarbled final paragraph:

Being honest, my only serious issue was with git reset. For about
first five times I knew the "operation" I wanted to perform but
carefully checked the man-page because I wasn't sure whether --hard or
--soft corresponded to the operation I wanted (and didn't want to take
any chances of picking the wrong one).


-- 
cheers, dave tweed__________________________
david.tweed@gmail.com
Rm 124, School of Systems Engineering, University of Reading.
"while having code so boring anyone can maintain it, use Python." --
attempted insult seen on slashdot

Re: About git pretty

[Stephan Beyer]

Hi,

Felipe Contreras wrote:
> Hi,
> 
> Please read aloud the following commands:
> git log --pretty=short
> git log --pretty=full
> git log --pretty=format:%s
> 
> It is just me or 'pretty full' doesn't exactly convey the meaning of
> the action to execute?

But "pretty short" and "pretty format" is. :)

> How about:
> git log --format=short
> git log --format=full
> git log --format=custom:%s
> 
> If you like the idea I can work on a patch.

Because --pretty=<format> is an option taken by many git commands including
git plumbing (e.g. rev-list), many scripts will rely on "--pretty" and they
all would have to be changed. And --pretty exists since Jan 2005 (see
9d97aa64).

Also, --format is an option available to git-archive and git-for-each-ref
with a different intention for each. --pretty exists for several git
commands with the same intention for all (I think) -- pretty-printing
commit objects.

And, btw, I also do not think that your idea does really solve the 
"problem" that it always will make sense when you read it aloud.

Thus it seems that --format has no benefit over --pretty at all. :-)


Ahh, another thought:
If a new git user is looking for an option to _format_ git-log output,
she will surely search the git-log manual page for the word "format", finding

 1. --raw
 2. --shortstat
 3. --abbrev
 4. --full-index
 5. --pretty
  STRIKE!

This makes me wonder if it could make sense to move --pretty up in the
git-log manual page, but I do not think renaming it is worth the
trouble.

Regards,
  Stephan

-- 
Stephan Beyer <s-beyer@gmx.net>, PGP 0x6EDDD207FCC5040F

Re: About git pretty

[Felipe Contreras]

On Sat, Aug 23, 2008 at 3:03 AM, Stephan Beyer <s-beyer@gmx.net> wrote:
> Hi,
>
> Felipe Contreras wrote:
>> Hi,
>>
>> Please read aloud the following commands:
>> git log --pretty=short
>> git log --pretty=full
>> git log --pretty=format:%s
>>
>> It is just me or 'pretty full' doesn't exactly convey the meaning of
>> the action to execute?
>
> But "pretty short" and "pretty format" is. :)
>
>> How about:
>> git log --format=short
>> git log --format=full
>> git log --format=custom:%s
>>
>> If you like the idea I can work on a patch.
>
> Because --pretty=<format> is an option taken by many git commands including
> git plumbing (e.g. rev-list), many scripts will rely on "--pretty" and they
> all would have to be changed. And --pretty exists since Jan 2005 (see
> 9d97aa64).

Well, it might be difficult, but that doesn't mean it should not be
done. Just like the 'git-*' removal, there could be a period for
transition.

> Also, --format is an option available to git-archive and git-for-each-ref
> with a different intention for each. --pretty exists for several git
> commands with the same intention for all (I think) -- pretty-printing
> commit objects.
>
> And, btw, I also do not think that your idea does really solve the
> "problem" that it always will make sense when you read it aloud.
>
> Thus it seems that --format has no benefit over --pretty at all. :-)

Heh, it was just one example. My point is that 'format' is more meaningful.

</snip>

-- 
Felipe Contreras

Re: About git pretty

[Johannes Schindelin]

Hi,

On Sat, 23 Aug 2008, Felipe Contreras wrote:

> On Sat, Aug 23, 2008 at 3:03 AM, Stephan Beyer <s-beyer@gmx.net> wrote:
>
> > Felipe Contreras wrote:
> >> Hi,
> >>
> >> Please read aloud the following commands:
> >> git log --pretty=short
> >> git log --pretty=full
> >> git log --pretty=format:%s
> >>
> >> It is just me or 'pretty full' doesn't exactly convey the meaning of 
> >> the action to execute?
> >
> > But "pretty short" and "pretty format" is. :)
> >
> >> How about:
> >> git log --format=short
> >> git log --format=full
> >> git log --format=custom:%s
> >>
> >> If you like the idea I can work on a patch.
> >
> > Because --pretty=<format> is an option taken by many git commands 
> > including git plumbing (e.g. rev-list), many scripts will rely on 
> > "--pretty" and they all would have to be changed. And --pretty exists 
> > since Jan 2005 (see 9d97aa64).
> 
> Well, it might be difficult, but that doesn't mean it should not be 
> done. Just like the 'git-*' removal, there could be a period for 
> transition.

Of course it could be done.  But I do not deem it necessary.  In the 
balance gain/pain it comes out as not worth the hassle on this guy's 
calculator.

Ciao,
Dscho

Re: About git pretty

[Junio C Hamano]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

>> On Sat, Aug 23, 2008 at 3:03 AM, Stephan Beyer <s-beyer@gmx.net> wrote:
>>
>> > Felipe Contreras wrote:
>> >> Hi,
>> >>
>> >> Please read aloud the following commands:
>> >> git log --pretty=short
>> >> git log --pretty=full
>> >> git log --pretty=format:%s
>> >>
>> >> It is just me or 'pretty full' doesn't exactly convey the meaning of 
>> >> the action to execute?
>> >
>> > But "pretty short" and "pretty format" is. :)
>> >
>> >> How about:
>> >> git log --format=short
>> >> git log --format=full
>> >> git log --format=custom:%s
>> >>
>> >> If you like the idea I can work on a patch.
>> >
>> > Because --pretty=<format> is an option taken by many git commands 
>> > including git plumbing (e.g. rev-list), many scripts will rely on 
>> > "--pretty" and they all would have to be changed. And --pretty exists 
>> > since Jan 2005 (see 9d97aa64).
>> 
>> Well, it might be difficult, but that doesn't mean it should not be 
>> done. Just like the 'git-*' removal, there could be a period for 
>> transition.
>
> Of course it could be done.  But I do not deem it necessary.  In the 
> balance gain/pain it comes out as not worth the hassle on this guy's 
> calculator.

On the other hand, as an undocumented synonym without deprecating nor
conflicting with existing set of options in any way, I do not think it is
wrong per-se to support something like:

	git log --format=short
        git log --format=':%h %s'

in addition to existing --pretty.  It should be fairly obvious and trivial
to make handle_revision_opt() pretend as if the user said --pretty, and
for the latter one silently prefix "tformat" while doing so.

I won't be doing such a patch myself, though.

Re: About git pretty

[Felipe Contreras]

On Sat, Aug 30, 2008 at 6:30 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>
>>> On Sat, Aug 23, 2008 at 3:03 AM, Stephan Beyer <s-beyer@gmx.net> wrote:
>>>
>>> > Felipe Contreras wrote:
>>> >> Hi,
>>> >>
>>> >> Please read aloud the following commands:
>>> >> git log --pretty=short
>>> >> git log --pretty=full
>>> >> git log --pretty=format:%s
>>> >>
>>> >> It is just me or 'pretty full' doesn't exactly convey the meaning of
>>> >> the action to execute?
>>> >
>>> > But "pretty short" and "pretty format" is. :)
>>> >
>>> >> How about:
>>> >> git log --format=short
>>> >> git log --format=full
>>> >> git log --format=custom:%s
>>> >>
>>> >> If you like the idea I can work on a patch.
>>> >
>>> > Because --pretty=<format> is an option taken by many git commands
>>> > including git plumbing (e.g. rev-list), many scripts will rely on
>>> > "--pretty" and they all would have to be changed. And --pretty exists
>>> > since Jan 2005 (see 9d97aa64).
>>>
>>> Well, it might be difficult, but that doesn't mean it should not be
>>> done. Just like the 'git-*' removal, there could be a period for
>>> transition.
>>
>> Of course it could be done.  But I do not deem it necessary.  In the
>> balance gain/pain it comes out as not worth the hassle on this guy's
>> calculator.
>
> On the other hand, as an undocumented synonym without deprecating nor
> conflicting with existing set of options in any way, I do not think it is
> wrong per-se to support something like:
>
>        git log --format=short
>        git log --format=':%h %s'
>
> in addition to existing --pretty.  It should be fairly obvious and trivial
> to make handle_revision_opt() pretend as if the user said --pretty, and
> for the latter one silently prefix "tformat" while doing so.
>
> I won't be doing such a patch myself, though.

I've submitted a patch for that.

-- 
Felipe Contreras