RFC: what should git rev-parse --flags HEAD do?

RFC: what should git rev-parse --flags HEAD do?

[Jon Seymour]

The documentation for git rev-parse --flags currently states:

    Do not output non-flag parameters.

Therefore, one might expect:
  $ git rev-parse --flags HEAD

to produce no output.

In fact, it outputs the sha1 hash of HEAD.

Can anyone see a reason why git rev-parse --flags should not be
modified to match the documentation?

If there is agreement that this should change, I can re-roll my
current rev-parse series to include such a change.

jon.

Re: RFC: what should git rev-parse --flags HEAD do?

[Junio C Hamano]

Jon Seymour <jon.seymour@gmail.com> writes:

> The documentation for git rev-parse --flags currently states:
>
>     Do not output non-flag parameters.
>
> Therefore, one might expect:
>   $ git rev-parse --flags HEAD
>
> to produce no output.
>
> In fact, it outputs the sha1 hash of HEAD.

Perhaps you are missing --no-revs.

Linus wrote rev-parse to implement this in a shell script:

    git log [other-options-and-args] [revision-traversal-options-and-args]

which needs to be transformed to:

    git rev-list [revision-traversal-options-and-args] |
    git diff-tree --stdin [other-options-and-args]

so that it can parse "-p HEAD" with and without "--no-revs" to produce
"HEAD" and "-p" respectively.  It does so by knowing options that are
relevant to rev-list invocation (shown by default, or --revs-only) and 
everything else (hidden when --no-revs is given).

"--flags" is an afterthought that filters out non-flags in other parts; I
do not think it applied to the "rev" part (i.e. giving --no-revs at the
same time would be a valid workaround if you know you do not want HEAD or
any revision traversal argument) in any released version of git.

Re: RFC: what should git rev-parse --flags HEAD do?

[Jon Seymour]

On Sun, Sep 26, 2010 at 3:54 AM, Junio C Hamano <gitster@pobox.com> wrote:
>
> Perhaps you are missing --no-revs.
> ...

> "--flags" is an afterthought that filters out non-flags in other parts; I
> do not think it applied to the "rev" part (i.e. giving --no-revs at the
> same time would be a valid workaround if you know you do not want HEAD or
> any revision traversal argument) in any released version of git.
>

i am aware that --no-revs exists and can be used with --flags to
ensure that only flag arguments are displayed.

The issue is that the documentation currently implies that --flags
alone is sufficient to suppress anything that is not a flag when this
is not, in fact, the case.

If there is some reason --flags should not imply --no-revs, then the
documentation should be updated to state:

--flags::

Re: RFC: what should git rev-parse --flags HEAD do?

[Jon Seymour]

On Sun, Sep 26, 2010 at 3:54 AM, Junio C Hamano <gitster@pobox.com> wrote:
>
> Perhaps you are missing --no-revs.
> ...

> "--flags" is an afterthought that filters out non-flags in other parts; I
> do not think it applied to the "rev" part (i.e. giving --no-revs at the
> same time would be a valid workaround if you know you do not want HEAD or
> any revision traversal argument) in any released version of git.
>

i am aware that --no-revs exists and can be used with --flags to
ensure that only flag arguments are displayed.

The issue is that the documentation currently implies that --flags
alone is sufficient to suppress anything that is not a flag when this
is not, in fact, the case.  To wit:

--flags::
       Do not output any non-flag parameters.

This is simply not accurate, given the current implementation.

If there is some reason --flags should not imply --no-revs, then the
documentation should be updated to state:

--flags::
       Do not output any non-flag parameters (unless the parameter
also specifies a revision). To output only the flag parameters,
specify --no-revs as well.

jon.