[PATCH/RFC] Add [] as an alias for a reference to the empty tree

[PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Peter Kjellerstedt]

Instead of specifying the SHA1 for the empty tree (i.e.,
4b825dc642cb6eb9a060e54bf8d69288fbee4904) one can now say [], e.g.,
'git diff [] v1.7.1' would give all the changes between the empty tree
and the tag v1.7.1.

The rationale for selecting [] as the alias for the empty tree was that
it looks empty, the brackets are not used for anything related to
references (AFAIK), they are not allowed in references according to
'man git-check-ref-format', and the syntax can easily be extended to
allow other types of references by adding information between the
brackets.

Signed-off-by: Peter Kjellerstedt <pkj@axis.com>
---
 sha1_name.c |    3 +++
 1 files changed, 3 insertions(+), 0 deletions(-)

This is in response to the discussion in [1]. I am not sure the use of
'[]' as an alias for the empty tree will be accepted, but I think having
an alias similar to this is much easier to implement than adding support
for a --root option to all commands which can take a <tree-ish>...

Since this is mostly an RFC I have not included any new tests (though
the existsing once still pass after this change).

[1] http://thread.gmane.org/gmane.comp.version-control.git/146468/focus=146484

diff --git a/sha1_name.c b/sha1_name.c
index bf92417..ba58eab 100644
--- a/sha1_name.c
+++ b/sha1_name.c
@@ -347,6 +347,9 @@ static int get_sha1_basic(const char *str, int len, unsigned char *sha1)
 	int refs_found = 0;
 	int at, reflog_len;
 
+	if (len == 2 && str[0] == '[' && str[1] == ']')
+		return get_sha1_hex(EMPTY_TREE_SHA1_HEX, sha1);
+
 	if (len == 40 && !get_sha1_hex(str, sha1))
 		return 0;
 
-- 
1.7.0.1

Re: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Jeff King]

On Fri, May 07, 2010 at 06:37:27PM +0200, Peter Kjellerstedt wrote:

> Instead of specifying the SHA1 for the empty tree (i.e.,
> 4b825dc642cb6eb9a060e54bf8d69288fbee4904) one can now say [], e.g.,
> 'git diff [] v1.7.1' would give all the changes between the empty tree
> and the tag v1.7.1.

FWIW, I like the idea of a special namespace that indicates "this is not
a regular ref, but you can resolve it to some object". It seems to come
up once in a while, but I don't recall anybody ever actually making a
patch.

> The rationale for selecting [] as the alias for the empty tree was that
> it looks empty, the brackets are not used for anything related to
> references (AFAIK), they are not allowed in references according to
> 'man git-check-ref-format', and the syntax can easily be extended to
> allow other types of references by adding information between the
> brackets.

I am a little iffy on brackets, as they can invoke shell wildcarding
behavior. But the fact that they don't cause a syntactic conflict does
make them appealing.

Based on past discussions, I suspect other people would be interested
in:

  $ git diff [index] HEAD
  $ git diff HEAD [index]
  $ git diff [working-tree] [index]

etc. I don't think I would want to type those all the time, but they
conceptually are quite clear about what is happening, so they may be
nice for showing new users what is happening with each diff invocation
(as opposed to, say, "git diff --cached" versus "git diff", which is
somewhat unintuitive, even though it is more handy in practice).

-Peff

Re: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> Based on past discussions, I suspect other people would be interested
> in:
>
>   $ git diff [index] HEAD
>   $ git diff HEAD [index]
>   $ git diff [working-tree] [index]
>
> etc. I don't think I would want to type those all the time,...

If you go that route, why not use INDEX and WORKTREE (all caps) to at
least avoid the brackets?  I am not personally interested in [] at all,
but as part of that repertoire of syntactic sugar tokens EMPTY might be
able to sneak in [*1*]

[Footnote]

*1* Without that "[]" syntax, the feature is "Meh" for me, but with the
syntax, it becomes "Yuck".  The reason I am not interested in the feature
is because I don't see much value in running "git diff EMPTY <anything>".
Perhaps "git archive" might be what the user really wants to find.

Re: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Jeff King]

