git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* Slightly confusing documentation for "git clone --recursive"
@ 2019-05-21 21:25 Keith Thompson
  0 siblings, 0 replies; only message in thread
From: Keith Thompson @ 2019-05-21 21:25 UTC (permalink / raw)
  To: git; +Cc: Keith Thompson

In builtin/clone.c, the handling of "--recursive" as an alias for
"--recurse-submodules" changed between
v2.22.0-rc0 and v2.22.0-rc1. This report refers to the way it's
documented in the newest version
and suggests some improvements.

The short help (git clone -h) says:

    --recursive[=<pathspec>]
                          initialize submodules in the clone
    --recurse-submodules[=<pathspec>]
                          initialize submodules in the clone

It repeats the same description, but doesn't explicitly say that
they're equivalent. I can imagine
this causing some confusion. I might have wondered if there's some
subtle difference between them.
Suggested change:

    --recursive[=<pathspec>]
    --recurse-submodules[=<pathspec>]
                          initialize submodules in the clone

The long help ("git clone --help") says:

       --recurse-submodules[=<pathspec]
           After the clone is created, initialize and clone submodules within
           based on the provided pathspec. If no pathspec is provided, all
           submodules are initialized and cloned. This option can be given
           multiple times for pathspecs consisting of multiple entries. The
           resulting clone has submodule.active set to the provided pathspec,
           or "." (meaning all submodules) if no pathspec is provided.

           Submodules are initialized and cloned using their default settings.
           This is equivalent to running git submodule update --init
           --recursive <pathspec> immediately after the clone is finished.
           This option is ignored if the cloned repository does not have a
           worktree/checkout (i.e. if any of --no-checkout/-n, --bare, or
           --mirror is given)

The "--recursive" spelling is not documented, but is used in an example in
the documentation for "--recursive-submodules". Suggested change:

       --recursive=<pathspec]
       --recurse-submodules[=<pathspec]
           After the clone is created, initialize and clone submodules within
           [... rest of description as before]

^ permalink raw reply	[flat|nested] only message in thread

only message in thread, other threads:[~2019-05-21 21:26 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-05-21 21:25 Slightly confusing documentation for "git clone --recursive" Keith Thompson

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.version-control.git
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.version-control.git
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git