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

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

[Jakub Wilk]

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(+)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index c37c4a37f7..e6f0329510 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -316,6 +316,14 @@ or `--mirror` is given)
 	The number of submodules fetched at the same time.
 	Defaults to the `submodule.fetchJobs` option.
 
+-4::
+--ipv4::
+	Use IPv4 addresses only, ignoring IPv6 addresses.
+
+-6::
+--ipv6::
+	Use IPv6 addresses only, ignoring IPv4 addresses.
+
 <repository>::
 	The (possibly remote) repository to clone from.  See the
 	<<URLS,GIT URLS>> section below for more information on specifying
-- 
2.25.1

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

[Junio C Hamano]

Jakub Wilk <jwilk@jwilk.net> writes:

> 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(+)

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.

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

[Jakub Wilk]

* Junio C Hamano <gitster@pobox.com>, 2023-06-01 15:06:
>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".

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

-- 
Jakub Wilk

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

[Taylor Blau]

On Thu, Jun 01, 2023 at 03:06:35PM +0900, Junio C Hamano wrote:
> Jakub Wilk <jwilk@jwilk.net> writes:
>
> > 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(+)
>
> 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

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

[Taylor Blau]

On Tue, Jan 02, 2024 at 02:56:50PM -0500, Taylor Blau wrote:
> 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

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

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

[Junio C Hamano]

Taylor Blau <me@ttaylorr.com> 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.

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

[Taylor Blau]

On Tue, Jan 02, 2024 at 02:15:57PM -0800, Junio C Hamano wrote:
> Taylor Blau <me@ttaylorr.com> 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?

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