Re: [PATCH] git-clone.txt: document -4 and -6

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 2, 2024, 22:15 UTC
Message-ID: <xmqqr0izcrfm.fsf@gitster.g>
In-Reply-To: <ZZRzxZNb2Aq+2feW@nand.local>

Taylor Blau <me@ttaylorr.com> writes:

Show 10 quoted lines

> Note that the 'clone' and 'fetch' versions for many of these options
> have different wording. For example, in Documentation/git-clone.txt we
> have:
>
>     -j::
>     --jobs=<n>::
>            Number of parallel children to be used for all forms of fetching.
>
> Whereas the description in the original fetch-options.txt is more
> verbose.

Yes, so it will be impossible to unify without changing the resulting text. But unless one description is clearly better for one subcommand while the other description is also clearly better for the other subcommand, we should be able to pick a better one that would serve both subcommands, and that way we would improve description for one subcommand while keeping the other one the same, right?

> In fact, the story is even more complicated than that, since even though
> the 'push' builtin would benefit from having a shared source of
> documentation for the --ipv4 and --ipv6 options, 'push' does not have a
> --jobs option.

Sure, it won't be just "write what is shared across all the transfer commands in a single file and include it from all". The direction of transfer is a reason why the options may differ, of course, so we may need to have two (or three) include files if we want to go that route.

> --progress could be shared, as could --server-option, and the two
> --ipv4/6 options. But the number of nested ifdefs necessary to share the
> other options probably dose not justify the effort to do so.