patchgit-clone.txt: document -4 and -6

These options were added in c915f11eb4 ("connect & http: support -4 and -6 switches for remote operations").

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
---
 Documentation/git-clone.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

Jakub Wilk <jwilk@jwilk.net> writes:

The patch is not _wrong_ per-se, but there are other options that are common among the "fetch" family of commands. I counted at least these should be shared between "fetch" and "clone", by splitting them out of "fetch-options.txt" into a new file, and including that new file from "fetch-options.txt" and "git-clone.txt". Those marked with (?) are described in different phrasing between "clone" and "fetch", and may fall into the "let's keep them separate, because they mean different things" category (later):

 * --jobs
 * --upload-pack
 * --quiet (?)
 * --verbose (?)
 * --progress
 * --server-option
 * --ipv[46]

Note that these happen to share the same name, but to "clone" and "fetch" they different things, so leaving them separate is the right thing to do.

 * --no-tags
 * --recurse-submodules

Thanks.

* Junio C Hamano <gitster@pobox.com>, 2023-06-01 15:06:

Agreed such a split would be better, but I don't have energy to implement it.

On Thu, Jun 01, 2023 at 03:06:35PM +0900, Junio C Hamano wrote:

I wrote this ugly shell incantation to find an exhaustive list of potentially shareable options:

    $ grep '^-.*::$' <Documentation/fetch-options.txt |
      tr -d ':' | sed -e 's/\[=/=[/' -e 's/<[^>]*>//' |
      grep -Eo '^[^=]+' | awk -F] '
        /\[no-\]/ { print "--" $2; print "--no-" $2; next }
        { print $0 }
      ' |
    while read arg
    do
      if grep -Fwq -- $arg Documentation/fetch-options.txt &&
         grep -Fwq -- $arg Documentation/git-clone.txt
      then
        echo $arg;
      fi
    done

It turned up the following results:

    -a
    --depth
    --shallow-since
    --shallow-exclude
    --no-tags
    --recurse-submodules
    -j, --jobs
    -u, --upload-pack
    -q, --quiet
    -v, --verbose
    --progress
    -o, --server-option

-a is a false-positive (it comes from "you can simply run `git repack -a`", which is in the clone documentation).

Even though depth, and the shallow options are shared by both fetch and clone, they have different wording in each context, so they should be kept separate.

I agree with your thinking that `--no-tags` and `--recurse-submodules` should be kept separate.

That makes our two lists equal (modulo the --ipv[46] options, which were previously not documented in git-clone(1) until this patch).

Thanks, Taylor

On Tue, Jan 02, 2024 at 02:56:50PM -0500, Taylor Blau wrote:

Hmm. I think the story is a little more complicated. Just looking at the ones that we agree on:

  * -j, --jobs
  * -u, --upload-pack
  * --progress
  * -o, --server-option
  * --[ipv]4
  * --[ipv]6

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.

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.

'clone', 'fetch', and 'pull' all share an '--upload-pack' option as you note, though 'push' naturally doesn't (so we would need another ifdef there, too). But the instances in 'clone', 'fetch', and 'pull' all differ in their wording (e.g., the 'clone' documentation says "the repository to clone from ..." but the others say "the repository to fetch from ...").

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

Thanks, Taylor

Taylor Blau <me@ttaylorr.com> writes:

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?

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.

On Tue, Jan 02, 2024 at 02:15:57PM -0800, Junio C Hamano wrote:

Right. I meant to illustrate merely that this would probably involve some word-smithing instead of just pure cut-and-paste, so that it may not be worth the effort.

Thanks, Taylor