git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH/RFC 09/12] docs: use <commit> instead of <commit-ish>

From
Mark Lodato <lodatom@gmail.com>
Date
Mar 16, 2010, 01:12 UTC
Message-ID
<ca433831003151812l7cc2c1b4hc11c9748ec8ed570@mail.gmail.com>
In-Reply-To
<7vwrxf6fnc.fsf@alter.siamese.dyndns.org>
On Sat, Mar 13, 2010 at 6:05 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 17 quoted lines
> Mark Lodato <lodatom@gmail.com> writes:
>
>> There exist no commands that accept a <commit> but not a <commit-ish>,
>
> I have one worry about this and [07/12].  The droppage of -ish would make
> sense from the point of view of describing command line arguments,
> i.e. what you can give to the commands, but it would make it impossible
> for us to talk about places that _only_ tree not arbitrary tree-ish can
> appear.  For example, don't we ever talk about something like this?
>
>    A tree object is a sequence of records, each of which describes the
>    type of entry, object name, and the name of the entry in the tree.
>    When the type is "tree", the object name must name a tree, when the
>    type is "gitlink", the object name must name a commit, ...
>
> Other than that small worry, I think the series goes in the right
> direction.

Yes, it would probably be best to leave the -ish terms in the glossary (which I evidently did by mistake) and in the comments and documentation, but just not use them as an identifier in angle brackets. For example, a command accepting a <tree> would also accept commits or tags unless otherwise noted, but the term "tree object" would still only refer to an actual tree object, not a tree-ish. When it is unclear, one can use the -ish term, like I just did in that last sentence.

I'll wait a few days to see if there are any more comments, and then I'll try fixing up this series.

Previous: Junio C HamanoNext: Mark Lodato
Message 17 of 20 in “docs: use metavariables consistently”
  1. 00/12 docs: use metavariables consistentlyMark Lodato, Mar 13, 2010
  2. 01/12 commit-tree: allow indirect tree referencesMark Lodato, Mar 13, 2010
  3. Junio C HamanoMar 13, 2010
  4. Mark LodatoMar 16, 2010
  5. 02/12 grep docs: grep accepts a <tree-ish>, not a <tree>Mark Lodato, Mar 13, 2010
  6. Junio C HamanoMar 13, 2010
  7. Mark LodatoMar 16, 2010
  8. 03/12 fsck docs: remove outdated and useless diagnosticMark Lodato, Mar 13, 2010
  9. 04/12 docs: use <sha1> to mean unabbreviated IDMark Lodato, Mar 13, 2010
  10. 05/12 docs: differentiate between <tag> and <tagname>Mark Lodato, Mar 13, 2010
  11. Junio C HamanoMar 13, 2010
  12. 06/12 docs: clarify <object>, <commit>, <tree-ish>, etcMark Lodato, Mar 13, 2010
  13. 07/12 docs: use <tree> instead of <tree-ish>Mark Lodato, Mar 13, 2010
  14. 08/12 http-fetch docs: use <commit-id> consistentlyMark Lodato, Mar 13, 2010
  15. 09/12 docs: use <commit> instead of <commit-ish>Mark Lodato, Mar 13, 2010
  16. Junio C HamanoMar 13, 2010
  17. Mark LodatoMar 16, 2010
  18. 10/12 diff: use brackets for optional args in usageMark Lodato, Mar 13, 2010
  19. 11/12 docs: use ... instead of * for multiplicityMark Lodato, Mar 13, 2010
  20. 12/12 diff docs: remove <rev>{0,2} notationMark Lodato, Mar 13, 2010

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.