Re: [PATCH v2 01/11] builtin/init: rename "--ref-format=" to "--ref-storage-format="

On 9/9/26 12:30, Patrick Steinhardt wrote:

On Tue, Sep 08, 2026 at 02:31:22PM +0530, Kaartic Sivaraam wrote:

I'm aiming for a a quiet deprecation -- the old options keep on working,
but we don't show them anymore. We may eventually remove them
altogether, but I neither want to warn about use of old options now or
even remove them as that would likely cause more negative consequences
than is worth it. It's not like we want to soon use the old names.

Understood.

But I agree that we should keep the old options documented. Otherwise,
it might be hard to figure out what those options do in case they for
example still exist in an old script.

Yeah, makes sense.

quoted

Relevant only if we are deprecating the old option: We could change the
description of the old option to convey that it is deprecated so that it
could be easily distinguished by anyone reading through. I suggest this by
noting a similar pattern in `builtin/name-rev.c` for the `--stdin` argument.

We don't really have to update the description as we pass
`PARSE_OPT_HIDDEN` anyway, so the option is not even shown.

Indeed. I was suggesting to change the description only for the sake of 
someone who reads the code to quickly get an idea that we have 
deprecated the old names. The PARSE_OPT_HIDDEN would definitely hint at 
it but this just a suggestion to make it more obvious :-)

That said, it's fine if we don't change the description too. It isn't a 
big deal.

quoted

If we don't plan to deprecate, I suppose we could use OPT_ALIAS to clarify
that `ref-format` is an alias of `ref-storage-format` similar to how
`recursive` is marked as an alias of `recurse-submodules` in
`builtin/clone.c`.

I was originally planning to use `OPT_ALIAS()`, but we don't seem to
support `PARSE_OPT_HIDDEN` there. Maybe it's better to add a small
preparatory patch to support that though.

Indeed. OPT_ALIAS does have that caveat. A patch to allow the alias to 
be hidden by choice would indeed be worthwhile.

-- 
Sivaraam