clone: Deprecate the --recursive option in favor of --recurse-submodules
RFC PATCH 1/1 clone: Deprecate the --recursive option in favor of --recurse-submodules
Since 1.6.5 "git clone" honors the --recursive option to recursively check out submodules too. As this option can easily be misinterpreted when it is added to other commands like "git grep", add the new --recurse-submodules option to avoid confusing it with other types of recursion.
---
At the GitTogether some of us were talking about a sane option name for recursing submodules which should then be used consistently by all commands (maybe with the exception of "git submodule", as --recursive there has a pretty obvious meaning). For my first recursion patches a few months ago I started with --recurse-submodules but then I noticed that "git clone" already used "--recursive" for the same purpose, and for consistency reasons I switched to using that too. But especially when looking at recursive grep it is really easy to misinterpret --recursive, so the idea came up to use --recurse-submodules everywhere.
Opinions?
Documentation/git-clone.txt | 5 +++-- builtin/clone.c | 10 ++++++++-- 2 files changed, 11 insertions(+), 4 deletions(-)
Documentation/git-clone.txt +3 -2
@@ -12,7 +12,7 @@ SYNOPSIS 'git clone' [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] - [--depth <depth>] [--recursive] [--] <repository> [<directory>] + [--depth <depth>] [--recurse-submodules] [--] <repository> [<directory>] DESCRIPTION -----------
@@ -166,13 +166,14 @@ objects from the source repository into a pack in the cloned repository. with a long history, and would want to send in fixes as patches. ---recursive:: +--recurse-submodules:: After the clone is created, initialize all submodules within, using their default settings. This is equivalent to running `git submodule update --init --recursive` 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) + This option replaces the now deprecated `--recursive`. <repository>:: The (possibly remote) repository to clone from. See the
builtin/clone.c +8 -2
@@ -43,7 +43,7 @@ static char *option_template, *option_reference, *option_depth;static char *option_origin =NULL ;static char *option_branch =NULL ;static char *option_upload_pack ="git-upload-pack" ; -static int option_verbosity; +static int option_verbosity, option_recurse_submodules;static int option_progress;static struct option builtin_clone_options[] = {
@@ -65,6 +65,8 @@ static struct option builtin_clone_options[] = {OPT_BOOLEAN ('s' ,"shared" , &option_shared,"setup as shared repository" ),OPT_BOOLEAN (0 ,"recursive" , &option_recursive, +"initialize submodules in the clone (deprecated)" ), +OPT_BOOLEAN (0 ,"recurse_submodules" , &option_recurse_submodules,"initialize submodules in the clone" ),OPT_STRING (0 ,"template" , &option_template,"path" , "path the template repository"),
@@ -659,7 +661,11 @@ int cmd_clone(int argc, const char **argv, const char *prefix)sha1_to_hex (our_head_points_at->old_sha1),"1" , NULL); -if (!err && option_recursive) +if (option_recursive) { +warning ("--recursive is deprecated; use --recurse-submodules instead." ); + option_recurse_submodules =1 ; + } +if (!err && option_recurse_submodules) err =run_command_v_opt (argv_submodule,RUN_GIT_CMD ); }
Signature · 1 line
1.7.3.2.213.g5fe186
Quoted 8 lines · Jens Lehmann
... For my first recursion patches a
few months ago I started with --recurse-submodules but then I noticed that "git clone" already used "--recursive" for the same purpose, and for consistency reasons I switched to using that too. But especially when looking at recursive grep it is really easy to misinterpret --recursive, so the idea came up to use --recurse-submodules everywhere.Opinions?
I think it would make sense to _add_ --recurse-submodules to "clone" to make everybody consistent.
With the introduction of --recurse-submodules option, the user can rest assured that --recurse-submodules is understood by any command that knows how to descend into submodules. A command may have --recursive option (or it may not), and when it does, the option may or may not mean descending into submodules. E.g. if "git ls-tree" learns long options, --recursive would mean "recurse into subtrees" and you would say --no-recursive to countermand.
As it does not make any sense to say "clone --no-recursive" to limit the clone to the top-level directory, --recursive to "clone" would need to mean "descend into subprojects". So in that sense, "clone --recursive" shares a similar degree of obviousness with "submodule --recursive". I thing it is too strong to _deprecate_ the option in the context of that command.
PATCH 1/1 clone: Add the --recurse-submodules option as alias for --recursive
Since 1.6.5 "git clone" honors the --recursive option to recursively check out submodules too. As this option can easily be misinterpreted when it is added to other commands like "git grep", add the new --recurse-submodules option as an alias for --recursive so the same option can be used for all commands recursing into submodules.
---
Am 03.11.2010 23:36, schrieb Junio C Hamano:
Quoted 9 lines
Quoted 7 lines · Jens Lehmann
... For my first recursion patches a
few months ago I started with --recurse-submodules but then I noticed that "git clone" already used "--recursive" for the same purpose, and for consistency reasons I switched to using that too. But especially when looking at recursive grep it is really easy to misinterpret --recursive, so the idea came up to use --recurse-submodules everywhere.
Quoted 7 lines
Quoted 1 line
Opinions?
I think it would make sense to _add_ --recurse-submodules to "clone" to make everybody consistent.
... I
thing it is too strong to _deprecate_ the option in the context of that command.
Fine by me, then what about this patch?
And am I right to assume that there are no objections against using --recurse-submodule for fetch, checkout & friends?
Documentation/git-clone.txt | 4 +++- builtin/clone.c | 2 ++ 2 files changed, 5 insertions(+), 1 deletions(-)
Documentation/git-clone.txt +3 -1
@@ -12,7 +12,8 @@ SYNOPSIS 'git clone' [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] - [--depth <depth>] [--recursive] [--] <repository> [<directory>] + [--depth <depth>] [--recursive|--recurse-submodules] [--] <repository> + [<directory>] DESCRIPTION -----------
@@ -167,6 +168,7 @@ objects from the source repository into a pack in the cloned repository. as patches. --recursive:: +--recurse-submodules:: After the clone is created, initialize all submodules within, using their default settings. This is equivalent to running `git submodule update --init --recursive` immediately after
builtin/clone.c +2 -0
@@ -66,6 +66,8 @@ static struct option builtin_clone_options[] = { "setup as shared repository"),OPT_BOOLEAN (0 ,"recursive" , &option_recursive,"initialize submodules in the clone" ), +OPT_BOOLEAN (0 ,"recurse_submodules" , &option_recursive, +"initialize submodules in the clone" ),OPT_STRING (0 ,"template" , &option_template,"path" ,"path the template repository" ), OPT_STRING(0, "reference", &option_reference, "repo",
Signature · 1 line
1.7.3.2.194.ge0b67
builtin/clone.c static struct option builtin_clone_options[] = { · line 72
Quoted 9 lines · Jens Lehmann
builtin/clone.c +2
-0@@ -65,6 +65,8 @@ static struct option builtin_clone_options[] = {OPT_BOOLEAN ('s' ,"shared" , &option_shared,"setup as shared repository" ),OPT_BOOLEAN (0 ,"recursive" , &option_recursive, +"initialize submodules in the clone (deprecated)" ), +OPT_BOOLEAN (0 ,"recurse_submodules" , &option_recurse_submodules,"initialize submodules in the clone" ),OPT_STRING (0 ,"template" , &option_template,"path" , "path the template repository"),
Shouldn't we use PARSE_OPT_HIDDEN? Or should it be left for later?
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
Heya,
Quoted 1 line · Jakub Narebski
Shouldn't we use
PARSE_OPT_HIDDEN? Or should it be left for later?
I assumed we would add PARSE_OPT_HIDDEN in a few releases. Perhaps that patch should also be sent.
Signature · 3 lines
Cheers, Sverre Rabbelier