* What's the definition of a valid Git symbolic reference?
@ 2011-02-14 20:58 Emeric Fermas
2011-02-15 3:19 ` Kevin Ballard
0 siblings, 1 reply; 8+ messages in thread
From: Emeric Fermas @ 2011-02-14 20:58 UTC (permalink / raw)
To: git; +Cc: Vicent Marti, libgit2
Hello,
I'm one of the contributors of libgit2 (http://libgit2.github.com/).
I'm currently working on the handling of refs and I'd like to get a
better understanding of git symbolic references.
In order to avoid polluting this list with an easy to answer noob
question, I firsty asked this question on stackoverflow
(http://stackoverflow.com/q/4986000). However, I do not have the
feeling that I'm getting some definite "carved-in-stone" answers.
This explains why I'm posting it here today.
The following shell code correctly creates a chain of symbolic references
git symbolic-ref "first" "refs/heads/master"
git symbolic-ref "second" "first"
git symbolic-ref "nested/third" "second"
git symbolic-ref "refs/heads/fourth" "nested/third"
And the following shell code correctly resolves the latest created
symbolic reference to the tip of master.
git show-ref "refs/heads/fourth"
None of these use cases are described in the official documentation
(git-symbolic-ref doc, git-show-ref doc).
However, the following doesn't work
git check-ref-format --print "first"
So, my questions are:
- Is it ok to store a symbolic reference within the refs/heads directory ?
- Is it ok to chain symbolic references ?
- As check-ref-format fails when being passed "first", does this mean
that it's not recommended to create a symbolic reference at the same
level than "HEAD"? Or maybe this command is not intended to deal with
symbolic links ?
My intent is to get a clear understanding of what is being supported
and that I'm not working around anything or benefiting from a bug.
Thanks in advance for any help you could provide me with.
Cheers,
Em.
Em.
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: What's the definition of a valid Git symbolic reference?
2011-02-14 20:58 What's the definition of a valid Git symbolic reference? Emeric Fermas
@ 2011-02-15 3:19 ` Kevin Ballard
2011-02-15 3:49 ` Emeric Fermas
0 siblings, 1 reply; 8+ messages in thread
From: Kevin Ballard @ 2011-02-15 3:19 UTC (permalink / raw)
To: Emeric Fermas; +Cc: git, Vicent Marti, libgit2
On Feb 14, 2011, at 12:58 PM, Emeric Fermas wrote:
> - As check-ref-format fails when being passed "first", does this mean
> that it's not recommended to create a symbolic reference at the same
> level than "HEAD"? Or maybe this command is not intended to deal with
> symbolic links ?
I don't know about the rest of your question, but check-ref-format
explicitly states in the manpage that the refname must have at least
one /, to enforce the presence of a category (such as heads/) in the
refname.
-Kevin Ballard
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: What's the definition of a valid Git symbolic reference?
2011-02-15 3:19 ` Kevin Ballard
@ 2011-02-15 3:49 ` Emeric Fermas
2011-02-15 5:02 ` Tomas Carnecky
2011-02-15 6:22 ` Junio C Hamano
0 siblings, 2 replies; 8+ messages in thread
From: Emeric Fermas @ 2011-02-15 3:49 UTC (permalink / raw)
To: Kevin Ballard; +Cc: git, Vicent Marti, libgit2
Thanks a lot for this answer.
I've also read the man page of check-ref-format. However, there may be
some not up-to-date documentation or some "non guarded against"
command usage in git.
This explains the second part of my question ("Or maybe this command
(ie. check-ref-format) is not intended to deal with symbolic links
?").
Another possibility would be that only git internal symbolic
references are allowed to live under the ".git" dir (HEAD, FETCH_HEAD,
...) and that user defined symrefs should live under refs/. In this
case, maybe "git symbolic-ref" should also prevent the user from
creating a reference which doesn't contains a forward slash.
Once again, by reading at the code I can understand how those commands
currently work. What I'm trying to achieve is to understand what
should be their recommended usage.
Of course, I'll be glad to contribute any code/doc patch once the
"voice of the git community" has spoken :-)
Em.
On Tue, Feb 15, 2011 at 4:19 AM, Kevin Ballard <kevin@sb.org> wrote:
> On Feb 14, 2011, at 12:58 PM, Emeric Fermas wrote:
>
>> - As check-ref-format fails when being passed "first", does this mean
>> that it's not recommended to create a symbolic reference at the same
>> level than "HEAD"? Or maybe this command is not intended to deal with
>> symbolic links ?
>
> I don't know about the rest of your question, but check-ref-format
> explicitly states in the manpage that the refname must have at least
> one /, to enforce the presence of a category (such as heads/) in the
> refname.
>
> -Kevin Ballard
>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: What's the definition of a valid Git symbolic reference?
2011-02-15 3:49 ` Emeric Fermas
@ 2011-02-15 5:02 ` Tomas Carnecky
2011-02-19 13:10 ` Kevin P. Fleming
2011-02-15 6:22 ` Junio C Hamano
1 sibling, 1 reply; 8+ messages in thread
From: Tomas Carnecky @ 2011-02-15 5:02 UTC (permalink / raw)
To: Emeric Fermas; +Cc: Kevin Ballard, git, Vicent Marti, libgit2
On 2/15/11 4:49 AM, Emeric Fermas wrote:
> Another possibility would be that only git internal symbolic
> references are allowed to live under the ".git" dir (HEAD, FETCH_HEAD,
> ...) and that user defined symrefs should live under refs/. In this
All refs should live under refs/ (except the special ones like HEAD
etc). It's usually a mistake if someone manages to create one outside of
refs/. The plumbing commands allow you to do that, but users usually
shouldn't use those.
tom
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: What's the definition of a valid Git symbolic reference?
2011-02-15 5:02 ` Tomas Carnecky
@ 2011-02-19 13:10 ` Kevin P. Fleming
0 siblings, 0 replies; 8+ messages in thread
From: Kevin P. Fleming @ 2011-02-19 13:10 UTC (permalink / raw)
To: Tomas Carnecky; +Cc: Emeric Fermas, Kevin Ballard, git, Vicent Marti, libgit2
On 02/14/2011 11:02 PM, Tomas Carnecky wrote:
> On 2/15/11 4:49 AM, Emeric Fermas wrote:
>> Another possibility would be that only git internal symbolic
>> references are allowed to live under the ".git" dir (HEAD, FETCH_HEAD,
>> ...) and that user defined symrefs should live under refs/. In this
>
> All refs should live under refs/ (except the special ones like HEAD
> etc). It's usually a mistake if someone manages to create one outside of
> refs/. The plumbing commands allow you to do that, but users usually
> shouldn't use those.
Being able to manually point HEAD at a ref is actually useful; when I've
created repos that start out with a 'vendor branch', I want to do the
initial import into a branch called 'upstream', not 'master'. Using 'git
symbolic-ref HEAD refs/heads/upstream' in a brand-new repo allows that
to happen, and works quite well.
Please don't take it away :-)
--
Kevin P. Fleming
Digium, Inc. | Director of Software Technologies
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
skype: kpfleming | jabber: kfleming@digium.com
Check us out at www.digium.com & www.asterisk.org
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: What's the definition of a valid Git symbolic reference?
2011-02-15 3:49 ` Emeric Fermas
2011-02-15 5:02 ` Tomas Carnecky
@ 2011-02-15 6:22 ` Junio C Hamano
2011-02-15 6:32 ` Emeric Fermas
2011-02-15 7:09 ` Jeff King
1 sibling, 2 replies; 8+ messages in thread
From: Junio C Hamano @ 2011-02-15 6:22 UTC (permalink / raw)
To: Emeric Fermas; +Cc: Kevin Ballard, git, Vicent Marti, libgit2
Emeric Fermas <emeric.fermas@gmail.com> writes:
> Once again, by reading at the code I can understand how those commands
> currently work. What I'm trying to achieve is to understand what
> should be their recommended usage.
There are only two valid kinds of symrefs right now:
- .git/HEAD, pointing at somewhere under refs/heads/ hierarchy;
- .git/refs/remotes/<some remote name>/HEAD, pointing at somewhere under
refs/remotes/<the same remote name>/ hierarchy.
The code may be prepared to resolve recursive symrefs, symrefs other than
the above two kinds, symrefs that point at elsewhere, but all of them are
outside of the design scope of what the mechanism was intended to support.
What the code do to them (without crashing) is not the design, but simply
an undefined behaviour.
This won't change very much if we decide to reorganize the remote tracking
hierarchies in 1.8.0. The former won't change at all, and the latter will
start pointing at refs/remotes/<the same remote name>/heads hierarchy
instead.
I vaguely recall tg abused the symref mechanism to point .git/HEAD at
funny locations; it may still be doing so, and if that is the case we
should extend the above list to cover that usage.
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: What's the definition of a valid Git symbolic reference?
2011-02-15 6:22 ` Junio C Hamano
@ 2011-02-15 6:32 ` Emeric Fermas
2011-02-15 7:09 ` Jeff King
1 sibling, 0 replies; 8+ messages in thread
From: Emeric Fermas @ 2011-02-15 6:32 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Kevin Ballard, git, Vicent Marti, libgit2
Thanks a lot for this very clear explanation. All my questions have
found an answer.
Cheers,
Em.
On Tue, Feb 15, 2011 at 7:22 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Emeric Fermas <emeric.fermas@gmail.com> writes:
>
>> Once again, by reading at the code I can understand how those commands
>> currently work. What I'm trying to achieve is to understand what
>> should be their recommended usage.
>
> There are only two valid kinds of symrefs right now:
>
> - .git/HEAD, pointing at somewhere under refs/heads/ hierarchy;
>
> - .git/refs/remotes/<some remote name>/HEAD, pointing at somewhere under
> refs/remotes/<the same remote name>/ hierarchy.
>
> The code may be prepared to resolve recursive symrefs, symrefs other than
> the above two kinds, symrefs that point at elsewhere, but all of them are
> outside of the design scope of what the mechanism was intended to support.
> What the code do to them (without crashing) is not the design, but simply
> an undefined behaviour.
>
> This won't change very much if we decide to reorganize the remote tracking
> hierarchies in 1.8.0. The former won't change at all, and the latter will
> start pointing at refs/remotes/<the same remote name>/heads hierarchy
> instead.
>
> I vaguely recall tg abused the symref mechanism to point .git/HEAD at
> funny locations; it may still be doing so, and if that is the case we
> should extend the above list to cover that usage.
>
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: What's the definition of a valid Git symbolic reference?
2011-02-15 6:22 ` Junio C Hamano
2011-02-15 6:32 ` Emeric Fermas
@ 2011-02-15 7:09 ` Jeff King
1 sibling, 0 replies; 8+ messages in thread
From: Jeff King @ 2011-02-15 7:09 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Emeric Fermas, Kevin Ballard, git, Vicent Marti, libgit2
On Mon, Feb 14, 2011 at 10:22:55PM -0800, Junio C Hamano wrote:
> Emeric Fermas <emeric.fermas@gmail.com> writes:
>
> > Once again, by reading at the code I can understand how those commands
> > currently work. What I'm trying to achieve is to understand what
> > should be their recommended usage.
>
> There are only two valid kinds of symrefs right now:
>
> - .git/HEAD, pointing at somewhere under refs/heads/ hierarchy;
>
> - .git/refs/remotes/<some remote name>/HEAD, pointing at somewhere under
> refs/remotes/<the same remote name>/ hierarchy.
Nit: the notes merge code uses NOTES_MERGE_REF as a symref to a notes
ref. See the create_symref call in builtin/notes.c.
I don't think that changes your point much, though.
> The code may be prepared to resolve recursive symrefs, symrefs other than
> the above two kinds, symrefs that point at elsewhere, but all of them are
> outside of the design scope of what the mechanism was intended to support.
> What the code do to them (without crashing) is not the design, but simply
> an undefined behaviour.
I was always under the impression that you could generally use symbolic
refs to point wherever you wanted inside the refs hierarchy as a
replacement for symlinks (I don't know how the latter would deal with
ref packing, though). But I think that was just my assumption rather
than anything that was ever communicated officially.
-Peff
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2011-02-19 13:11 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-02-14 20:58 What's the definition of a valid Git symbolic reference? Emeric Fermas
2011-02-15 3:19 ` Kevin Ballard
2011-02-15 3:49 ` Emeric Fermas
2011-02-15 5:02 ` Tomas Carnecky
2011-02-19 13:10 ` Kevin P. Fleming
2011-02-15 6:22 ` Junio C Hamano
2011-02-15 6:32 ` Emeric Fermas
2011-02-15 7:09 ` Jeff King
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).