* [PATCH] git-clone.txt: document -4 and -6
@ 2023-05-27 12:38 Jakub Wilk
2023-06-01 6:06 ` Junio C Hamano
0 siblings, 1 reply; 7+ messages in thread
From: Jakub Wilk @ 2023-05-27 12:38 UTC (permalink / raw)
To: git; +Cc: Eric Wong, Junio C Hamano
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
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] git-clone.txt: document -4 and -6
2023-05-27 12:38 [PATCH] git-clone.txt: document -4 and -6 Jakub Wilk
@ 2023-06-01 6:06 ` Junio C Hamano
2024-01-02 18:58 ` Jakub Wilk
2024-01-02 19:56 ` Taylor Blau
0 siblings, 2 replies; 7+ messages in thread
From: Junio C Hamano @ 2023-06-01 6:06 UTC (permalink / raw)
To: Jakub Wilk; +Cc: git, Eric Wong
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] git-clone.txt: document -4 and -6
2023-06-01 6:06 ` Junio C Hamano
@ 2024-01-02 18:58 ` Jakub Wilk
2024-01-02 19:56 ` Taylor Blau
1 sibling, 0 replies; 7+ messages in thread
From: Jakub Wilk @ 2024-01-02 18:58 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, Eric Wong
* 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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] git-clone.txt: document -4 and -6
2023-06-01 6:06 ` Junio C Hamano
2024-01-02 18:58 ` Jakub Wilk
@ 2024-01-02 19:56 ` Taylor Blau
2024-01-02 20:36 ` Taylor Blau
1 sibling, 1 reply; 7+ messages in thread
From: Taylor Blau @ 2024-01-02 19:56 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Jakub Wilk, git, Eric Wong
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] git-clone.txt: document -4 and -6
2024-01-02 19:56 ` Taylor Blau
@ 2024-01-02 20:36 ` Taylor Blau
2024-01-02 22:15 ` Junio C Hamano
0 siblings, 1 reply; 7+ messages in thread
From: Taylor Blau @ 2024-01-02 20:36 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Jakub Wilk, git, Eric Wong
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
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] git-clone.txt: document -4 and -6
2024-01-02 20:36 ` Taylor Blau
@ 2024-01-02 22:15 ` Junio C Hamano
2024-01-02 22:25 ` Taylor Blau
0 siblings, 1 reply; 7+ messages in thread
From: Junio C Hamano @ 2024-01-02 22:15 UTC (permalink / raw)
To: Taylor Blau; +Cc: Jakub Wilk, git, Eric Wong
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.
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] git-clone.txt: document -4 and -6
2024-01-02 22:15 ` Junio C Hamano
@ 2024-01-02 22:25 ` Taylor Blau
0 siblings, 0 replies; 7+ messages in thread
From: Taylor Blau @ 2024-01-02 22:25 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Jakub Wilk, git, Eric Wong
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
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2024-01-02 22:25 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-05-27 12:38 [PATCH] git-clone.txt: document -4 and -6 Jakub Wilk
2023-06-01 6:06 ` Junio C Hamano
2024-01-02 18:58 ` Jakub Wilk
2024-01-02 19:56 ` Taylor Blau
2024-01-02 20:36 ` Taylor Blau
2024-01-02 22:15 ` Junio C Hamano
2024-01-02 22:25 ` Taylor Blau
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).