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

From: Junio C Hamano <[email-masked]>
Date: Tue, 02 Jan 2024 14:15:57 -0800

Taylor Blau <[email-masked]> writes:

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