Newbie / git / gitosis question

Newbie / git / gitosis question

[Howard Miller]

I've been working away at Gitosis and it's mostly fair enough but
there's one bit that's unclear to me...

git push origin master:refs/heads/master

Would somebody kindly explain (or point to docs) what
refs/heads/master means? How is this different from just 'git push
origin master' or even 'git push origin master:master'?

Any insights much appreciated.

Re: Newbie / git / gitosis question

[Michael Wookey]

2009/8/26 Howard Miller <howard@e-learndesign.co.uk>:
> I've been working away at Gitosis and it's mostly fair enough but
> there's one bit that's unclear to me...
>
> git push origin master:refs/heads/master
>
> Would somebody kindly explain (or point to docs) what
> refs/heads/master means? How is this different from just 'git push
> origin master' or even 'git push origin master:master'?
>
> Any insights much appreciated.

You might find some insight here - http://progit.org/book/ch9-5.html

Re: Newbie / git / gitosis question

[Howard Miller]

Mmm...

I think I see what's happening  - vaguely - but I'm not sure I understand why!

Why does gitosis require you to be this specific? Why can't I just do
a 'straight' push?

Howard

2009/8/26 Michael Wookey <michaelwookey@gmail.com>:
> 2009/8/26 Howard Miller <howard@e-learndesign.co.uk>:
>> I've been working away at Gitosis and it's mostly fair enough but
>> there's one bit that's unclear to me...
>>
>> git push origin master:refs/heads/master
>>
>> Would somebody kindly explain (or point to docs) what
>> refs/heads/master means? How is this different from just 'git push
>> origin master' or even 'git push origin master:master'?
>>
>> Any insights much appreciated.
>
> You might find some insight here - http://progit.org/book/ch9-5.html
>

Re: Newbie / git / gitosis question

[Graham Perks]

On Aug 26, 2009, at 4:27 AM, Howard Miller wrote:
> there's one bit that's unclear to me...
>
> git push origin master:refs/heads/master
>
> Would somebody kindly explain (or point to docs) what
> refs/heads/master means?

I wish somehow these refs would be hidden so newbies like me and  
everyone I introduce to git didn't have to know about them. They feel  
like an "advanced concept", some internal syntax that 99% of users  
shouldn't need to know about. When I see a refspec in the help pages  
my eyes glaze over!

Graham.

Re: Newbie / git / gitosis question

[Jeff King]

On Wed, Aug 26, 2009 at 10:27:30AM +0100, Howard Miller wrote:

> I've been working away at Gitosis and it's mostly fair enough but
> there's one bit that's unclear to me...
> 
> git push origin master:refs/heads/master
> 
> Would somebody kindly explain (or point to docs) what
> refs/heads/master means? How is this different from just 'git push
> origin master' or even 'git push origin master:master'?

I'll try to explain.

Refs are pointers to commits. In other words, you can think of
"refs/heads/master" as a key pointing to a SHA-1 commit id. The long-ish
name divides up the namespace for refs.

There are a few special refs that live outside of the refs/ hierarchy,
like HEAD, FETCH_HEAD, MERGE_HEAD, ORIG_HEAD, etc. Normal refs are
generally under refs/.

The refs/heads/ hierarchy is for branches (they are the "head" of a line
of development). The refs/tags hierarchy is for tags. The refs/remotes
hierarchy is where we store our local idea of where remote repositories'
branches point.

Pushing (and fetching) take a "refspec": two refs, a source and
destination, separated by a colon. So "git push foo:bar" means "look up
my local ref 'foo' and update or create the remote ref 'bar' with the
same commit".

Every ref has a "full name" that is much longer than what we often
see. We can generally abbreviate because one of the following applies:

  1. We are specifying a name to look up, and there is a set of lookup
     rules. For example, the name "master" will be considered as a tag,
     and then as a branch, and then as a remote branch.

     The lookup rules are described in "git help rev-parse" under the
     section "Specifying Revisions".

  2. We are using a name in a context that expects a particular type.
     For example, "git branch foo" knows that "foo" is a new branch
     name, and so will create the ref as refs/heads/foo. Similarly "git
     tag foo" will create refs/tags/foo.

  3. We can infer the type from the other half of a refspec. For
     example, given a local branch "master" and a tag "v1.0" (and
     neither currently existing on the remote side), we can do:

       git push origin master:master v1.0:v1.0

     and we know that the "master" we create on the remote will be a
     branch, because the local "master" is a branch, and similarly the
     "v1.0" we create on the remote will be a tag because the local
     "v1.0" is a tag.

And finally, "git push" knows a shorthand for refspecs: a refspec
without a colon is treated as having the same string on both sides. So
"master" is really a shortcut for "master:master".

Knowing all of that, let's look at your examples:

  A. git push origin master

     This is really a syntactic shortcut for "git push origin
     master:master".

  B. git push origin master:master

     The left-hand side of the refspec is looked up locally. In this
     case, it is probably going to be "refs/heads/master". The right-hand
     side is looked up on the remote. If it exists (i.e., you are
     updating your branch), it is probably "refs/heads/master".

     If it doesn't exist on the remote (i.e., you are pushing a new
     branch), then we can infer from the prefix of the left-hand side
     that the right-hand side should also be a branch (i.e., under
     "refs/heads/").

     So assuming "master" is a branch, this is really equivalent to:

       git push origin refs/heads/master:refs/heads/master

  C. git push origin master:refs/heads/master

     If you understood the explanation for (B) above, you will know that
     this is again basically the same thing. :)

     However, note that in (B), if the branch is being created on the
     remote, we rely on the "refspec inference" rule described earlier.
     This behavior was adopted in git in v1.5.5.2 (commit f8aae120,
     2008-04-23). So you may still see examples that pre-date this
     feature and recommend using the full ref-name, which should no
     longer be necessary.

Hope that helps. Let me know if you need clarification on any of the
above.

-Peff