git-log vs git-rev-list

git-log vs git-rev-list

[Petr Baudis]

  Hi,

  the baroque usage options of both git-log and git-rev-list make them
pretty much equivalent as far as I can see, except that:

  * Both have slightly different options set

  * git log --pretty=format is actually sane and does not pollute the
output with spurious 'commit' lines

  * I assume there are more subtle behaviour differences

  I think that having two commands that by now do essentially the same
thing, but slightly differently, is rather messy UI. Thus, I'm wondering
if it would be worthwhile to make rev-list a thin git-log wrapper and
start phasing it out?

  Yes, git-rev-list is supposed to be a plumbing thing, but from my
porcelain, I actually have to use git-log anyway if I'm to avoid messing
up my code with workarounds to the --pretty=format commit lines
evilness (hey, if I'm using --pretty=format, it means I actually want
to _control_ rev-list output, not having it trying to outsmart me
anyway).

  Merging porcelain and plumbing interface in a single command may sound
like a bad idea UI-wise, but I believe that consolidation would actually
result in a UI _improvement_ - you can cleanly separate the
documentation to the porcelain and plumbing part (actually, maybe
pushing all the plumbing part like --pretty documentation to
git-log-plumbing(1), having actually user-relevant options like -p or
--no-meges in git-log(1)). And you do not have to tell the user "oh, and
there is also git-rev-list(1) which does the same thing, but
differently; ah, and for some reason you are also to use only that one
if you need to query for bisect points".

  Should I do it?

-- 
				Petr "Pasky" Baudis
Whatever you can do, or dream you can, begin it.
Boldness has genius, power, and magic in it.	-- J. W. von Goethe

Re: git-log vs git-rev-list

[Linus Torvalds]

On Fri, 30 May 2008, Petr Baudis wrote:
> 
>   * git log --pretty=format is actually sane and does not pollute the
> output with spurious 'commit' lines

Why would you want to use "git-rev-list" at all?

The common case for git-rev-list is for things that git log simply won't 
do, ie things like "git rev-list --all --objects" that is a nonsensical 
operation to do on "git log".

So if you use "--pretty" or anything like that, you generally shouldn't 
use rev-list. Sure, it works, but it works for mainly historical reasons.

>   I think that having two commands that by now do essentially the same
> thing, but slightly differently, is rather messy UI. Thus, I'm wondering
> if it would be worthwhile to make rev-list a thin git-log wrapper and
> start phasing it out?

It already is. It's already phased out in the sense that I don't see why 
you complain. If you don't like it, don't use it. It has legacy reasons 
for existing, and it does *some* things that are simply not sensible at 
all for "git log" (ie the non-commit things).

>   Yes, git-rev-list is supposed to be a plumbing thing, but from my
> porcelain, I actually have to use git-log anyway [..]

So why do you care?

No, git-rev-list is *not* the same as "git log". 

Yes, git rev-list can do a lot of the same things, for historical reasons.

Yes, they share most of the code. No, they're not the same.

			Linus

Re: git-log vs git-rev-list

[Petr Baudis]

On Fri, May 30, 2008 at 10:25:47AM -0700, Linus Torvalds wrote:
> On Fri, 30 May 2008, Petr Baudis wrote:
> > 
> >   * git log --pretty=format is actually sane and does not pollute the
> > output with spurious 'commit' lines
> 
> Why would you want to use "git-rev-list" at all?

Because it was the natural command to access history from a script to me
and nothing in the documentation hinted me that I shouldn't use it.

> The common case for git-rev-list is for things that git log simply won't 
> do, ie things like "git rev-list --all --objects" that is a nonsensical 
> operation to do on "git log".

Step back a bit: it's git-_REV_-list. Technically, --all --objects is
nonsensical operation to do on revision list either.

> >   I think that having two commands that by now do essentially the same
> > thing, but slightly differently, is rather messy UI. Thus, I'm wondering
> > if it would be worthwhile to make rev-list a thin git-log wrapper and
> > start phasing it out?
> 
> It already is. It's already phased out in the sense that I don't see why 
> you complain. If you don't like it, don't use it. It has legacy reasons 
> for existing, and it does *some* things that are simply not sensible at 
> all for "git log" (ie the non-commit things).

But there is no indication that it is phased out whatsoever. My point is
that presence of this command is confusing. If it is going to stand
around for non-commit things, it should be called 'git-object-list' or
something, and the difference to git-log should be made clear. But I
think there is no fundamental reason why git-log shouldn't be made able
to list non-commit objects either.

> >   Yes, git-rev-list is supposed to be a plumbing thing, but from my
> > porcelain, I actually have to use git-log anyway [..]
> 
> So why do you care?

Because it confused me, I'm probably not the first to be confused and it
will probably confuse others in the future too. The UI should be more
consistent.

-- 
				Petr "Pasky" Baudis
