{"thread":{"id":"43318","subject":"[PATCH] Documentation: Define symref and update HEAD description","startedAt":"2006-11-18T19:44:08Z","lastAt":"2006-11-18T21:31:54Z","messageCount":3,"participants":["Petr Baudis","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"294341","messageId":"20061118194408.27106.65771.stgit@machine.or.cz","threadId":"43318","inReplyTo":null,"subject":"[PATCH] Documentation: Define symref and update HEAD description","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2006-11-18T19:44:08Z","receivedAt":"2006-11-18T19:44:08Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"HEAD was still described as a symlink instead of a symref.\n\nSigned-off-by: Petr Baudis \n---\n\n Documentation/glossary.txt | 7 +++++++\n Documentation/repository-layout.txt | 14 +++++++++-----\n 2 files changed, 16 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/glossary.txt b/Documentation/glossary.txt\nindex 7e560b0..894883d 100644\n--- a/Documentation/glossary.txt\n+++ b/Documentation/glossary.txt\n@@ -282,6 +282,13 @@ SCM::\n SHA1::\n \tSynonym for object name.\n \n+symref::\n+\tSymbolic reference: instead of containing the SHA1 id itself, it\n+\tis of the format 'ref: refs/some/thing' and when referenced, it\n+\trecursively dereferences to this reference. 'HEAD' is a prime\n+\texample of a symref. Symbolic references are manipulated with\n+\tthe gitlink:git-symbolic-ref[1] command.\n+\n topic branch::\n \tA regular git branch that is used by a developer to\n \tidentify a conceptual line of development. Since branches\ndiff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt\nindex 275d18b..fd9f406 100644\n--- a/Documentation/repository-layout.txt\n+++ b/Documentation/repository-layout.txt\n@@ -70,12 +70,16 @@ refs/tags/`name`::\n \tobject, or a tag object that points at a commit object).\n \n HEAD::\n-\tA symlink of the form `refs/heads/'name'` to point at\n-\tthe current branch, if exists. It does not mean much if\n-\tthe repository is not associated with any working tree\n+\tA symref (see glossary) to the `refs/heads/` namespace\n+\tdescribing the currently active branch. It does not mean\n+\tmuch if the repository is not associated with any working tree\n \t(i.e. a 'bare' repository), but a valid git repository\n-\t*must* have such a symlink here. It is legal if the\n-\tnamed branch 'name' does not (yet) exist.\n+\t*must* have the HEAD file; some porcelains may use it to\n+\tguess the designated \"default\" branch of the repository\n+\t(usually 'master'). It is legal if the named branch\n+\t'name' does not (yet) exist. In some legacy setups, it is\n+\ta symbolic link instead of a symref, but this has been\n+\tdeprecated long ago.\n \n branches::\n"},{"id":"298246","messageId":"7v64dccyx2.fsf@assigned-by-dhcp.cox.net","threadId":"43318","inReplyTo":"20061118194408.27106.65771.stgit@machine.or.cz","subject":"Re: [PATCH] Documentation: Define symref and update HEAD description","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-11-18T19:55:37Z","receivedAt":"2006-11-18T19:55:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Petr Baudis writes:\n\n> HEAD was still described as a symlink instead of a symref.\n>...\n> HEAD::\n> +\tA symref (see glossary) to the `refs/heads/` namespace\n> +\tdescribing the currently active branch. It does not mean\n> +\tmuch if the repository is not associated with any working tree\n> \t(i.e. a 'bare' repository), but a valid git repository\n> +\t*must* have the HEAD file; some porcelains may use it to\n> +\tguess the designated \"default\" branch of the repository\n> +\t(usually 'master'). It is legal if the named branch\n> +\t'name' does not (yet) exist. In some legacy setups, it is\n> +\ta symbolic link instead of a symref, but this has been\n> +\tdeprecated long ago.\n\nWe fully support dealing with repositories with symlinked HEAD,\nand will continue to do so; I do not think we ever talked about\ndeprecating it. Public \"distribution point\" repositories that\nhave been established long ago that do not have reason to switch\nHEAD to point at different branch still have symlinked HEAD and\nthey should continue to work.\n\nWhat we _don't_ do these days is to set up new repositories with\nsymlinked HEAD, but that does not have anything to do with\ndeprecating symlinked HEAD.\n\n\n"},{"id":"295616","messageId":"20061118213153.GR7201@pasky.or.cz","threadId":"43318","inReplyTo":"7v64dccyx2.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Documentation: Define symref and update HEAD description","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2006-11-18T21:31:54Z","receivedAt":"2006-11-18T21:31:54Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Sat, Nov 18, 2006 at 08:55:37PM CET, Junio C Hamano wrote:\n> Petr Baudis writes:\n> \n> > HEAD was still described as a symlink instead of a symref.\n> >...\n> > HEAD::\n> > +\tA symref (see glossary) to the `refs/heads/` namespace\n> > +\tdescribing the currently active branch. It does not mean\n> > +\tmuch if the repository is not associated with any working tree\n> > \t(i.e. a 'bare' repository), but a valid git repository\n> > +\t*must* have the HEAD file; some porcelains may use it to\n> > +\tguess the designated \"default\" branch of the repository\n> > +\t(usually 'master'). It is legal if the named branch\n> > +\t'name' does not (yet) exist. In some legacy setups, it is\n> > +\ta symbolic link instead of a symref, but this has been\n> > +\tdeprecated long ago.\n> \n> We fully support dealing with repositories with symlinked HEAD,\n> and will continue to do so; I do not think we ever talked about\n> deprecating it. Public \"distribution point\" repositories that\n> have been established long ago that do not have reason to switch\n> HEAD to point at different branch still have symlinked HEAD and\n> they should continue to work.\n> \n> What we _don't_ do these days is to set up new repositories with\n> symlinked HEAD, but that does not have anything to do with\n> deprecating symlinked HEAD.\n\nThat's true, perhaps \"obsoleted\" is a better word.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nThe meaning of Stonehenge in Traflamadorian, when viewed from above, is:\n\"Replacement part being rushed with all possible speed.\"\n"}]}