Questions about git-rev-parse

Questions about git-rev-parse

[Theodore Ts'o]

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.

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 dedb0faa48787839dbc47b7ca2507bda5924ec2c \
		^6db027ffe03210324939b3dd655c4223ca023b45

as

	git-rev-list v1.5.0..v1.5.0.1

Also, there are a number of options in git-rev-list which make it appear
to be a general dumping ground of miscellaneous options.  

For example, it's not clear what 

	git-rev-parse --show-prefix

and

	git-rev-parse --show-cdup

have to do with the description of git-rev-parse as described in the
DESCRIPTION section.  It seems to be completely miscellaneous extras
that were tacked on.  Or am I missing something?

Finally, it seems rather unfortunate that certain bits of functionality
such as --since and --until were hidden into git-rev-parse, since it
means that some commands which are implemented as shell scripts are more
likely to use git-rev-parse, and will therefore support --since and
--until, where as other commands which are implemented as built-in's,
such as git-log, don't accept --since and --until.

So I'm wondering if I'm missing something about historical context,
since from looking at git-rev-parse, it looks like not a lot of thought
went into its design, and it has a bunch of stuff that grew via
accretion; or maybe I'm not understanding why it was designed the way it
was?

Regards,

						- Ted

Re: Questions about git-rev-parse

[Junio C Hamano]

"Theodore Ts'o" <tytso@mit.edu> writes:

> So I'm wondering if I'm missing something about historical context,
> since from looking at git-rev-parse, it looks like not a lot of thought
> went into its design, and it has a bunch of stuff that grew via
> accretion; or maybe I'm not understanding why it was designed the way it
> was?

You are lacking historical context that our porcelain-ish were
all Bourne shell scripts.  If you check out an old version (say
v0.99), it would be apparent why translating symbolic names to
object names and canonicalizing a..b to b ^a were useful to help
them.

These days, "log" family got sufficiently smart that there are
not many reasons to write shell pipeline that has rev-list on
the upstream with diff-tree --stdin on the downstream anymore,
and rev-parse outlived its original purpose of sifting between
rev-list args/flags and others.

Re: Questions about git-rev-parse

[Theodore Tso]

On Tue, Feb 27, 2007 at 06:40:47PM -0800, Junio C Hamano wrote:
> You are lacking historical context that our porcelain-ish were

So while I'm asking questions, where did the "*-ish" terminology come
from, anyway?  For someone who is a relative newbie, terms like
tree-ish and commit-ish seems like some kind of strange, git jargon.
And this is the first time I've come across porcelian-ish.

I had the mental model (which I had intuited, since no git
documentation I could find had bothered to explain it) that -ish meant
something like specifier, so "tree-ish" meant tree specifier, so a
commit id could get dereferenced into a tree id, so it could be used
to specify a tree.

But that explanation doesn't explain "porcelain-ish".  

So what does -ish mean, really?  Where did it come from?  And if it
does add value to use this wierd bit of git jargon, can we document it
somewhere, preferably in a tutorial and main git man page?  It used in
too many places that it's probably not worth it to rip it out, but I
can tell you that for someone who is learning git from the ground up,
it would be easier if we used some term like <tree_specifier> instead
of <tree-ish>.  

Regards,

						- Ted

Re: Questions about git-rev-parse

[Linus Torvalds]

On Tue, 27 Feb 2007, Theodore Ts'o wrote:
> 
> 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 ;)

> 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

Re: Questions about git-rev-parse

[Linus Torvalds]

On Tue, 27 Feb 2007, Theodore Tso wrote:
> 
> So while I'm asking questions, where did the "*-ish" terminology come 
> from, anyway?

It's means "approximate" or "having the character of". Quite like the 
normal English meaning of "thirtyish" or "fortyish" when you talk about 
approximate ages of people, or "tallish" when you talk about height. 
Google for "ish suffix", and you'll get as your first hit:

	http://www.randomhouse.com/wotd/index.pperl?date=19990617

and the git usage is actually just a variation of that.

So a "tree-ish" is not necessarily exactly a tree, but it has all the 
characteristics of a tree (by virtue of there being a well-defined 1:1 
relationship with a tree).

> I had the mental model (which I had intuited, since no git documentation 
> I could find had bothered to explain it) that -ish meant something like 
> specifier, so "tree-ish" meant tree specifier, so a commit id could get 
> dereferenced into a tree id, so it could be used to specify a tree.

No, it really is English. At least grammatically.

A "tree-ish" is "like a tree", exactly like "sheepish" is "like a sheep". 
Nothing really git-specific about it, except for it certainly having 
become common usage in a way that it may not be normally ;)

		Linus

Re: Questions about git-rev-parse

[Theodore Tso]