On Fri, May 07, 2010 at 10:24:57PM -0700, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > Based on past discussions, I suspect other people would be interested
> > in:
> >
> >   $ git diff [index] HEAD
> >   $ git diff HEAD [index]
> >   $ git diff [working-tree] [index]
> >
> > etc. I don't think I would want to type those all the time,...
> 
> If you go that route, why not use INDEX and WORKTREE (all caps) to at
> least avoid the brackets?  I am not personally interested in [] at all,
> but as part of that repertoire of syntactic sugar tokens EMPTY might be
> able to sneak in [*1*]

Yeah, I would be fine with that (and I think I even suggested it the
last time this came up). In theory we can be breaking somebody's repo by
stealing from the valid ref namespace, but it really is not all that
likely (and I suppose we could prefer user refs).

> *1* Without that "[]" syntax, the feature is "Meh" for me, but with the
> syntax, it becomes "Yuck".  The reason I am not interested in the feature
> is because I don't see much value in running "git diff EMPTY <anything>".
> Perhaps "git archive" might be what the user really wants to find.

Somehow it comes up for me every once in a while, and I go look up the
empty tree sha1 in the source and use it, think "it would be nice if
there was a handy syntax", and then realize that it is the sort of thing
that only comes up infrequently, and even then only when you are trying
to do something a little odd, so it probably isn't worth caring about. I
wish I could remember the reason for the last time I needed it, but I
can't.

-Peff

Re: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Jonathan Nieder]

Junio C Hamano wrote:

> The reason I am not interested in the feature
> is because I don't see much value in running "git diff EMPTY <anything>".
> Perhaps "git archive" might be what the user really wants to find.

I suspect the goal was to use a tool such as checkpatch, or
get_maintainer without -f.  An implementation using git archive should
still work (with the help of a tar diff-ing program with the EMPTY
feature ;-)), but as UI that might be less discoverable than building
it into git diff.

Personally, I liked both the

  git diff $(</dev/null git hash-object -t tree --stdin) $rev

and

  git diff --root $rev

suggestions.  That may be from a warped sense of aesthetics.

Cheers,
Jonathan

RE: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Peter Kjellerstedt]

> -----Original Message-----
> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On
> Behalf Of Junio C Hamano
> Sent: den 8 maj 2010 07:25
> To: Jeff King
> Cc: Peter Kjellerstedt; git@vger.kernel.org
> Subject: Re: [PATCH/RFC] Add [] as an alias for a reference to the
> empty tree
> 
> Jeff King <peff@peff.net> writes:
> 
> > Based on past discussions, I suspect other people would be interested
> > in:
> >
> >   $ git diff [index] HEAD
> >   $ git diff HEAD [index]
> >   $ git diff [working-tree] [index]

Interesting. I had not thought of that, but I can see the use for it
in some situations if nothing else but to clarify what is going on.

> > etc. I don't think I would want to type those all the time,...

Well, I have to agree on that, even though I guess they could be 
abbreviated like [i] and [wt].

> If you go that route, why not use INDEX and WORKTREE (all caps) to at
> least avoid the brackets?  I am not personally interested in [] at all,
> but as part of that repertoire of syntactic sugar tokens EMPTY might be
> able to sneak in [*1*]

The reason I choose to use some special characters like [] was that I 
explicitly did not want to touch the normal namespace for references,
since these refs do not actually exist in the .git directory and things
could get a bit surprising if someone actually created a branch/tag
named INDEX...

However, if INDEX, WORKTREE and EMPTY are preferred as syntactic sugar
tokes, then that is fine by me. Unfortunately, I do not have the time
nor the knowledge needed to add support for the INDEX and WORKTREE 
tokens, so I am afraid I will have to leave this as a suggestion for 
the future.

> [Footnote]
> 
> *1* Without that "[]" syntax, the feature is "Meh" for me, but with the
> syntax, it becomes "Yuck".  The reason I am not interested in the
> feature is because I don't see much value in running "git diff EMPTY
> <anything>". Perhaps "git archive" might be what the user really wants 
> to find.

As I mentioned in [1] I am post-processing the generated diff, and then 
the empty tree is just another starting point for the diff. Having to 
get the full content some other way (e.g., via git archive) would just
mean a lot of unnecessary code and special casing in this case.

//Peter

[1] http://thread.gmane.org/gmane.comp.version-control.git/146468/focus=146518

Re: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Jeff King]

On Mon, May 10, 2010 at 10:14:15AM +0200, Peter Kjellerstedt wrote:

