Andy Whitcroft [off-list ref] writes:
Junio, I wonder if we should be changing the usage for this command
slightly. Currently, it mearly says <object> as the identifier for the
blob. Really this is <object-ish> as it supports symbolic naming in
addition to raw sha1's. I also feel it would be very helpful if
<commit-ish> and family were documented as a glossary section in main
git manpage.
Something like this:
<commit-ish>:: is an sha1 for a commit, or any symbolic name for a
commit (see SPECIFYING REVISIONS in git-rev-parse)
What do people think. I can do the munging about if its seems like a
sane plan.
When we really want an object of type <x>, we accept an object
that is not of type <x> if there is a natural and unique
dereferencing of that object to the type <x>. We use word
<x-ish> to describe such an object that dereferences to <x>.
For example, ls-tree is about listing tree contents (so we want
a tree), but we accept a commit because the natural and unique
dereferencing of a commit to a tree is to take its (toplevel)
tree. We also accept a tag pointing at a commit because we can
dereference it to the commit and then to its tree. Hence a tag
that points at either commit or a tree, and a commit are
tree-ish.
<object> is an object which can be <commit>, <tree>, <tag> or
<blob>. There is nothing -ish about it.
I was actually reviewing the documentation of git-rev-parse and
noticed that it talks about naming objects in the section called
"SPECIFYING REVISIONS". The title implies that it is about
committish (because we think of "revisions" as something that is
used in walking commit ancestry chains), but it actually talks
about naming objects of any type.
It is a good and comprehensive list when viewed as "list of ways
you can name an object", but both the title and the page the
list appears in put unfair emphasis of commits for that purpose,
and it is hard to realize that what you learned there applies to
naming any type of objects. It is even harder to guess the list
appears on that page, unless you are the one who is actively involved
in the git list, when you want to know which manual page to look
at in order to find out how you name an arbitrary object.
We could either
(1) retitle the list and move it to git.txt (Symbolic
Identifiers), and refer to it from pages that describe
commands that take object names;
(2) retitle the list and make it an includable snippet, similar
to the way Documentation/diff-format.txt is used from pages
that describe diff commands, and include it everywhere.
I am slightly in favor of the latter. Although it has a bloat
factor in the generated documentation, docs are not novels and
not meant to be read from cover to cover, and duplicating
relevant information on each page is more useful than refering
the reader to jump around in the documentation set.
Junio C Hamano wrote:
Andy Whitcroft [off-list ref] writes:
quoted
Junio, I wonder if we should be changing the usage for this command
slightly. Currently, it mearly says <object> as the identifier for the
blob. Really this is <object-ish> as it supports symbolic naming in
addition to raw sha1's. I also feel it would be very helpful if
<commit-ish> and family were documented as a glossary section in main
git manpage.
Something like this:
<commit-ish>:: is an sha1 for a commit, or any symbolic name for a
commit (see SPECIFYING REVISIONS in git-rev-parse)
What do people think. I can do the munging about if its seems like a
sane plan.
When we really want an object of type <x>, we accept an object
that is not of type <x> if there is a natural and unique
dereferencing of that object to the type <x>. We use word
<x-ish> to describe such an object that dereferences to <x>.
For example, ls-tree is about listing tree contents (so we want
a tree), but we accept a commit because the natural and unique
dereferencing of a commit to a tree is to take its (toplevel)
tree. We also accept a tag pointing at a commit because we can
dereference it to the commit and then to its tree. Hence a tag
that points at either commit or a tree, and a commit are
tree-ish.
<object> is an object which can be <commit>, <tree>, <tag> or
<blob>. There is nothing -ish about it.
I was actually reviewing the documentation of git-rev-parse and
noticed that it talks about naming objects in the section called
"SPECIFYING REVISIONS". The title implies that it is about
committish (because we think of "revisions" as something that is
used in walking commit ancestry chains), but it actually talks
about naming objects of any type.
It is a good and comprehensive list when viewed as "list of ways
you can name an object", but both the title and the page the
list appears in put unfair emphasis of commits for that purpose,
and it is hard to realize that what you learned there applies to
naming any type of objects. It is even harder to guess the list
appears on that page, unless you are the one who is actively involved
in the git list, when you want to know which manual page to look
at in order to find out how you name an arbitrary object.
We could either
(1) retitle the list and move it to git.txt (Symbolic
Identifiers), and refer to it from pages that describe
commands that take object names;
(2) retitle the list and make it an includable snippet, similar
to the way Documentation/diff-format.txt is used from pages
that describe diff commands, and include it everywhere.
I am slightly in favor of the latter. Although it has a bloat
factor in the generated documentation, docs are not novels and
not meant to be read from cover to cover, and duplicating
relevant information on each page is more useful than refering
the reader to jump around in the documentation set.
I'll take a stab at this ...
On 11/1/06, Junio C Hamano [off-list ref] wrote:
I was actually reviewing the documentation of git-rev-parse and
noticed that it talks about naming objects in the section called
"SPECIFYING REVISIONS". The title implies that it is about
committish (because we think of "revisions" as something that is
used in walking commit ancestry chains), but it actually talks
about naming objects of any type.
There's no way I would have known to look in git-rev-parse. My
git-rev-parse man page doesn't mention the colon syntax, but now I see
that part in git's gitweb; my man page must be too old. Either (1) or
(2) would have been enough for me to figure out that the colon syntax
would do what I wanted, but to grab the attention of the less
persistent user, it would be good to mention the particular case of
"git-cat-file <commit-ish>:<file>" in the git-cat-file man page.