# [PATCH] Documentation: Define symref and update HEAD description 3 messages from 2006-11-18 to 2006-11-18. Participants: Petr Baudis, Junio C Hamano. Thread: https://gitlist.dev/t/43318 ## Petr Baudis, 2006-11-18 19:44 Subject: [PATCH] Documentation: Define symref and update HEAD description Message-ID: <20061118194408.27106.65771.stgit@machine.or.cz> URL: https://gitlist.dev/e/20061118194408.27106.65771.stgit%40machine.or.cz ``` HEAD was still described as a symlink instead of a symref. Signed-off-by: Petr Baudis --- Documentation/glossary.txt | 7 +++++++ Documentation/repository-layout.txt | 14 +++++++++----- 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt index 7e560b0..894883d 100644 --- a/Documentation/glossary.txt +++ b/Documentation/glossary.txt @@ -282,6 +282,13 @@ SCM:: SHA1:: Synonym for object name. +symref:: + Symbolic reference: instead of containing the SHA1 id itself, it + is of the format 'ref: refs/some/thing' and when referenced, it + recursively dereferences to this reference. 'HEAD' is a prime + example of a symref. Symbolic references are manipulated with + the gitlink:git-symbolic-ref[1] command. + topic branch:: A regular git branch that is used by a developer to identify a conceptual line of development. Since branches diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 275d18b..fd9f406 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -70,12 +70,16 @@ refs/tags/`name`:: object, or a tag object that points at a commit object). HEAD:: - A symlink of the form `refs/heads/'name'` to point at - the current branch, if exists. It does not mean much if - the repository is not associated with any working tree + A symref (see glossary) to the `refs/heads/` namespace + describing the currently active branch. It does not mean + much if the repository is not associated with any working tree (i.e. a 'bare' repository), but a valid git repository - *must* have such a symlink here. It is legal if the - named branch 'name' does not (yet) exist. + *must* have the HEAD file; some porcelains may use it to + guess the designated "default" branch of the repository + (usually 'master'). It is legal if the named branch + 'name' does not (yet) exist. In some legacy setups, it is + a symbolic link instead of a symref, but this has been + deprecated long ago. branches:: ``` ## Junio C Hamano, 2006-11-18 19:55 Subject: Re: [PATCH] Documentation: Define symref and update HEAD description Message-ID: <7v64dccyx2.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7v64dccyx2.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <20061118194408.27106.65771.stgit@machine.or.cz> ``` Petr Baudis writes: > HEAD was still described as a symlink instead of a symref. >... > HEAD:: > + A symref (see glossary) to the `refs/heads/` namespace > + describing the currently active branch. It does not mean > + much if the repository is not associated with any working tree > (i.e. a 'bare' repository), but a valid git repository > + *must* have the HEAD file; some porcelains may use it to > + guess the designated "default" branch of the repository > + (usually 'master'). It is legal if the named branch > + 'name' does not (yet) exist. In some legacy setups, it is > + a symbolic link instead of a symref, but this has been > + deprecated long ago. We fully support dealing with repositories with symlinked HEAD, and will continue to do so; I do not think we ever talked about deprecating it. Public "distribution point" repositories that have been established long ago that do not have reason to switch HEAD to point at different branch still have symlinked HEAD and they should continue to work. What we _don't_ do these days is to set up new repositories with symlinked HEAD, but that does not have anything to do with deprecating symlinked HEAD. ``` ## Petr Baudis, 2006-11-18 21:31 Subject: Re: [PATCH] Documentation: Define symref and update HEAD description Message-ID: <20061118213153.GR7201@pasky.or.cz> URL: https://gitlist.dev/e/20061118213153.GR7201%40pasky.or.cz In-Reply-To: <7v64dccyx2.fsf@assigned-by-dhcp.cox.net> ``` On Sat, Nov 18, 2006 at 08:55:37PM CET, Junio C Hamano wrote: > Petr Baudis writes: > > > HEAD was still described as a symlink instead of a symref. > >... > > HEAD:: > > + A symref (see glossary) to the `refs/heads/` namespace > > + describing the currently active branch. It does not mean > > + much if the repository is not associated with any working tree > > (i.e. a 'bare' repository), but a valid git repository > > + *must* have the HEAD file; some porcelains may use it to > > + guess the designated "default" branch of the repository > > + (usually 'master'). It is legal if the named branch > > + 'name' does not (yet) exist. In some legacy setups, it is > > + a symbolic link instead of a symref, but this has been > > + deprecated long ago. > > We fully support dealing with repositories with symlinked HEAD, > and will continue to do so; I do not think we ever talked about > deprecating it. Public "distribution point" repositories that > have been established long ago that do not have reason to switch > HEAD to point at different branch still have symlinked HEAD and > they should continue to work. > > What we _don't_ do these days is to set up new repositories with > symlinked HEAD, but that does not have anything to do with > deprecating symlinked HEAD. That's true, perhaps "obsoleted" is a better word. -- Petr "Pasky" Baudis Stuff: http://pasky.or.cz/ The meaning of Stonehenge in Traflamadorian, when viewed from above, is: "Replacement part being rushed with all possible speed." ```