> However, if INDEX, WORKTREE and EMPTY are preferred as syntactic sugar
> tokes, then that is fine by me. Unfortunately, I do not have the time
> nor the knowledge needed to add support for the INDEX and WORKTREE 
> tokens, so I am afraid I will have to leave this as a suggestion for 
> the future.

Implementing INDEX and WORKTREE would be quite challenging. EMPTY is
easy because it is really just a fake ref for a particular sha1. The
others need special casing everywhere that might look at the result.

So certainly if you want to do EMPTY, I wouldn't let the lack of the
other two hold you back. The only reason they are related at all is that
they would probably share a syntax, if the other two ever even get
implemented.

-Peff

Re: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Sverre Rabbelier]

Heya,

On Mon, May 10, 2010 at 11:20, Jeff King <peff@peff.net> wrote:
>> However, if INDEX, WORKTREE and EMPTY are preferred as syntactic sugar
>> tokes, then that is fine by me.

Must it be ALL CAPS? In Mercurial the fairly elegant 'nil' is used for
the empty commit, why can't we do the same?

> So certainly if you want to do EMPTY, I wouldn't let the lack of the
> other two hold you back. The only reason they are related at all is that
> they would probably share a syntax, if the other two ever even get
> implemented.

I still don't see the point in having INDEX and WORKTREE, especially
since they're so CAPSY. Almost as if they're supposed to be
environment variables.

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Jeff King]

On Mon, May 10, 2010 at 11:51:05AM +0200, Sverre Rabbelier wrote:

> On Mon, May 10, 2010 at 11:20, Jeff King <peff@peff.net> wrote:
> >> However, if INDEX, WORKTREE and EMPTY are preferred as syntactic sugar
> >> tokes, then that is fine by me.
> 
> Must it be ALL CAPS? In Mercurial the fairly elegant 'nil' is used for
> the empty commit, why can't we do the same?

[Please watch your quoting, which is a bit misleading there].

I think the intent was that because they clash in the normal refs
namespace, we would set them apart with caps (and we have already
sort-of claimed the all-caps namespace with things like HEAD,
FETCH_HEAD, etc).

> > So certainly if you want to do EMPTY, I wouldn't let the lack of the
> > other two hold you back. The only reason they are related at all is that
> > they would probably share a syntax, if the other two ever even get
> > implemented.
> 
> I still don't see the point in having INDEX and WORKTREE, especially
> since they're so CAPSY. Almost as if they're supposed to be
> environment variables.

The point was to make a more obvious and verbose alternative for people
who find "git diff" a little confusing. E.g.:

  # diff index to working tree
  # (now)
  git diff
  # (verbose)
  git diff INDEX..WORKTREE

  # diff HEAD to index
  # (now)
  git diff --cached
  # (verbose)
  git diff HEAD..INDEX

  # diff HEAD to working tree
  # (now)
  git diff HEAD
  # (verbose)
  git diff HEAD..WORKTREE

I think the original proposal is from this post-GitTogether 2008 thread:

  http://thread.gmane.org/gmane.comp.version-control.git/99376/focus=100729

-Peff

Re: [PATCH/RFC] Add [] as an alias for a reference to the empty tree

[Sverre Rabbelier]

Heya,

On Mon, May 10, 2010 at 12:00, Jeff King <peff@peff.net> wrote:
> On Mon, May 10, 2010 at 11:51:05AM +0200, Sverre Rabbelier wrote:
>> Must it be ALL CAPS? In Mercurial the fairly elegant 'nil' is used for
>> the empty commit, why can't we do the same?
>
> [Please watch your quoting, which is a bit misleading there].

Apologies, I accidentally removed Junio's attribution line. I fully
intended to reply to both your and Junio's post at the same time :).

> I think the intent was that because they clash in the normal refs
> namespace, we would set them apart with caps (and we have already
> sort-of claimed the all-caps namespace with things like HEAD,
> FETCH_HEAD, etc).

While I understand the rationale, (of already having two all-caps
refs), I don't think adding more of them is a good idea. Aesthetically
I think 'nil' does make sense, but I agree that 'worktree' and 'index'
as lower-case names do not.

> The point was to make a more obvious and verbose alternative for people
> who find "git diff" a little confusing. E.g.:

I don't think that all caps names make for a good solution to that
problem though.

-- 
Cheers,

Sverre Rabbelier