RFC patchAdd [] as an alias for a reference to the empty tree

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

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

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.

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

Jeff King <peff@peff.net> writes:

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.

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

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

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

Junio C Hamano wrote:

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

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.

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

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.

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

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

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

Heya,

On Mon, May 10, 2010 at 11:20, Jeff King <peff@peff.net> 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?

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.

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

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

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

Heya,

On Mon, May 10, 2010 at 12:00, Jeff King <peff@peff.net> wrote:

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

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.

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