On Tue, Feb 27, 2007 at 07:33:03PM -0800, Linus Torvalds wrote:
> No, it really is English. At least grammatically.
> 
> A "tree-ish" is "like a tree", exactly like "sheepish" is "like a sheep". 
> Nothing really git-specific about it, except for it certainly having 
> become common usage in a way that it may not be normally ;)

Well, in the randomhouse web page you quoted:

	Our -ish is a suffix that forms adjectives from nouns or other
	adjectives. Some of the senses existed in Old English (then
	spelled -isc but pronounced the same way), such as 'of, being,
	or pertaining to', used to form adjectives indicating a
	national, ethnic, or religious origin (British, Jewish).

it claims that the -ish suffix forms an _adjective_.   But in the sense of

	git describe <committish>

In the git world we are using "committish" (and in the documentation
sometimes we use committish and treeish, and other times we use
commit-ish and tree-ish) as a _noun_, and not an adjective.  So I'm
still going to take a bit of issue that it's grammatical English, and
I still think that "tree_specifier" and "commit_specifier" would have
been clearer.

In any case, I note that in the git(7) man page, there is a formal
definition of tree-ish, but not of commit-ish.  Would this patch to
Documentation/git.txt be correct?

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 9a74747..ff693c3 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -241,6 +241,12 @@ Identifier Terminology
 	operate on a <tree> object but automatically dereferences
 	<commit> and <tag> objects that point at a <tree>.
 
+<commit-ish>::
+	Indicates a commit or tag object name.  A
+	command that takes a <commit-ish> argument ultimately wants to
+	operate on a <commit> object but automatically dereferences
+	<tag> objects that point at a <commit>.
+
 <type>::
 	Indicates that an object type is required.
 	Currently one of: `blob`, `tree`, `commit`, or `tag`.

							- Ted

Re: Questions about git-rev-parse

[Andy Parkins]

On Wednesday 2007 February 28 03:33, Linus Torvalds wrote:

> So a "tree-ish" is not necessarily exactly a tree, but it has all the
> characteristics of a tree (by virtue of there being a well-defined 1:1
> relationship with a tree).

Funny; I'd always guessed that it came from Lord of the Rings, which (I think) 
often mentioned "Ent-ish" as being the language of the trees.  Then the happy 
coincidence of the English idiom usage meaning "approximately" was just a 
happy bonus.

Shocking: something geeky that didn't have an association with Lord of the 
Rings.  What will they think of next? :-)


Andy

-- 
Dr Andy Parkins, M Eng (hons), MIET
andyparkins@gmail.com

Re: Questions about git-rev-parse

[Linus Torvalds]

On Wed, 28 Feb 2007, Andy Parkins wrote:
> 
> Funny; I'd always guessed that it came from Lord of the Rings, which (I think) 
> often mentioned "Ent-ish" as being the language of the trees.

Yeah, we for a while had that overly geekish thing, but we didn't use 
"entish", we used just "ent". Because an "ent" is "tree-ish".

So when we used "ent", we didn't have the "-ish" there at all, and at some 
point all the ents got search-and-replaced into "tree-ish".

But "treeish" actually came before, and the "ent" thing was just a 
temporary pun that got dropped.

Looking at the git log, the first time we use "tree-ish" is fairly early: 
apparently May 5, 2005. Commit ac4e0869 introduces it instead of 
<tree/commit> (probably because the tag part got added, and to explain 
that we only care about the resulting tree and won't actually *use* any 
of the commit/tag information except to get to it).

			Linus

Re: Questions about git-rev-parse

[Willhelm Busch]

On Tue, Feb 27, 2007 at 07:19:54PM -0800, Linus Torvalds wrote:
> On Tue, 27 Feb 2007, Theodore Ts'o wrote:
> >
> > 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.

When it comes to dancing time
 At the branch of the grapevine
Out pop many lively souls,
 From their seed pods, shells, and holes.

'Twas one balmy summer's night
 When some documents to write
Linus rested on the ground
 Near the dancers' cheery round.

Heedless of their drunken rages,
 He cranked out a few man pages,
As he started git-rev-parse,
 Came a merry nighttime farce.

When by wine they are made merry
 Certain fruits wax literary,
Writing nonsense as they please --
 Raisins are the worst of these.

They seized Linus as their chance.
 "Let us leave this odious dance!"
With a hysterical hop,
 Down they jumped, to his laptop!

As they made a small edit,
 Typed the raisins: "git commit"!
"Could my shell prompt be possessed?"
 Linus wondered, much distressed.

Linus scratched his Nordic pate.
 "I should not be up this late!
Coffee's addling my sight!
 Better finish for tonight."

In the main I'm laudatory
 Of the git repository.
It has weirdness and to spare,
 But the raisins put it there.