Re: [PATCH 2/4] glossary: define committish (a.k.a. commit-ish)

[Junio C Hamano <gitster@pobox.com>]

Richard Hansen <rhansen@bbn.com> writes:

> Signed-off-by: Richard Hansen <rhansen@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.