From: Teemu Likonen <tlikonen@iki.fi>
Date: Wed, 09 Apr 2008 20:08:36 GMT
Subject: Friendly refspecs (Was: Re: git annoyances)
Message-ID: <20080409200836.GA19248@mithlond>
In-Reply-To: <20080409145758.GB20874@sigill.intra.peff.net>

Jeff King wrote (2008-04-09 10:57 -0400):

>   git-fetch <options> <repository> <refspec>

I have found this refs/heads/*:refs/remotes/* stuff quite confusing, but
I'm starting to understand them. I know my way with them but still they
seem quite unnecessary hackerish. Pull and push work pretty nicely
without knowing about any refs/* stuff; they can be operated with simple
branch names. Fetch is another story. Some ideas:

  $ git fetch <URL>

would be equivalent to

  $ git fetch <URL> +refs/heads/*:refs/remotes/<name>/*

In other words, fetch all the branches from remote repo and store them
locally as remote tracking branches to <name>/ hieararchy. The <name> is
the last component taken from the <URL> (maybe "origin" if it can't be
detected). 

Currently "git fetch <URL>" does not seem to do anything useful for
non-git-hackers. It seems to fetch objects but not create any branches
referring to them. As a comparison, let's configure a remote and run
similar fetch command without any refspecs explicitly named:

  $ git remote add <name> <URL>
  $ git fetch <name>

Now this fetch really creates all the branches (as defined in
remote.<name>.fetch) which is nice and the way Git currently works.

So would it be any good if "git fetch <URL>" without refpecs would use
+refs/heads/*:refs/remotes/<name>/* ? In any case the current behaviour
seems quite unfriendly.

Some more ideas for simple refspecs:

  $ git fetch <URL|name> <branch>

would be equivalent to

  $ git fetch <URL|name> +refs/heads/<branch>:refs/remotes/<name>/<branch>

Again the same behaviour with <URL> and configured remote <name>. In the
<URL> case the <name> is the last component of the <URL>.

  $ git fetch <URL|name> <Rbranch>:<Lbranch>

would be equivalent to

  $ git fetch <URL|name> +refs/heads/<Rbranch>:refs/remotes/<Lbranch>

Note that by giving the destination branch (the right side of colon) the
new remote tracking branch would be created directly to the
refs/remotes/ hierarchy, not to refs/remotes/<name>/ hierarchy like in
previous examples. This lets user a bit more control as she decided to
give <Lbranch> explicitly. User may want to give refspec
master:<name>/master to have new branch created as
refs/remotes/<name>/master.

With above example commands it is not possible to fetch remote branches
and store refs locally to refs/heads/ hierarchy. For this it would
either need another step - "git branch my-branch <name>/master" - or use
the long refspec form with fetch:
+refs/heads/master:refs/heads/my-branch .

Does this sound any good?