Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Richard Hansen wrote: In the meantime, I'll rework the patch series to avoid using the word ref when defining committish and tree-ish. This is a good way forward. I'm curious about what you're planning on substituting it with though: the extended SHA-1 expression that Jonathan hinted at? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Richard Hansen wrote:
* Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs?
HEAD is a symbolic ref [*1*], FETCH_HEAD is not a ref [*2*], and
ORIG_HEAD is a ref.
ref
A binding of a name to an object or other ref (in which case it
is a symref). Refs are stored in the repository.
What is binding of a name? It's a file that contains exactly one
line: a 40-character SHA-1 hex. End of story. Like I explained in
[*1*], I see no advantage in grouping symbolic refs with refs.
The ref namespace is hierarchical. Different subhierarchies
are used for different purposes (e.g. the refs/heads/ hierarchy
is used to represent local branches).
Good.
[Footnotes]
*1*: HEAD is the one and only symbolic ref, unless you create more by
hand using `git symbolic-ref`. Unfortunately, no other symbolic ref
can ever be on the same footing as HEAD: the sources hard-code HEAD
in a large number of places, and reworking it to truly support
symbolic refs is probably not worth the pain at all. If you want to
convince yourself that this is true, run `git symbolic-ref H HEAD` and
then try to resolve H@{u}: HEAD@{u} resolves fine, doesn't it?
*2*: It's not an ordinary file like COMMIT_EDITMSG either, in that
rev-parse can operate on it. It is not a ref because it contains
references to several objects; cat it and see for yourself.
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Hi, Richard Hansen wrote: --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -82,6 +82,17 @@ to point at the new commit. to the top def_directory,directory of the stored revision. +[[def_committish]]committish (also commit-ish):: + A def_ref,ref pointing to an def_object,object that + can be recursively dereferenced to a + def_commit_object,commit object. Usually I would expect that the string 4d1c565 is not a ref, but the glossary contains a different definition (A 40-byte hex representation of a SHA-1 or ...). I guess we need a shorter name for extended SHA-1 syntax (as described in gitrevisions(7)) that is a little less confusing. Perhaps we can sidestep the issue by saying A parameter pointing to an def_object,object that can be recursively dereferenced to ... since the most common use of commitish is in describing a command's syntax. I'm tempted to go even further and just call that a commit parameter, explaining the more pedantic synonym here --- something like [[def_commitish]]commitish (also commit-ish):: A commandline parameter to a command that requires a def_commit,commit. + The following are all commitishes: an expression (see linkgit:gitrevisions[7]) directly representing a commit object, an expression naming a tag that points to a commit object, a tag that points to a tag that points to a commit, etc. Thanks, Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
On 2013-06-19 01:56, Ramkumar Ramachandra wrote:
From gitglossary(7):
ref
A 40-byte hex representation of a SHA-1 or a name that denotes a
particular object. They may be stored in a file under $GIT_DIR/refs/
directory, or in the $GIT_DIR/packed-refs file.
Do master~3 and :/foomery qualify as refs?
Yes; they are names that denote a particular object.
Look at the other forms in gitrevisions(7); master:quuxery,
master^{tree} are notable exceptions.
gitrevisions(7) says that master:quuxery is a ref pointing to a blob or
tree, so it is not a committish. However, if quuxery is a submodule, I
would expect master:quuxery to point to a commit object and thus be a
committish. So perhaps the rev:path description in gitrevisions(7)
should be updated to accommodate submodules.
When quuxery is a submodule, master:quuxery refers to a commit object
that does not exist in the parent repository. I don't know what we
gain by documenting a comittish you can't even `show`.
Fair point.
-Richard
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
On 2013-06-19 11:31, Richard Hansen wrote: On 2013-06-19 01:56, Ramkumar Ramachandra wrote: From gitglossary(7): ref A 40-byte hex representation of a SHA-1 or a name that denotes a particular object. They may be stored in a file under $GIT_DIR/refs/ directory, or in the $GIT_DIR/packed-refs file. Do master~3 and :/foomery qualify as refs? Yes; they are names that denote a particular object. Hmm... Maybe not. There is no definition of name in gitglossary(7), but there is object name, and that says: object name The unique identifier of an object. The hash of the object's contents using the Secure Hash Algorithm 1 and usually represented by the 40 character hexadecimal encoding of the hash of the object. That definition excludes master~3 and :/foomery. So perhaps we need a clearer definition of ref, or add a separate definition of name that is distinct from object name, or change the definition of object name to be more general (and perhaps define object ID to take the current definition of object name?). In sha1_name.c, master~3 and :/foomery are considered to be names. I think it'd be a good idea if gitglossary(7) matched the code, because that's the vocabulary Git developers and power users will use. Unfortunately, in my mind name has a connotation that doesn't quite match what sha1_name.c considers to be a name (I think of name as an arbitrary, more-or-less semanticless label attached to something for the purpose of convenient identification; the stuff in gitrevisions(7) are more like operators on a name). Maybe object specifier (objspec for short) could be used to refer to all the ways one could specify an object? Similarly, commit specifier/commitspec, tree specifier/treespec, etc. A treeish would then be defined as a treespec or something that can be dereferenced to a treespec. BTW, I'm not a huge fan of the current definition of ref in gitglossary(7) because to me a ref is ONLY something in .git/refs (or HEAD, FETCH_HEAD, etc.) -- NOT a SHA1. But I used ref in the definition of committish because that's how the definition of tree-ish was worded. It's also unfortunate that gitrevisions(7) isn't just about specifying revisions -- it's about specifying any object. Anyway, although my patches aren't perfect, I think they improve the current situation. If there are no objections I would like to see them committed. Thanks, Richard -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Richard Hansen rhan...@bbn.com writes: Signed-off-by: Richard Hansen rhan...@bbn.com --- Documentation/glossary-content.txt | 11 +++ 1 file changed, 11 insertions(+) diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 01365d9..a3cc003 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -82,6 +82,17 @@ to point at the new commit. to the top def_directory,directory of the stored revision. +[[def_committish]]committish (also commit-ish):: + A def_ref,ref pointing to an def_object,object that + can be recursively dereferenced to a + def_commit_object,commit object. + The following are all committishes: + a ref pointing to a commit object, + a ref pointing to a def_tag_object,tag object that points + to a commit object, + a ref pointing to a tag object that points to a tag object + that points to a commit object, etc. + object-type-ish does not have anything to do with a ref. Even when an object is dangling in your object store without being reachable from any of your refs, it keeps its own ish-ness. ish-ness is a property of the object itself. * A commit object has a single top-level tree, and when a command wants a tree object, you can often pass it a commit (historically some commands were more strict and refused to work on a commit when they wanted a tree). In other words, a commit can be used in place for a tree. A commit object is a tree-ish. * A tag object, when it points (recursively) at a commit object, can often be used in place for a commit object. Such a tag object is a commit-ish. * A tag object, when it points (recursively) at a tree object, can often be used in place for a tree object. Such a tag object is a tree-ish. Note that such a tag object cannot be a commit-ish. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
On 2013-06-19 13:14, Junio C Hamano wrote: object-type-ish does not have anything to do with a ref. Even when an object is dangling in your object store without being reachable from any of your refs, it keeps its own ish-ness. Ah, so your personal definition of ref matches my personal definition of ref, and this definition doesn't match gitglossary(7). :) ish-ness is a property of the object itself. * A commit object has a single top-level tree, and when a command wants a tree object, you can often pass it a commit (historically some commands were more strict and refused to work on a commit when they wanted a tree). In other words, a commit can be used in place for a tree. A commit object is a tree-ish. * A tag object, when it points (recursively) at a commit object, can often be used in place for a commit object. Such a tag object is a commit-ish. * A tag object, when it points (recursively) at a tree object, can often be used in place for a tree object. Such a tag object is a tree-ish. Note that such a tag object cannot be a commit-ish. I agree with all of this; the issue is the definition of ref in gitglossary(7). That definition should be fixed. In the meantime, I'll rework the patch series to avoid using the word ref when defining committish and tree-ish. -Richard -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Richard Hansen rhan...@bbn.com writes: On 2013-06-19 13:14, Junio C Hamano wrote: object-type-ish does not have anything to do with a ref. Even when an object is dangling in your object store without being reachable from any of your refs, it keeps its own ish-ness. Ah, so your personal definition of ref matches my personal definition of ref, and this definition doesn't match gitglossary(7). :) Huh? The only thing I I said was that *-ish does not have anything to do with a ref. I didn't say anything about definition of ref. You are the one who brought ref into description of *-ish, with this: +[[def_committish]]committish (also commit-ish):: + A def_ref,ref pointing to an def_object,object that + can be recursively dereferenced to a All I am saying is that an object does not have to be pointed by any ref to be any-ish. ish-ness is an attribute of an object, not an ref. You do not say refs/heads/master (which is a ref) is a commit-ish or a tree-ish. The object pointed at by that ref is always a commit and is a commit-ish and a tree-ish. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
On 2013-06-19 17:05, Junio C Hamano wrote: Richard Hansen rhan...@bbn.com writes: On 2013-06-19 13:14, Junio C Hamano wrote: object-type-ish does not have anything to do with a ref. Even when an object is dangling in your object store without being reachable from any of your refs, it keeps its own ish-ness. Ah, so your personal definition of ref matches my personal definition of ref, and this definition doesn't match gitglossary(7). :) Huh? The only thing I I said was that *-ish does not have anything to do with a ref. I didn't say anything about definition of ref. The phrase when an object is dangling in your object store without being reachable from any of your refs implies something about your definition of a ref that is inconsistent with gitglossary(7). See below. You are the one who brought ref into description of *-ish, with this: +[[def_committish]]committish (also commit-ish):: +A def_ref,ref pointing to an def_object,object that +can be recursively dereferenced to a And I did that to be consistent with the definition of tree-ish, which currently says: tree-ish A ref pointing to either a commit object, a tree object, or a tag object pointing to a tag or commit or tree object. Notice the term ref in the above definition. This definition says that a tree-ish is a particular kind of ref -- NOT a property of an object as you claim. I'm not saying you're wrong -- I actually agree with you completely -- I'm just saying that your definition of ref doesn't match the definition of ref in gitglossary(7). The current definition of ref says: ref A 40-byte hex representation of a SHA-1 or a name that denotes a particular object. They may be stored in a file under $GIT_DIR/refs/ directory, or in the $GIT_DIR/packed-refs file. Depending on how one interprets name (which is not defined in gitglossary(7)) in the above definition of ref, claiming that master:README is a ref is consistent with gitglossary(7). It is NOT, however, consistent with what you -- or anyone else I know -- think of as a ref. All I am saying is that an object does not have to be pointed by any ref to be any-ish. ish-ness is an attribute of an object, not an ref. You do not say refs/heads/master (which is a ref) is a commit-ish or a tree-ish. The object pointed at by that ref is always a commit and is a commit-ish and a tree-ish. I understand and agree completely and always have. Here's what I'm trying to say: * Given the current definition of ref in gitglossary(7), claiming that a foo-ish is a ref is not entirely incorrect. * If the definition of ref is altered to match the general understanding of a ref, then claiming that a foo-ish is a ref is wrong. Very wrong. I was trying to be minimal and consistent with my changes, but unfortunately it seems like more changes are necessary. When I next have time, I'll send some revised patches to include the following changes: * replace the current definition of ref with something that matches general understanding * eliminate the use of ref in the definitions of tag object, tree object, and tree-ish * create a term that means a thing understood by rev-parse that uniquely identifies an object (perhaps object specifier?) that can be used in gitglossary(7) and elsewhere -Richard -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Richard Hansen rhan...@bbn.com writes: Here's what I'm trying to say: * Given the current definition of ref in gitglossary(7), claiming that a foo-ish is a ref is not entirely incorrect. Ahh. If you had quoted this a few exchanges ago: [[def_ref]]ref:: A 40-byte hex representation of a def_SHA1,SHA-1 or a name that denotes a particular def_object,object. They may be stored in a file under `$GIT_DIR/refs/` directory, or in the `$GIT_DIR/packed-refs` file. I would have immediately understood what you were trying to say. Sorry about a wasted back-and-forth. The above is an utterly confused explanation. It explains object names and mentions as a sidenote that object names _can_ be held in refs. It does not say what a ref is, in other words. Before 'packed-refs' was introduced, the right definition would have been A file under `$GIT_DIR/refs/` directory that holds an object name. And packed-refs is a way to coalesce such files into a single file to make it easier/faster to access. In today's world (after packed-refs was introduced), probably A name that begins with refs/ (e.g. refs/heads/master) that can point at an object name. The namespace of refs is hierarchical and different subhierarchy is used for different purposes (e.g. the refs/heads/ hierarchy is used to represent local branches). is an appropriate rewrite of the above. If we also want to explain the implementation details of refs, then additionally at the end of the first paragraph, add: ... at an object name, by storing its 40-byte hex representation. They are implemented as either a file in $GIT_DIR/refs/ directory (called loose refs) or an entry in $GIT_DIR/packed-refs file (called packed refs); when a loose ref exists, a packed ref of the same name is ignored. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
On 2013-06-19 18:36, Junio C Hamano wrote: Ahh. If you had quoted [...] a few exchanges ago I would have immediately understood what you were trying to say. Sorry about that, my bad. In today's world (after packed-refs was introduced), probably A name that begins with refs/ (e.g. refs/heads/master) that can point at an object name. The namespace of refs is hierarchical and different subhierarchy is used for different purposes (e.g. the refs/heads/ hierarchy is used to represent local branches). is an appropriate rewrite of the above. Some thoughts about the above definition: * Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs? * That definition excludes symrefs. * It may be worthwhile to mention that refs are part of the repository. * Is a ref a name? Or is it the binding of a name to an object/ref? How about: ref A binding of a name to an object or other ref (in which case it is a symref). Refs are stored in the repository. The ref namespace is hierarchical. Different subhierarchies are used for different purposes (e.g. the refs/heads/ hierarchy is used to represent local branches). If we also want to explain the implementation details of refs, then additionally at the end of the first paragraph, add: ... at an object name, by storing its 40-byte hex representation. They are implemented as either a file in $GIT_DIR/refs/ directory (called loose refs) or an entry in $GIT_DIR/packed-refs file (called packed refs); when a loose ref exists, a packed ref of the same name is ignored. It would be good to document this somewhere, but I'm not sure the glossary is the right place for it. Maybe gitrepository-layout(5)? -Richard -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Richard Hansen rhan...@bbn.com writes: On 2013-06-19 18:36, Junio C Hamano wrote: Ahh. If you had quoted [...] a few exchanges ago I would have immediately understood what you were trying to say. Sorry about that, my bad. In today's world (after packed-refs was introduced), probably A name that begins with refs/ (e.g. refs/heads/master) that can point at an object name. The namespace of refs is hierarchical and different subhierarchy is used for different purposes (e.g. the refs/heads/ hierarchy is used to represent local branches). is an appropriate rewrite of the above. Some thoughts about the above definition: * Aren't HEAD, FETCH_HEAD, ORIG_HEAD also refs? That is a shade of gray. refs are names we use as the starting point to construct extended SHA-1 expressions to refer to objects, and in that sense they are. It would be complete to mention these as special cases. * That definition excludes symrefs. True. ... that can directly point at an object, or point at another ref (the latter is called a symbolic ref). * It may be worthwhile to mention that refs are part of the repository. * Is a ref a name? Or is it the binding of a name to an object/ref? I am not particularly interested in pedantry, but I think in the way we used the word ref, it is a name. refs/heads/master is the full name of the ref and it can be abbreviated to 'master' when not ambiguous. And there is a mechanism to read what the the ref has to learn the name of the object (*not* object/ref) it refers to (the name of that mechanism being ref resolution). To a layperson, a ref is one of the ways you can name an object with. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Signed-off-by: Richard Hansen rhan...@bbn.com --- Documentation/glossary-content.txt | 11 +++ 1 file changed, 11 insertions(+) diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index 01365d9..a3cc003 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -82,6 +82,17 @@ to point at the new commit. to the top def_directory,directory of the stored revision. +[[def_committish]]committish (also commit-ish):: + A def_ref,ref pointing to an def_object,object that + can be recursively dereferenced to a + def_commit_object,commit object. + The following are all committishes: + a ref pointing to a commit object, + a ref pointing to a def_tag_object,tag object that points + to a commit object, + a ref pointing to a tag object that points to a tag object + that points to a commit object, etc. + [[def_core_git]]core Git:: Fundamental data structures and utilities of Git. Exposes only limited source code management tools. -- 1.8.3.1 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Richard Hansen wrote:
+[[def_committish]]committish (also commit-ish)::
Good.
+ A def_ref,ref pointing to an def_object,object that
+ can be recursively dereferenced to a
+ def_commit_object,commit object.
+ The following are all committishes:
+ a ref pointing to a commit object,
+ a ref pointing to a def_tag_object,tag object that points
+ to a commit object,
+ a ref pointing to a tag object that points to a tag object
+ that points to a commit object, etc.
Is master~3 a committish? What about :/foomery? Look at the other
forms in gitrevisions(7); master:quuxery, master^{tree} are notable
exceptions.
Thanks.
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
On 2013-06-19 00:19, Ramkumar Ramachandra wrote:
Is master~3 a committish? What about :/foomery?
Yes; as documented, both of those are refs that point to a commit.
Look at the other forms in gitrevisions(7); master:quuxery,
master^{tree} are notable exceptions.
gitrevisions(7) says that master:quuxery is a ref pointing to a blob or
tree, so it is not a committish. However, if quuxery is a submodule, I
would expect master:quuxery to point to a commit object and thus be a
committish. So perhaps the rev:path description in gitrevisions(7)
should be updated to accommodate submodules.
master^{tree} is guaranteed to be a tree (if such a tree exists), so it
is not a committish.
-Richard
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Richard Hansen wrote:
On 2013-06-19 00:19, Ramkumar Ramachandra wrote:
Is master~3 a committish? What about :/foomery?
Yes; as documented, both of those are refs that point to a commit.
From gitglossary(7):
ref
A 40-byte hex representation of a SHA-1 or a name that denotes a
particular object. They may be stored in a file under $GIT_DIR/refs/
directory, or in the $GIT_DIR/packed-refs file.
Do master~3 and :/foomery qualify as refs?
Look at the other forms in gitrevisions(7); master:quuxery,
master^{tree} are notable exceptions.
gitrevisions(7) says that master:quuxery is a ref pointing to a blob or
tree, so it is not a committish. However, if quuxery is a submodule, I
would expect master:quuxery to point to a commit object and thus be a
committish. So perhaps the rev:path description in gitrevisions(7)
should be updated to accommodate submodules.
When quuxery is a submodule, master:quuxery refers to a commit object
that does not exist in the parent repository. I don't know what we
gain by documenting a comittish you can't even `show`.
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
