threads / patch / 43318

patchDocumentation: Define symref and update HEAD description

Subject: [PATCH] Documentation: Define symref and update HEAD description

## tl;dr

3 messages between Nov 18, 2006 and Nov 18, 2006. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Petr Baudis· Nov 18, 2006, 19:44 UTC · lore

HEAD was still described as a symlink instead of a symref.

Signed-off-by: Petr Baudis <pasky@suse.cz>
---

 Documentation/glossary.txt          |    7 +++++++
 Documentation/repository-layout.txt |   14 +++++++++-----
 2 files changed, 16 insertions(+), 5 deletions(-)

Show changes to 2 files +16 −5

Documentation/glossary.txt, Documentation/repository-layout.txt

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· Nov 18, 2006, 19:55 UTC · re: Petr Baudis · lore

Re: [PATCH] Documentation: Define symref and update HEAD description

Petr Baudis <pasky@suse.cz> writes:

Show 13 quoted lines

> 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· Nov 18, 2006, 21:31 UTC · re: Junio C Hamano · lore

Re: [PATCH] Documentation: Define symref and update HEAD description

On Sat, Nov 18, 2006 at 08:55:37PM CET, Junio C Hamano wrote:

Show 26 quoted lines

> Petr Baudis <pasky@suse.cz> 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."