[PATCH] Documentation: Define symref and update HEAD description

[PATCH] Documentation: Define symref and update HEAD description

[Petr Baudis]

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(-)

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::

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

[Junio C Hamano]

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.

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

[Petr Baudis]

On Sat, Nov 18, 2006 at 08:55:37PM CET, Junio C Hamano wrote:
> 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."