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)
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 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
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 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 <> or a name that denotes a particular <>. 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 17:05, Junio C Hamano wrote: > Richard Hansen writes: > >> On 2013-06-19 13:14, Junio C Hamano wrote: >>> -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 <> pointing to an <> 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 writes: > On 2013-06-19 13:14, Junio C Hamano wrote: >> -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 <> pointing to an <> 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 13:14, Junio C Hamano wrote: > -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 writes: > Signed-off-by: Richard Hansen > --- > 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 <> of the stored > revision. > > +[[def_committish]]committish (also commit-ish):: > + A <> pointing to an <> that > + can be recursively dereferenced to a > + <>. > + The following are all committishes: > + a ref pointing to a commit object, > + a ref pointing to a <> 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. > + -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 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)
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 : 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)
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 <> of the stored
> revision.
>
> +[[def_committish]]committish (also commit-ish)::
> + A <> pointing to an <> that
> + can be recursively dereferenced to a
> + <>.
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 <> 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
<>.
+
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)
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 : 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
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 : 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:
> +[[def_committish]]committish (also commit-ish)::
Good.
> + A <> pointing to an <> that
> + can be recursively dereferenced to a
> + <>.
> + The following are all committishes:
> + a ref pointing to a commit object,
> + a ref pointing to a <> 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
[PATCH 2/4] glossary: define committish (a.k.a. commit-ish)
Signed-off-by: Richard Hansen --- 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 <> of the stored revision. +[[def_committish]]committish (also commit-ish):: + A <> pointing to an <> that + can be recursively dereferenced to a + <>. + The following are all committishes: + a ref pointing to a commit object, + a ref pointing to a <> 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
