git-log vs git-rev-list

  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?

On Fri, 30 May 2008, Petr Baudis wrote:

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.

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).

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

On Fri, May 30, 2008 at 10:25:47AM -0700, Linus Torvalds wrote:

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.

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

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.

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.

On Fri, 30 May 2008, Petr Baudis wrote:

So use it. Or not.

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

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

On Fri, May 30, 2008 at 01:20:13PM -0700, Linus Torvalds wrote:

You did in case of git log.

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.

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.)

On Fri, 30 May 2008, Petr Baudis wrote:

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

Petr Baudis <pasky@suse.cz> writes:

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.