Re: Questions about git-rev-parse

From: Linus Torvalds <torvalds@linux-foundation.org>
Date: Feb 28, 2007, 03:19 UTC
Message-ID: <Pine.LNX.4.64.0702271905200.12485@woody.linux-foundation.org>
In-Reply-To: <E1HMETh-0004BO-Lw@candygram.thunk.org>

On Tue, 27 Feb 2007, Theodore Ts'o wrote:

Show 14 quoted lines

> 
> So I was looking at git-rev-parse trying to understand the man page, as
> I was trying to understand how various commands can accept lists (or
> ranges) of commits, and the man page raised a number of questions.
> First of all, the DESCRIPTION section doesn't quite parse as English:
> 
>        Many  git  porcelainish commands take mixture of flags (i.e. parameters
>        that  begin  with  a  dash  -)  and  parameters  meant  for  underlying
>        git-rev-list  command  they use internally and flags and parameters for
>        other commands they use as the downstream of git-rev-list. 
> 
> But, as best as I can gather that it's a helper function meant to do
> some basic options parsing for those git porcelain commands that expect
> to take a set of revision ID's.

Heh. This is totally due to hysterical raisins.

It literally used to be the case that "git-rev-parse" (the command) would be used to just parse the command line, and do three different things:

 - split "revision flags" from "command flags"

   For example, "--before=<date>" is a revision flag, but "-r" (for 
   "recursive") would be the command-specific flag for doing a diff.

   git-rev-parse was what knew about all the revision parsing flags (and 
   anything that wasn't a revision parsing flag was by definition a 
   subcommand flag).

   It would also actually parse the date itself, and turn a human-readable 
   date like "--before=24.hours.ago" into a git-internal date as seconds 
   since the epoch - so no other git command would ever need to even know.

 - split pathnames from either revision flags _or_ command flags

 - do all the SHA1 arithmetic parsing for revision names, and split 
   revision names from pathnames and flags.

I think to really appreciate the whole scripting basis of very early git versions, do this:

	git show v0.99:git-diff-script

or look at the top few lines of the slightly more complex:

	git show v0.99.9:git-diff.sh

which starts out with:

	rev=$(git-rev-parse --revs-only --no-flags --sq "$@") || exit
	flags=$(git-rev-parse --no-revs --flags --sq "$@")
	files=$(git-rev-parse --no-revs --no-flags --sq "$@")

to parse out all the arguments using "git-rev-parse".

Now, all the argument parsing was made internal to all the common git programs, and there really is no reason to use git-rev-parse any more (unless you actually want to see the SHA1 of some revision expression), but some of the documentation seems to still be based on that old behaviour, where "git-rev-parse" was really a very integral part of parsing the git command line.

You can still see it: try something like

	git-rev-parse --since=24.hours.ago --default HEAD

and you'll see how it parses the command line and turns it into a more primitive form ;)

Show 9 quoted lines

> This raises some additional questions, though.  If the goal of this
> command is to parse out those options and arguments which are meant for
> git-rev-list, why does it translate tag names to SHA id's:
> 
> % git-rev-parse v1.5.0..v1.5.0.1
> dedb0faa48787839dbc47b7ca2507bda5924ec2c
> ^6db027ffe03210324939b3dd655c4223ca023b45
> 
> After all, git-rev-list can just as easily accept:

git-rev-list can accept it _now_, but originally, all the low-level plumbing commands took only the raw hex representations, and git-rev-parse was literally the thing that made it all "look" user-friendly.

Software archeology indeed..

		Linus