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

[Taylor Blau <me@xxxxxxxxxxxx>]

On Thu, Jun 01, 2023 at 03:06:35PM +0900, Junio C Hamano wrote:
> Jakub Wilk <jwilk@xxxxxxxxx> writes:
>
> > These options were added in c915f11eb4 ("connect & http: support -4 and
> > -6 switches for remote operations").
> >
> > Signed-off-by: Jakub Wilk <jwilk@xxxxxxxxx>
> > ---
> >  Documentation/git-clone.txt | 8 ++++++++
> >  1 file changed, 8 insertions(+)
>
> 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

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