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

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.

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

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.

On Sun, Sep 26, 2010 at 3:54 AM, Junio C Hamano <gitster@pobox.com> wrote:

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::

On Sun, Sep 26, 2010 at 3:54 AM, Junio C Hamano <gitster@pobox.com> wrote:

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.