Re: [PATCH v2 21/25] rev-list: add --index-objects option

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

Jeff King <peff@peff.net> writes:

> There is currently no easy way to ask the revision traversal
> machinery to include objects reachable from the index (e.g.,
> blobs and trees that have not yet been committed). This
> patch adds an option to do so.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> I was tempted to call this just "--index", because I could not think of
> what else "--index" would mean in the context of rev-list. But I also
> worried about weird interactions with other commands that take revision
> arguments. And since this is mostly for internal use anyway, I figured
> the more verbose name is not too bad. I could be convinced otherwise,
> though.

I agree that "--index" is a bad name as it usually is used in a
particular context: the command can work on various combination of
working tree and the index, and I am asking it to work on both
(e.g. "apply --index" as opposed to "apply --cached").

> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index 4cf94c6..03ab343 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -172,6 +172,13 @@ explicitly.
>  	Pretend as if all objects mentioned by reflogs are listed on the
>  	command line as `<commit>`.
>  
> +--index-objects::

This risks "index" getting misunderstood as a verb, e.g. "please
enumerate the objects and assign labels to later refer to them",
doesn't it?

"--indexed-objects" (short for "--show-objects-in-the-index") or
something?

> +	Pretend as if all objects used by the index (any blobs, and any
> +	trees which are mentioned by the index's cache-tree extension)
> +	ad listed on the command line. Note that you probably want to

s/ad/are/, probably?

> +	use `--objects`, too, as there are by definition no commits in
> +	the index.

For gitlinks/submodules, the index records names of the commit
objects, they are not listed, and that is the right behaviour, but
this description invites some confusion.