git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH v3 01/13] parse-options: allow for hidden aliases

From
Junio C Hamano <gitster@pobox.com>
Date
Sep 15, 2026, 14:41 UTC
Message-ID
<xmqq1pau37bo.fsf@gitster.g>
In-Reply-To
<c5266fff-8247-48d2-9679-3fc1f649cf34@gmail.com>
Kaartic Sivaraam <kaartic.sivaraam@gmail.com> writes:
Show 27 quoted lines
>> Perhaps it doesn't make sense to add flags to OPT_ALIAS() at all?
>> ...
>
> Just some food for thought. There are a couple of other instances where 
> we are currently using OPT_ALIAS to represent the deprecated variant of 
> an option. They are:
>
>    1. `--recursive` is a deprecated alias of  `--recurse-submodule` in
>       `git clone`
>
>       cf. bb62e0a99f (clone: teach --recurse-submodules to optionally
>       take a pathspec, 2017-03-17) and 5c387428f1 (parse-options: don't
>       emit "ambiguous option" for aliases, 2019-04-29)
>
>    2.  `--negotiation-tip` is a deprecated alias of
>        `--negotiation-restrict` in `git fetch`
>
>        cf. 1a445fc60b (fetch: add --negotiation-restrict option,
>        2026-05-19)
>
>        Note: The documentation clarifies that --negotiation-restrict is
>        the preferred variant but does not mention about deprecation.
>
> Since they are not hidden, the deprecated variants still show up in the 
> help output of those commands. So, we appear to be doing fine with a 
> public alias so far. So, may be it is not a big deal if we expose the 
> deprecated option publicly?

The OPT_HIDDEN bit for an option indeed is a mechanism for deprecation and it is not limited to alias.

When an option has a clearly better alternative, we would want to eventually remove the old one and have everybody use the new one. For that to happen, we need to let people know that the old thing is on its way out, and "git cmd -h" is a good place to do so. We do not want to use OPT_HIDDEN in earlier half of the deprecation. After sufficient time passes, there will be a lot of new users who are equally unfamiliar with old and new options. Telling them about old way that is on its way out does not help them at all. So at some point, we want to start using OPT_HIDDEN for such options.

When nobody uses the old option, we can remove the entry from the options[] array, or we can keep it and use it only to cause an error message (i.e., "This option used to do something, but no longer. Do not use it anymore").

If OPT_ALIAS() does not allow using OPT_HIDDEN, that is a bug in the infrastructure. It does not have to block a new topic that uses OPT_ALIAS(), but we can leave a #leftoverbit mark to invite interested parties to work on fixing it.

Thanks.
Previous: Kaartic SivaraamNext: Patrick Steinhardt
Message 5 of 20 in “Fix inconsistent ref storage format terminology”
  1. 00/13 Fix inconsistent ref storage format terminologyPatrick Steinhardt, Sep 9, 2026
  2. 01/13 parse-options: allow for hidden aliasesPatrick Steinhardt, Sep 9, 2026
  3. Karthik NayakSep 14, 2026
  4. Kaartic SivaraamSep 15, 2026
  5. Junio C HamanoSep 15, 2026
  6. 02/13 builtin/init: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 9, 2026
  7. 03/13 builtin/clone: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 9, 2026
  8. 04/13 builtin/refs: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 9, 2026
  9. 05/13 builtin/submodule: rename "--ref-format=" to "--ref-storage-format="Patrick Steinhardt, Sep 9, 2026
  10. 06/13 builtin/rev-parse: rename "--show-ref-format" to "--show-ref-storage-format"Patrick Steinhardt, Sep 9, 2026
  11. 07/13 help: rename "default-ref-format" to "default-ref-storage-format"Patrick Steinhardt, Sep 9, 2026
  12. 08/13 refs: expose function to parse reference URIsPatrick Steinhardt, Sep 9, 2026
  13. 09/13 setup: refactor how we configure the ref storage formatPatrick Steinhardt, Sep 9, 2026
  14. 10/13 setup: rename ref storage format environment variablesPatrick Steinhardt, Sep 9, 2026
  15. 11/13 t: rename GIT_TEST_DEFAULT_REF_FORMATPatrick Steinhardt, Sep 9, 2026
  16. 12/13 setup: rename "init.defaultRefFormat" to "init.defaultRefStorageFormat"Patrick Steinhardt, Sep 9, 2026
  17. 13/13 setup: allow "--ref-storage-format=" to specify a payloadPatrick Steinhardt, Sep 9, 2026
  18. Karthik NayakSep 14, 2026
  19. Junio C HamanoSep 14, 2026
  20. Kaartic SivaraamSep 14, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.