{"thread":{"id":"34212","subject":"[PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","startedAt":"2013-06-19T02:09:36Z","lastAt":"2013-06-20T10:55:31Z","messageCount":24,"participants":["Richard Hansen","Ramkumar Ramachandra","Jonathan Nieder","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"221313","messageId":"1371607780-2966-1-git-send-email-rhansen@bbn.com","threadId":"34212","inReplyTo":null,"subject":"[PATCH 0/4] documentation cleanups for <rev>^{<type>}","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T02:09:36Z","receivedAt":"2013-06-19T02:09:36Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"The documentation for the <rev>^{<type>} syntax (e.g.,\nv1.8.3.1^{tree}) needed some fixing, and while I was at it I thought\nI'd be pedantic about tree-ish.  Oh, and let's welcome \"committish\" to\nthe party!\n\n-Richard\n\n\nRichard Hansen (4):\n  glossary: add 'treeish' as a synonym for 'tree-ish'\n  glossary: define committish (a.k.a. commit-ish)\n  glossary: more precise definition of tree-ish (a.k.a. treeish)\n  revisions.txt: fix and clarify <rev>^{<type>}\n\n Documentation/glossary-content.txt | 29 +++++++++++++++++++++++++----\n Documentation/revisions.txt        | 12 ++++++++----\n 2 files changed, 33 insertions(+), 8 deletions(-)\n\n-- \n1.8.3.1\n"},{"id":"221315","messageId":"1371607780-2966-2-git-send-email-rhansen@bbn.com","threadId":"34212","inReplyTo":"1371607780-2966-1-git-send-email-rhansen@bbn.com","subject":"[PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T02:09:37Z","receivedAt":"2013-06-19T02:09:37Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"The documentation contains a mix of the two spellings, and including\nboth makes it possible for users to search the glossary with their\nspelling of choice.\n\nSigned-off-by: Richard Hansen <rhansen@bbn.com>\n---\n Documentation/glossary-content.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex db2a74d..01365d9 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -486,7 +486,7 @@ should not be combined with other pathspec.\n \twith refs to the associated blob and/or tree objects. A\n \t<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.\n \n-[[def_tree-ish]]tree-ish::\n+[[def_tree-ish]]tree-ish (also treeish)::\n \tA <<def_ref,ref>> pointing to either a <<def_commit_object,commit\n \tobject>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag\n \tobject>> pointing to a tag or commit or tree object.\n-- \n1.8.3.1\n"},{"id":"221312","messageId":"1371607780-2966-3-git-send-email-rhansen@bbn.com","threadId":"34212","inReplyTo":"1371607780-2966-1-git-send-email-rhansen@bbn.com","subject":"[PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T02:09:38Z","receivedAt":"2013-06-19T02:09:38Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"Signed-off-by: Richard Hansen <rhansen@bbn.com>\n---\n Documentation/glossary-content.txt | 11 +++++++++++\n 1 file changed, 11 insertions(+)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 01365d9..a3cc003 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -82,6 +82,17 @@ to point at the new commit.\n \tto the top <<def_directory,directory>> of the stored\n \trevision.\n \n+[[def_committish]]committish (also commit-ish)::\n+\tA <<def_ref,ref>> pointing to an <<def_object,object>> that\n+\tcan be recursively dereferenced to a\n+\t<<def_commit_object,commit object>>.\n+\tThe following are all committishes:\n+\ta ref pointing to a commit object,\n+\ta ref pointing to a <<def_tag_object,tag object>> that points\n+\tto a commit object,\n+\ta ref pointing to a tag object that points to a tag object\n+\tthat points to a commit object, etc.\n+\n [[def_core_git]]core Git::\n \tFundamental data structures and utilities of Git. Exposes only limited\n \tsource code management tools.\n-- \n1.8.3.1\n"},{"id":"221316","messageId":"1371607780-2966-4-git-send-email-rhansen@bbn.com","threadId":"34212","inReplyTo":"1371607780-2966-1-git-send-email-rhansen@bbn.com","subject":"[PATCH 3/4] glossary: more precise definition of tree-ish (a.k.a. treeish)","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T02:09:39Z","receivedAt":"2013-06-19T02:09:39Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"Mention dereferencing, and that a commit dereferences to a tree, to\nsupport gitrevisions(7) and rev-parse's error messages.\n\nSigned-off-by: Richard Hansen <rhansen@bbn.com>\n---\n Documentation/glossary-content.txt | 16 +++++++++++++---\n 1 file changed, 13 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex a3cc003..9a50fe1 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -498,9 +498,19 @@ should not be combined with other pathspec.\n \t<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.\n \n [[def_tree-ish]]tree-ish (also treeish)::\n-\tA <<def_ref,ref>> pointing to either a <<def_commit_object,commit\n-\tobject>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag\n-\tobject>> pointing to a tag or commit or tree object.\n+\tA <<def_ref,ref>> pointing to an <<def_object,object>> that\n+\tcan be recursively dereferenced to a\n+\t<<def_tree_object,tree object>>.\n+\tDereferencing a <<def_commit_object,commit object>> yields the\n+\ttree object corresponding to the <<def_revision,revision>>'s\n+\ttop <<def_directory,directory>>.\n+\tThe following are all tree-ishes:\n+\ta <<def_committish,committish>>,\n+\ta ref pointing to a tree object,\n+\ta ref pointing to a <<def_tag_object,tag object>> that points\n+\tto a tree object,\n+\ta ref pointing to a tag object that points to a tag object\n+\tthat points to a tree object, etc.\n \n [[def_unmerged_index]]unmerged index::\n \tAn <<def_index,index>> which contains unmerged\n-- \n1.8.3.1\n"},{"id":"221317","messageId":"1371607780-2966-5-git-send-email-rhansen@bbn.com","threadId":"34212","inReplyTo":"1371607780-2966-1-git-send-email-rhansen@bbn.com","subject":"[PATCH 4/4] revisions.txt: fix and clarify <rev>^{<type>}","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T02:09:40Z","receivedAt":"2013-06-19T02:09:40Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"If possible, <rev> will be dereferenced even if it is not a tag type\n(e.g., commit dereferenced to a tree).\n\nSigned-off-by: Richard Hansen <rhansen@bbn.com>\n---\n Documentation/revisions.txt | 12 ++++++++----\n 1 file changed, 8 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\nindex 09896a3..bf563cf 100644\n--- a/Documentation/revisions.txt\n+++ b/Documentation/revisions.txt\n@@ -114,10 +114,14 @@ some output processing may assume ref names in UTF-8.\n \n '<rev>{caret}\\{<type>\\}', e.g. 'v0.99.8{caret}\\{commit\\}'::\n   A suffix '{caret}' followed by an object type name enclosed in\n-  brace pair means the object\n-  could be a tag, and dereference the tag recursively until an\n-  object of that type is found or the object cannot be\n-  dereferenced anymore (in which case, barf).  '<rev>{caret}0'\n+  brace pair means dereference the object at '<rev>' recursively until\n+  an object of type '<type>' is found or the object cannot be\n+  dereferenced anymore (in which case, barf).\n+  For example, if '<rev>' is a committish, '<rev>{caret}\\{commit\\}'\n+  specifies the corresponding commit object.\n+  Similarly, if '<rev>' is a tree-ish, '<rev>{caret}\\{tree\\}'\n+  specifies the corresponding tree object.\n+  '<rev>{caret}0'\n   is a short-hand for '<rev>{caret}\\{commit\\}'.\n +\n 'rev{caret}\\{object\\}' can be used to make sure 'rev' names an\n-- \n1.8.3.1\n"},{"id":"221324","messageId":"CALkWK0mo2SG+Eh1Qmy58Xo-taG_EGEj9RSx65EYhvs2CLK9dUA@mail.gmail.com","threadId":"34212","inReplyTo":"1371607780-2966-3-git-send-email-rhansen@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-19T04:19:37Z","receivedAt":"2013-06-19T04:19:37Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Richard Hansen wrote:\n> +[[def_committish]]committish (also commit-ish)::\n\nGood.\n\n> +       A <<def_ref,ref>> pointing to an <<def_object,object>> that\n> +       can be recursively dereferenced to a\n> +       <<def_commit_object,commit object>>.\n> +       The following are all committishes:\n> +       a ref pointing to a commit object,\n> +       a ref pointing to a <<def_tag_object,tag object>> that points\n> +       to a commit object,\n> +       a ref pointing to a tag object that points to a tag object\n> +       that points to a commit object, etc.\n\nIs master~3 a committish?  What about :/foomery?  Look at the other\nforms in gitrevisions(7); master:quuxery, master^{tree} are notable\nexceptions.\n\nThanks.\n"},{"id":"221325","messageId":"51C135BE.4030506@bbn.com","threadId":"34212","inReplyTo":"CALkWK0mo2SG+Eh1Qmy58Xo-taG_EGEj9RSx65EYhvs2CLK9dUA@mail.gmail.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T04:38:22Z","receivedAt":"2013-06-19T04:38:22Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"On 2013-06-19 00:19, Ramkumar Ramachandra wrote:\n> Is master~3 a committish?  What about :/foomery?\n\nYes; as documented, both of those are refs that point to a commit.\n\n> Look at the other forms in gitrevisions(7); master:quuxery,\n> master^{tree} are notable exceptions.\n\ngitrevisions(7) says that master:quuxery is a ref pointing to a blob or\ntree, so it is not a committish.  However, if quuxery is a submodule, I\nwould expect master:quuxery to point to a commit object and thus be a\ncommittish.  So perhaps the <rev>:<path> description in gitrevisions(7)\nshould be updated to accommodate submodules.\n\nmaster^{tree} is guaranteed to be a tree (if such a tree exists), so it\nis not a committish.\n\n-Richard\n"},{"id":"221334","messageId":"CALkWK0=-PT=QD5enFQhrDZN03xCAttZKtjtT8rE7n4QynT+Ndg@mail.gmail.com","threadId":"34212","inReplyTo":"51C135BE.4030506@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-19T05:56:45Z","receivedAt":"2013-06-19T05:56:45Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Richard Hansen wrote:\n> On 2013-06-19 00:19, Ramkumar Ramachandra wrote:\n>> Is master~3 a committish?  What about :/foomery?\n>\n> Yes; as documented, both of those are refs that point to a commit.\n\n>From gitglossary(7):\n\nref\n    A 40-byte hex representation of a SHA-1 or a name that denotes a\n    particular object. They may be stored in a file under $GIT_DIR/refs/\n    directory, or in the $GIT_DIR/packed-refs file.\n\nDo master~3 and :/foomery qualify as refs?\n\n>> Look at the other forms in gitrevisions(7); master:quuxery,\n>> master^{tree} are notable exceptions.\n>\n> gitrevisions(7) says that master:quuxery is a ref pointing to a blob or\n> tree, so it is not a committish.  However, if quuxery is a submodule, I\n> would expect master:quuxery to point to a commit object and thus be a\n> committish.  So perhaps the <rev>:<path> description in gitrevisions(7)\n> should be updated to accommodate submodules.\n\nWhen quuxery is a submodule, master:quuxery refers to a commit object\nthat does not exist in the parent repository.  I don't know what we\ngain by documenting a comittish you can't even `show`.\n"},{"id":"221336","messageId":"20130619061938.GA2968@elie.Belkin","threadId":"34212","inReplyTo":"1371607780-2966-3-git-send-email-rhansen@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-06-19T06:19:39Z","receivedAt":"2013-06-19T06:19:39Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nRichard Hansen wrote:\n\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -82,6 +82,17 @@ to point at the new commit.\n>  \tto the top <<def_directory,directory>> of the stored\n>  \trevision.\n>  \n> +[[def_committish]]committish (also commit-ish)::\n> +\tA <<def_ref,ref>> pointing to an <<def_object,object>> that\n> +\tcan be recursively dereferenced to a\n> +\t<<def_commit_object,commit object>>.\n\nUsually I would expect that the string \"4d1c565\" is not a ref, but the\nglossary contains a different definition (\"A 40-byte hex\nrepresentation of a SHA-1 or ...\").  I guess we need a shorter name\nfor \"extended SHA-1 syntax\" (as described in gitrevisions(7)) that is\na little less confusing.\n\nPerhaps we can sidestep the issue by saying\n\n\tA parameter pointing to an <<def_object,object>> that\n\tcan be recursively dereferenced to ...\n\nsince the most common use of \"commitish\" is in describing a command's\nsyntax.  I'm tempted to go even further and just call that a \"commit\nparameter\", explaining the more pedantic synonym here --- something\nlike\n\n\t[[def_commitish]]commitish (also commit-ish)::\n\t\tA commandline parameter to a command that requires a\n\t\t<<def_commit,commit>>.\n\t+\n\tThe following are all commitishes: an expression (see\n\tlinkgit:gitrevisions[7]) directly representing a commit object,\n\tan expression naming a tag that points to a commit object, a\n\ttag that points to a tag that points to a commit, etc.\n\nThanks,\nJonathan\n"},{"id":"221380","messageId":"51C1CEB4.60206@bbn.com","threadId":"34212","inReplyTo":"CALkWK0=-PT=QD5enFQhrDZN03xCAttZKtjtT8rE7n4QynT+Ndg@mail.gmail.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T15:31:00Z","receivedAt":"2013-06-19T15:31:00Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"On 2013-06-19 01:56, Ramkumar Ramachandra wrote:\n> From gitglossary(7):\n> \n> ref\n>     A 40-byte hex representation of a SHA-1 or a name that denotes a\n>     particular object. They may be stored in a file under $GIT_DIR/refs/\n>     directory, or in the $GIT_DIR/packed-refs file.\n> \n> Do master~3 and :/foomery qualify as refs?\n\nYes; they are names that denote a particular object.\n\n> \n>>> Look at the other forms in gitrevisions(7); master:quuxery,\n>>> master^{tree} are notable exceptions.\n>>\n>> gitrevisions(7) says that master:quuxery is a ref pointing to a blob or\n>> tree, so it is not a committish.  However, if quuxery is a submodule, I\n>> would expect master:quuxery to point to a commit object and thus be a\n>> committish.  So perhaps the <rev>:<path> description in gitrevisions(7)\n>> should be updated to accommodate submodules.\n> \n> When quuxery is a submodule, master:quuxery refers to a commit object\n> that does not exist in the parent repository.  I don't know what we\n> gain by documenting a comittish you can't even `show`.\n\nFair point.\n\n-Richard\n"},{"id":"221382","messageId":"51C1D7E3.9020305@bbn.com","threadId":"34212","inReplyTo":"51C1CEB4.60206@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T16:10:11Z","receivedAt":"2013-06-19T16:10:11Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"On 2013-06-19 11:31, Richard Hansen wrote:\n> On 2013-06-19 01:56, Ramkumar Ramachandra wrote:\n>> From gitglossary(7):\n>>\n>> ref\n>>     A 40-byte hex representation of a SHA-1 or a name that denotes a\n>>     particular object. They may be stored in a file under $GIT_DIR/refs/\n>>     directory, or in the $GIT_DIR/packed-refs file.\n>>\n>> Do master~3 and :/foomery qualify as refs?\n> \n> Yes; they are names that denote a particular object.\n\nHmm...  Maybe not.  There is no definition of \"name\" in gitglossary(7),\nbut there is \"object name\", and that says:\n\n    object name\n        The unique identifier of an object.  The hash of the object's\n        contents using the Secure Hash Algorithm 1 and usually\n        represented by the 40 character hexadecimal encoding of the\n        hash of the object.\n\nThat definition excludes master~3 and :/foomery.  So perhaps we need a\nclearer definition of \"ref\", or add a separate definition of \"name\" that\nis distinct from \"object name\", or change the definition of \"object\nname\" to be more general (and perhaps define \"object ID\" to take the\ncurrent definition of \"object name\"?).\n\nIn sha1_name.c, master~3 and :/foomery are considered to be \"names\".  I\nthink it'd be a good idea if gitglossary(7) matched the code, because\nthat's the vocabulary Git developers and power users will use.\nUnfortunately, in my mind \"name\" has a connotation that doesn't quite\nmatch what sha1_name.c considers to be a name (I think of \"name\" as an\narbitrary, more-or-less semanticless label attached to something for the\npurpose of convenient identification; the stuff in gitrevisions(7) are\nmore like operators on a name).\n\nMaybe \"object specifier\" (\"objspec\" for short) could be used to refer to\nall the ways one could specify an object?  Similarly, commit\nspecifier/commitspec, tree specifier/treespec, etc.  A treeish would\nthen be defined as a treespec or something that can be dereferenced to a\ntreespec.\n\n\nBTW, I'm not a huge fan of the current definition of \"ref\" in\ngitglossary(7) because to me a ref is ONLY something in .git/refs (or\nHEAD, FETCH_HEAD, etc.) -- NOT a SHA1.  But I used \"ref\" in the\ndefinition of \"committish\" because that's how the definition of\n\"tree-ish\" was worded.\n\nIt's also unfortunate that gitrevisions(7) isn't just about specifying\nrevisions -- it's about specifying any object.\n\n\nAnyway, although my patches aren't perfect, I think they improve the\ncurrent situation.  If there are no objections I would like to see them\ncommitted.\n\nThanks,\nRichard\n"},{"id":"221387","messageId":"7vli6610yg.fsf@alter.siamese.dyndns.org","threadId":"34212","inReplyTo":"1371607780-2966-2-git-send-email-rhansen@bbn.com","subject":"Re: [PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-19T17:09:59Z","receivedAt":"2013-06-19T17:09:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Richard Hansen <rhansen@bbn.com> writes:\n\n> The documentation contains a mix of the two spellings, and including\n> both makes it possible for users to search the glossary with their\n> spelling of choice.\n\nIs it an option to instead find dashless form in our documentation\nand turn all of them into tree-ish form with a dash?  I personally\nfind it cleaner that way.\n\n>\n> Signed-off-by: Richard Hansen <rhansen@bbn.com>\n> ---\n>  Documentation/glossary-content.txt | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index db2a74d..01365d9 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -486,7 +486,7 @@ should not be combined with other pathspec.\n>  \twith refs to the associated blob and/or tree objects. A\n>  \t<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.\n>  \n> -[[def_tree-ish]]tree-ish::\n> +[[def_tree-ish]]tree-ish (also treeish)::\n>  \tA <<def_ref,ref>> pointing to either a <<def_commit_object,commit\n>  \tobject>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag\n>  \tobject>> pointing to a tag or commit or tree object.\n"},{"id":"221388","messageId":"7vhagu10ql.fsf@alter.siamese.dyndns.org","threadId":"34212","inReplyTo":"1371607780-2966-3-git-send-email-rhansen@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-19T17:14:42Z","receivedAt":"2013-06-19T17:14:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Richard Hansen <rhansen@bbn.com> writes:\n\n> Signed-off-by: Richard Hansen <rhansen@bbn.com>\n> ---\n>  Documentation/glossary-content.txt | 11 +++++++++++\n>  1 file changed, 11 insertions(+)\n>\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 01365d9..a3cc003 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -82,6 +82,17 @@ to point at the new commit.\n>  \tto the top <<def_directory,directory>> of the stored\n>  \trevision.\n>  \n> +[[def_committish]]committish (also commit-ish)::\n> +\tA <<def_ref,ref>> pointing to an <<def_object,object>> that\n> +\tcan be recursively dereferenced to a\n> +\t<<def_commit_object,commit object>>.\n> +\tThe following are all committishes:\n> +\ta ref pointing to a commit object,\n> +\ta ref pointing to a <<def_tag_object,tag object>> that points\n> +\tto a commit object,\n> +\ta ref pointing to a tag object that points to a tag object\n> +\tthat points to a commit object, etc.\n> +\n\n<object-type>-ish does not have anything to do with a ref.  Even\nwhen an object is dangling in your object store without being\nreachable from any of your refs, it keeps its own \"ish\"-ness.\n\n\"ish\"-ness is a property of the object itself.\n\n * A commit object has a single top-level tree, and when a command\n   wants a tree object, you can often pass it a commit (historically\n   some commands were more strict and refused to work on a commit\n   when they wanted a tree).  In other words, a commit can be used\n   in place for a tree.  A commit object is a tree-ish.\n\n * A tag object, when it points (recursively) at a commit object,\n   can often be used in place for a commit object.  Such a tag\n   object is a commit-ish.\n\n * A tag object, when it points (recursively) at a tree object, can\n   often be used in place for a tree object.  Such a tag object is a\n   tree-ish.  Note that such a tag object cannot be a commit-ish.\n"},{"id":"221398","messageId":"51C20287.3060301@bbn.com","threadId":"34212","inReplyTo":"7vli6610yg.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T19:12:07Z","receivedAt":"2013-06-19T19:12:07Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"On 2013-06-19 13:09, Junio C Hamano wrote:\n> Richard Hansen <rhansen@bbn.com> writes:\n> \n>> The documentation contains a mix of the two spellings, and including\n>> both makes it possible for users to search the glossary with their\n>> spelling of choice.\n> \n> Is it an option to instead find dashless form in our documentation\n> and turn all of them into tree-ish form with a dash?  I personally\n> find it cleaner that way.\n\nI can s/treeish/tree-ish/g, although I'd still like to keep 'treeish' in\nthe glossary so that people can find it when they search for the\nmisspelled version.\n\nPerhaps something like:\n\n-[[def_tree-ish]]tree-ish::\n+[[def_tree-ish]]tree-ish (sometimes misspelled treeish)::\n\nwould be satisfactory?\n\nWhile we're on the topic, do you have a preference for commit-ish vs.\ncommittish?  Grepping the code shows comittish to be the overwhelming\nfavorite, but it's inconsistent with tree-ish.\n\n-Richard\n\n\n> \n>>\n>> Signed-off-by: Richard Hansen <rhansen@bbn.com>\n>> ---\n>>  Documentation/glossary-content.txt | 2 +-\n>>  1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>> index db2a74d..01365d9 100644\n>> --- a/Documentation/glossary-content.txt\n>> +++ b/Documentation/glossary-content.txt\n>> @@ -486,7 +486,7 @@ should not be combined with other pathspec.\n>>  \twith refs to the associated blob and/or tree objects. A\n>>  \t<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.\n>>  \n>> -[[def_tree-ish]]tree-ish::\n>> +[[def_tree-ish]]tree-ish (also treeish)::\n>>  \tA <<def_ref,ref>> pointing to either a <<def_commit_object,commit\n>>  \tobject>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag\n>>  \tobject>> pointing to a tag or commit or tree object.\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at  http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"221399","messageId":"51C203A1.4000404@bbn.com","threadId":"34212","inReplyTo":"7vhagu10ql.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T19:16:49Z","receivedAt":"2013-06-19T19:16:49Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"On 2013-06-19 13:14, Junio C Hamano wrote:\n> <object-type>-ish does not have anything to do with a ref.  Even\n> when an object is dangling in your object store without being\n> reachable from any of your refs, it keeps its own \"ish\"-ness.\n\nAh, so your personal definition of \"ref\" matches my personal definition\nof \"ref\", and this definition doesn't match gitglossary(7).  :)\n\n> \n> \"ish\"-ness is a property of the object itself.\n> \n>  * A commit object has a single top-level tree, and when a command\n>    wants a tree object, you can often pass it a commit (historically\n>    some commands were more strict and refused to work on a commit\n>    when they wanted a tree).  In other words, a commit can be used\n>    in place for a tree.  A commit object is a tree-ish.\n> \n>  * A tag object, when it points (recursively) at a commit object,\n>    can often be used in place for a commit object.  Such a tag\n>    object is a commit-ish.\n> \n>  * A tag object, when it points (recursively) at a tree object, can\n>    often be used in place for a tree object.  Such a tag object is a\n>    tree-ish.  Note that such a tag object cannot be a commit-ish.\n\nI agree with all of this; the issue is the definition of \"ref\" in\ngitglossary(7).  That definition should be fixed.  In the meantime, I'll\nrework the patch series to avoid using the word \"ref\" when defining\ncommittish and tree-ish.\n\n-Richard\n"},{"id":"221407","messageId":"51C2162B.2070103@bbn.com","threadId":"34212","inReplyTo":"7vli6610yg.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T20:35:55Z","receivedAt":"2013-06-19T20:35:55Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"On 2013-06-19 13:09, Junio C Hamano wrote:\n> Richard Hansen <rhansen@bbn.com> writes:\n> \n>> The documentation contains a mix of the two spellings, and including\n>> both makes it possible for users to search the glossary with their\n>> spelling of choice.\n> \n> Is it an option to instead find dashless form in our documentation\n> and turn all of them into tree-ish form with a dash?  I personally\n> find it cleaner that way.\n\nMy preference is treeish and committish (instead of tree-ish and\ncommit-ish) because those are the spellings used in the source code.\n\n-Richard\n\n> \n>>\n>> Signed-off-by: Richard Hansen <rhansen@bbn.com>\n>> ---\n>>  Documentation/glossary-content.txt | 2 +-\n>>  1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>> index db2a74d..01365d9 100644\n>> --- a/Documentation/glossary-content.txt\n>> +++ b/Documentation/glossary-content.txt\n>> @@ -486,7 +486,7 @@ should not be combined with other pathspec.\n>>  \twith refs to the associated blob and/or tree objects. A\n>>  \t<<def_tree,tree>> is equivalent to a <<def_directory,directory>>.\n>>  \n>> -[[def_tree-ish]]tree-ish::\n>> +[[def_tree-ish]]tree-ish (also treeish)::\n>>  \tA <<def_ref,ref>> pointing to either a <<def_commit_object,commit\n>>  \tobject>>, a <<def_tree_object,tree object>>, or a <<def_tag_object,tag\n>>  \tobject>> pointing to a tag or commit or tree object.\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at  http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"221409","messageId":"7vtxktyfo1.fsf@alter.siamese.dyndns.org","threadId":"34212","inReplyTo":"51C203A1.4000404@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-19T21:05:50Z","receivedAt":"2013-06-19T21:05:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Richard Hansen <rhansen@bbn.com> writes:\n\n> On 2013-06-19 13:14, Junio C Hamano wrote:\n>> <object-type>-ish does not have anything to do with a ref.  Even\n>> when an object is dangling in your object store without being\n>> reachable from any of your refs, it keeps its own \"ish\"-ness.\n>\n> Ah, so your personal definition of \"ref\" matches my personal definition\n> of \"ref\", and this definition doesn't match gitglossary(7).  :)\n\nHuh?  The only thing I I said was that \"*-ish\" does not have\nanything to do with a ref.  I didn't say anything about definition\nof \"ref\".\n\nYou are the one who brought \"ref\" into description of *-ish, with\nthis:\n\n> +[[def_committish]]committish (also commit-ish)::\n> +\tA <<def_ref,ref>> pointing to an <<def_object,object>> that\n> +\tcan be recursively dereferenced to a\n\nAll I am saying is that an object does not have to be pointed by any\nref to be any-ish.  ish-ness is an attribute of an object, not an\nref.  You do not say refs/heads/master (which is a ref) is a\ncommit-ish or a tree-ish.  The object pointed at by that ref is\nalways a commit and is a commit-ish and a tree-ish.\n"},{"id":"221411","messageId":"7vli65ydrr.fsf@alter.siamese.dyndns.org","threadId":"34212","inReplyTo":"51C20287.3060301@bbn.com","subject":"Re: [PATCH 1/4] glossary: add 'treeish' as a synonym for 'tree-ish'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-19T21:46:48Z","receivedAt":"2013-06-19T21:46:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Richard Hansen <rhansen@bbn.com> writes:\n\n> Perhaps something like:\n>\n> -[[def_tree-ish]]tree-ish::\n> +[[def_tree-ish]]tree-ish (sometimes misspelled treeish)::\n>\n> would be satisfactory?\n\nIf it is a misspelling, I do not think we need to list both.  An\nentry \"tree-ish\" can be found if you were looking for treeish.\n\nIf it is not, then \"sometimes misspelled\" should perhaps is better\n\"aka\".\n\nI do not personally have a very strong preference between the dashed\nand dashless forms, but if I really have to pick one over the other,\nI would probably go with tree-ish, commit-ish, as these are not real\nwords.  I do have mild preference of not listing both to keep things\nshorter and cleaner.\n"},{"id":"221415","messageId":"51C22F77.8050004@bbn.com","threadId":"34212","inReplyTo":"7vtxktyfo1.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T22:23:51Z","receivedAt":"2013-06-19T22:23:51Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"On 2013-06-19 17:05, Junio C Hamano wrote:\n> Richard Hansen <rhansen@bbn.com> writes:\n> \n>> On 2013-06-19 13:14, Junio C Hamano wrote:\n>>> <object-type>-ish does not have anything to do with a ref.  Even\n>>> when an object is dangling in your object store without being\n>>> reachable from any of your refs, it keeps its own \"ish\"-ness.\n>>\n>> Ah, so your personal definition of \"ref\" matches my personal definition\n>> of \"ref\", and this definition doesn't match gitglossary(7).  :)\n> \n> Huh?  The only thing I I said was that \"*-ish\" does not have\n> anything to do with a ref.  I didn't say anything about definition\n> of \"ref\".\n\nThe phrase\n\n    when an object is dangling in your object store without being\n    reachable from any of your refs\n\nimplies something about your definition of a ref that is inconsistent\nwith gitglossary(7).  See below.\n\n> \n> You are the one who brought \"ref\" into description of *-ish, with\n> this:\n> \n>> +[[def_committish]]committish (also commit-ish)::\n>> +\tA <<def_ref,ref>> pointing to an <<def_object,object>> that\n>> +\tcan be recursively dereferenced to a\n\nAnd I did that to be consistent with the definition of tree-ish, which\ncurrently says:\n\n    tree-ish\n        A ref pointing to either a commit object, a tree object, or a\n        tag object pointing to a tag or commit or tree object.\n\nNotice the term \"ref\" in the above definition.  This definition says\nthat a tree-ish is a particular kind of ref -- NOT a property of an\nobject as you claim.  I'm not saying you're wrong -- I actually agree\nwith you completely -- I'm just saying that your definition of ref\ndoesn't match the definition of ref in gitglossary(7).\n\nThe current definition of ref says:\n\n    ref\n        A 40-byte hex representation of a SHA-1 or a name that denotes\n        a particular object.  They may be stored in a file under\n        $GIT_DIR/refs/ directory, or in the $GIT_DIR/packed-refs file.\n\nDepending on how one interprets \"name\" (which is not defined in\ngitglossary(7)) in the above definition of ref, claiming that\n\"master:README\" is a ref is consistent with gitglossary(7).  It is NOT,\nhowever, consistent with what you -- or anyone else I know -- think of\nas a ref.\n\n> \n> All I am saying is that an object does not have to be pointed by any\n> ref to be any-ish.  ish-ness is an attribute of an object, not an\n> ref.  You do not say refs/heads/master (which is a ref) is a\n> commit-ish or a tree-ish.  The object pointed at by that ref is\n> always a commit and is a commit-ish and a tree-ish.\n\nI understand and agree completely and always have.\n\nHere's what I'm trying to say:\n\n  * Given the current definition of \"ref\" in gitglossary(7), claiming\n    that a foo-ish is a ref is not entirely incorrect.\n  * If the definition of \"ref\" is altered to match the general\n    understanding of a \"ref\", then claiming that a foo-ish is a ref is\n    wrong.  Very wrong.\n\nI was trying to be minimal and consistent with my changes, but\nunfortunately it seems like more changes are necessary.  When I next\nhave time, I'll send some revised patches to include the following changes:\n\n  * replace the current definition of \"ref\" with something that matches\n    general understanding\n  * eliminate the use of \"ref\" in the definitions of tag object, tree\n    object, and tree-ish\n  * create a term that means \"a thing understood by rev-parse that\n    uniquely identifies an object\" (perhaps \"object specifier\"?) that\n    can be used in gitglossary(7) and elsewhere\n\n-Richard\n"},{"id":"221416","messageId":"7vwqppwwwj.fsf@alter.siamese.dyndns.org","threadId":"34212","inReplyTo":"51C22F77.8050004@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-19T22:36:28Z","receivedAt":"2013-06-19T22:36:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Richard Hansen <rhansen@bbn.com> writes:\n\n> Here's what I'm trying to say:\n>\n>   * Given the current definition of \"ref\" in gitglossary(7), claiming\n>     that a foo-ish is a ref is not entirely incorrect.\n\nAhh.  If you had quoted this a few exchanges ago:\n\n    [[def_ref]]ref::\n            A 40-byte hex representation of a <<def_SHA1,SHA-1>> or a name that\n            denotes a particular <<def_object,object>>. They may be stored in\n            a file under `$GIT_DIR/refs/` directory, or\n            in the `$GIT_DIR/packed-refs` file.\n\nI would have immediately understood what you were trying to say.\nSorry about a wasted back-and-forth.\n\nThe above is an utterly confused explanation.  It explains object\nnames and mentions as a sidenote that object names _can_ be held in\nrefs.\n\nIt does not say what a ref is, in other words.\n\nBefore 'packed-refs' was introduced, the right definition would have\nbeen\n\n\tA file under `$GIT_DIR/refs/` directory that holds an object\n\tname.\n\nAnd packed-refs is a way to coalesce such files into a single file\nto make it easier/faster to access.\n\nIn today's world (after packed-refs was introduced), probably\n\n\tA name that begins with refs/ (e.g. refs/heads/master) that\n\tcan point at an object name.\n\n        The namespace of refs is hierarchical and different\n        subhierarchy is used for different purposes (e.g. the\n        refs/heads/ hierarchy is used to represent local branches).\n\nis an appropriate rewrite of the above.\n\nIf we also want to explain the implementation details of refs, then\nadditionally at the end of the first paragraph, add:\n\n\t... at an object name, by storing its 40-byte hex\n\trepresentation.  They are implemented as either a file in\n\t$GIT_DIR/refs/ directory (called \"loose refs\") or an entry\n\tin $GIT_DIR/packed-refs file (called \"packed refs\"); when a\n\tloose ref exists, a packed ref of the same name is ignored.\n"},{"id":"221418","messageId":"51C2409F.1070801@bbn.com","threadId":"34212","inReplyTo":"7vwqppwwwj.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Richard Hansen","fromEmail":"rhansen@bbn.com","sentAt":"2013-06-19T23:37:03Z","receivedAt":"2013-06-19T23:37:03Z","isPatch":true,"sender":{"key":"rhansen@rhansen.org","avatar":null},"body":"On 2013-06-19 18:36, Junio C Hamano wrote:\n> Ahh.  If you had quoted [...] a few exchanges ago I would have\n> immediately understood what you were trying to say.\n\nSorry about that, my bad.\n\n> In today's world (after packed-refs was introduced), probably\n> \n> \tA name that begins with refs/ (e.g. refs/heads/master) that\n> \tcan point at an object name.\n> \n>         The namespace of refs is hierarchical and different\n>         subhierarchy is used for different purposes (e.g. the\n>         refs/heads/ hierarchy is used to represent local branches).\n> \n> is an appropriate rewrite of the above.\n\nSome thoughts about the above definition:\n  * Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs?\n  * That definition excludes symrefs.\n  * It may be worthwhile to mention that refs are part of the\n    repository.\n  * Is a ref a name?  Or is it the binding of a name to an object/ref?\n\nHow about:\n\n    ref\n        A binding of a name to an object or other ref (in which case it\n        is a symref).  Refs are stored in the repository.\n\n        The ref namespace is hierarchical.  Different subhierarchies\n        are used for different purposes (e.g. the refs/heads/ hierarchy\n        is used to represent local branches).\n\n> \n> If we also want to explain the implementation details of refs, then\n> additionally at the end of the first paragraph, add:\n> \n> \t... at an object name, by storing its 40-byte hex\n> \trepresentation.  They are implemented as either a file in\n> \t$GIT_DIR/refs/ directory (called \"loose refs\") or an entry\n> \tin $GIT_DIR/packed-refs file (called \"packed refs\"); when a\n> \tloose ref exists, a packed ref of the same name is ignored.\n\nIt would be good to document this somewhere, but I'm not sure the\nglossary is the right place for it.  Maybe gitrepository-layout(5)?\n\n-Richard\n"},{"id":"221421","messageId":"7vli65wjj2.fsf@alter.siamese.dyndns.org","threadId":"34212","inReplyTo":"51C2409F.1070801@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-06-20T03:25:21Z","receivedAt":"2013-06-20T03:25:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Richard Hansen <rhansen@bbn.com> writes:\n\n> On 2013-06-19 18:36, Junio C Hamano wrote:\n>> Ahh.  If you had quoted [...] a few exchanges ago I would have\n>> immediately understood what you were trying to say.\n>\n> Sorry about that, my bad.\n>\n>> In today's world (after packed-refs was introduced), probably\n>> \n>> \tA name that begins with refs/ (e.g. refs/heads/master) that\n>> \tcan point at an object name.\n>> \n>>         The namespace of refs is hierarchical and different\n>>         subhierarchy is used for different purposes (e.g. the\n>>         refs/heads/ hierarchy is used to represent local branches).\n>> \n>> is an appropriate rewrite of the above.\n>\n> Some thoughts about the above definition:\n>   * Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs?\n\nThat is a shade of gray.  \"refs\" are names we use as the starting\npoint to construct extended SHA-1 expressions to refer to objects,\nand in that sense they are.  It would be complete to mention these\nas special cases.\n\n>   * That definition excludes symrefs.\n\nTrue.  \"... that can directly point at an object, or point at\nanother ref (the latter is called a symbolic ref).\"\n\n>   * It may be worthwhile to mention that refs are part of the\n>     repository.\n>   * Is a ref a name?  Or is it the binding of a name to an object/ref?\n\nI am not particularly interested in pedantry, but I think in the way\nwe used the word \"ref\", it is a name.  \"refs/heads/master\" is the\nfull name of the ref and it can be abbreviated to 'master' when not\nambiguous.  And there is a mechanism to read what the the ref has to\nlearn the name of the object (*not* object/ref) it refers to (the\nname of that mechanism being \"ref resolution\").\n\nTo a layperson, a ref is one of the ways you can name an object\nwith.\n"},{"id":"221461","messageId":"CALkWK0mBYBeZ4cN203VP51RXW2=hwGGM=pXjLxuqXWu7R8M4yw@mail.gmail.com","threadId":"34212","inReplyTo":"51C203A1.4000404@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-20T10:37:34Z","receivedAt":"2013-06-20T10:37:34Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Richard Hansen wrote:\n> In the meantime, I'll\n> rework the patch series to avoid using the word \"ref\" when defining\n> committish and tree-ish.\n\nThis is a good way forward.  I'm curious about what you're planning on\nsubstituting it with though: the \"extended SHA-1 expression\" that\nJonathan hinted at?\n"},{"id":"221462","messageId":"CALkWK0nqOSmFaYhbW3anmBvgy2=DZs7qU0kz7=eEO5R99uLAqQ@mail.gmail.com","threadId":"34212","inReplyTo":"51C2409F.1070801@bbn.com","subject":"Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2013-06-20T10:55:31Z","receivedAt":"2013-06-20T10:55:31Z","isPatch":true,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Richard Hansen wrote:\n>   * Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs?\n\nHEAD is a symbolic ref [*1*], FETCH_HEAD is not a ref [*2*], and\nORIG_HEAD is a ref.\n\n>     ref\n>         A binding of a name to an object or other ref (in which case it\n>         is a symref).  Refs are stored in the repository.\n\nWhat is \"binding of a name\"?  It's a file that contains exactly one\nline: a 40-character SHA-1 hex.  End of story.  Like I explained in\n[*1*], I see no advantage in grouping symbolic refs with refs.\n\n>         The ref namespace is hierarchical.  Different subhierarchies\n>         are used for different purposes (e.g. the refs/heads/ hierarchy\n>         is used to represent local branches).\n\nGood.\n\n[Footnotes]\n\n*1*: HEAD is the one and only symbolic ref, unless you create more by\nhand using `git symbolic-ref`.  Unfortunately, no other symbolic ref\ncan ever be on the same footing as HEAD: the sources hard-code \"HEAD\"\nin a large number of places, and reworking it to truly support\nsymbolic refs is probably not worth the pain at all.  If you want to\nconvince yourself that this is true, run `git symbolic-ref H HEAD` and\nthen try to resolve H@{u}: HEAD@{u} resolves fine, doesn't it?\n\n*2*: It's not an \"ordinary file\" like COMMIT_EDITMSG either, in that\nrev-parse can operate on it.  It is not a ref because it contains\nreferences to several objects; cat it and see for yourself.\n"}]}