Whatever you can do, or dream you can, begin it.
Boldness has genius, power, and magic in it.	-- J. W. von Goethe

Re: git-log vs git-rev-list

[Linus Torvalds]

On Fri, 30 May 2008, Petr Baudis wrote:
> > 
> > Why would you want to use "git-rev-list" at all?
> 
> Because it was the natural command to access history from a script to me
> and nothing in the documentation hinted me that I shouldn't use it.

So use it. Or not.

Just don't think it's the same as "git log".

> Step back a bit: it's git-_REV_-list. Technically, --all --objects is
> nonsensical operation to do on revision list either.

Who cares?

Why are you arguing against *facts*?

The *fact* is, git rev-list can traverse the whole object chain.

The *fact* is that git rev-list can do other operations that have nothing 
to do with logs (bisection, for example).

The *fact* is that both git rev-list and git log can traverse a set of 
revisions, but that doesn't make them the same command.

I totally don't see your arguments. They are pointless. git rev-list and 
git log already share all the relevant internal machinery for the things 
where they overlap in capabilities. And the fact that they output 
different things is because they are different.

			Linus

Re: git-log vs git-rev-list

[Petr Baudis]

On Fri, May 30, 2008 at 01:20:13PM -0700, Linus Torvalds wrote:
> On Fri, 30 May 2008, Petr Baudis wrote:
> > Step back a bit: it's git-_REV_-list. Technically, --all --objects is
> > nonsensical operation to do on revision list either.
> 
> Who cares?

You did in case of git log.

> Why are you arguing against *facts*?
> 
> The *fact* is, git rev-list can traverse the whole object chain.
> 
> The *fact* is that git rev-list can do other operations that have nothing 
> to do with logs (bisection, for example).
> 
> The *fact* is that both git rev-list and git log can traverse a set of 
> revisions, but that doesn't make them the same command.

Huh? Of course these are facts, but I don't see what does that have to
do with anything. I'm not arguing this isn't so, I'm arguing it _is_ so
and some of it is _wrong_ from user interface standpoint.

> I totally don't see your arguments. They are pointless. git rev-list and 
> git log already share all the relevant internal machinery for the things 
> where they overlap in capabilities. And the fact that they output 
> different things is because they are different.

My argument is that there should not be two different commands with
similar interface and almost similar feature set when a single interface
would be more than enough - no matter if it is UI or an API, redundant
interfaces mean more clutter for users (or developers) to wade through
and more bitrot for the project. After all, as I said - when I've hit
the rev-list / log inconsitencies, I was not looking for UI but indeed
for an internal helper.


Having said that, I'm fine with Junio's argument that we need to keep
git-rev-list for compatibility reasons as long as the relationship
between git-rev-list and git-log is more clearly documented; I would be
happier if the few remaining options would get implemented for git-log
and git-rev-list got deprecated (which does not mean removing it right
away; git-ssh-push was removed after two years), but I don't care that
much as to flame on, it's too hot over here in Central Europe already.
:-)

I will send some documentation patches soon.


By the way, is git log regarded as porcelain or plumbing? That is, are
there any guarantees about stability of git log output format etc.? Can
I use git log in my script and rely on it to behave forever exactly as
it does now? (Modulo bugfixes.)

-- 
				Petr "Pasky" Baudis
Whatever you can do, or dream you can, begin it.
Boldness has genius, power, and magic in it.	-- J. W. von Goethe

Re: git-log vs git-rev-list

[Linus Torvalds]

On Fri, 30 May 2008, Petr Baudis wrote:
> 
> Because it confused me, I'm probably not the first to be confused and it
> will probably confuse others in the future too. The UI should be more
> consistent.

Btw, the reason this is irrelevant is that "git rev-list" isn't even a UI. 
It's internal plumbing, and almost all of it's flags etc are directly from 
historical reasons. IOW, it does bisection because it used to be the only 
program that did any revision walking. It can do pretty much what git log 
does for the same reason.

So breaking git rev-list because somebody thinks it's "UI" is odd totally 
misses the whole _point_ of the command.

		Linus

Re: git-log vs git-rev-list

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

>   I think that having two commands that by now do essentially the same
> thing, but slightly differently, is rather messy UI. Thus, I'm wondering
> if it would be worthwhile to make rev-list a thin git-log wrapper and
> start phasing it out?

Two answers and a half.

 (1) There are a few things git-log does not do but git-rev-list is
     designed to do.

 (2) They are _already_ thin wrappers to the same core "revision
     traversal" engine, and each of them does what it is meant to do well
     as specified.

 (3) rev-list is an established script interface.  You could enhance it if
     it does not fit your Porcelain needs, but you cannot break it, let
     alone phase it out.  What you can contribute is perhaps to document
     it better so that casual end users do not accidentally try to use
     rev-list as if it is the first class end-user interface and get
     confused.

I do not think there is much to be gained by further refactoring of the
implementations between the two.