sparse-checkout: make set subsume init

From: Elijah Newren <[email protected]>

The previously suggested workflow:
git sparse-checkout init ...
git sparse-checkout set ...

Suffered from three problems:
1) It would delete nearly all files in the first step, then restore them in the second. That was poor performance and forced unnecessary rebuilds.
2) The two-step process resulted in two progress bars, which was suboptimal from a UI point of view for wrappers that invoked both of these commands but only exposed a single command to their end users.
3) With cone mode, the first step would delete nearly all ignored files everywhere, because everything was considered to be outside of the specified sparsity paths. (The user was not allowed to specify any sparsity paths in the init step.)

Avoid these problems by teaching set to understand the extra parameters that init takes and performing any necessary initialization if not already in a sparse checkout.

Signed-off-by Elijah Newren <[email protected]>

---
 builtin/sparse-checkout.c | 52 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

builtin/sparse-checkout.c +0 -0

index e252b82136e..cf6a6c6c3a7 100644

builtin/sparse-checkout.c +2 -0

 	NULL
 };
 
 static struct sparse_checkout_set_opts {
+	int cone_mode;
+	int sparse_index;
 	int use_stdin;
 } set_opts;
 
 static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
 {

builtin/sparse-checkout.c +3 -0

 		OPT_END(),

@@ -700,11 +709,52 @@ static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
 
 	repo_read_index(the_repository);
 
+	set_opts.cone_mode = -1;
+	set_opts.sparse_index = -1;
+
 	argc = parse_options(argc, argv, prefix,

builtin/sparse-checkout.c +32 -0

+		set_opts.cone_mode = core_sparse_checkout_cone;
+
+	/* Set cone/non-cone mode appropriately */
+	if (set_opts.cone_mode == 1) {
+		mode = MODE_CONE_PATTERNS;
+		core_sparse_checkout_cone = 1;
+	} else {
+		mode = MODE_ALL_PATTERNS;
+	}
+	if (record_mode && set_config(mode))
+		return 1;
+
+	/* Set sparse-index/non-sparse-index mode if specified */
+	if (set_opts.sparse_index >= 0) {
+		if (set_sparse_index_config(the_repository, set_opts.sparse_index) < 0)
+			die(_("failed to modify sparse-index config"));
+
+		/* force an index rewrite */
+		repo_read_index(the_repository);
+		the_repository->index->updated_workdir = 1;
+	}
+
+	/*
+	 * Cone mode automatically specifies the toplevel directory.  For
+	 * non-cone mode, if nothing is specified, manually select just the
+	 * top-level directory (much as 'init' would do).
+	 */
+	if (!core_sparse_checkout_cone && argc == 0) {
+		argv = default_patterns;
+		argc = 2;
+	}
+
 	return modify_pattern_list(argc, argv, set_opts.use_stdin, REPLACE);
 }
 

Quoted 19 lines · Elijah Newren via GitGitGadget

From: Elijah Newren <[email protected]>

The previously suggested workflow:
git sparse-checkout init ...
git sparse-checkout set ...

Suffered from three problems:
1) It would delete nearly all files in the first step, then restore them in the second. That was poor performance and forced unnecessary rebuilds.
2) The two-step process resulted in two progress bars, which was suboptimal from a UI point of view for wrappers that invoked both of these commands but only exposed a single command to their end users.
3) With cone mode, the first step would delete nearly all ignored files everywhere, because everything was considered to be outside of the specified sparsity paths. (The user was not allowed to specify any sparsity paths in the init step.)

Quoted 4 lines

Avoid these problems by teaching set to understand the extra parameters that init takes and performing any necessary initialization if not already in a sparse checkout.

I really like this change! It always seemed weird that set would implicitly init, but without any of the options in init.

Quoted 12 lines

Signed-off-by Elijah Newren <[email protected]>

---
 builtin/sparse-checkout.c | 52 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

builtin/sparse-checkout.c +0 -0

index e252b82136e..cf6a6c6c3a7 100644
@@ -682,17 +682,26 @@ static int sparse_checkout_add(int argc, const char **argv, const char *prefix)
 }
 

builtin/sparse-checkout.c static int sparse_checkout_add(int argc, const char **argv, const char *prefix) · line 685

Quoted 3 lines

builtin/sparse-checkout.c +1 -1

 static char const * const builtin_sparse_checkout_set_usage[] = {
-     N_("git sparse-checkout set (--stdin | <patterns>)"),
+     N_("git sparse-checkout set [--cone] [--[no-]sparse-index] (--stdin | <patterns>)"),

Since cone is an OPT_BOOL, shouldn't it appear in the usage string as --[no-]cone? Without a --no-cone option, it's not clear how a user would disable cone mode (since set preserves the existing cone mode setting if --cone isn't given).

Quoted 11 lines

builtin/sparse-checkout.c +2 -0

      NULL
 };
 
 static struct sparse_checkout_set_opts {
+     int cone_mode;
+     int sparse_index;
      int use_stdin;
 } set_opts;
 
 static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
 {

builtin/sparse-checkout.c static int sparse_checkout_add(int argc, const char **argv, const char *prefix) · line 706

Quoted 10 lines

builtin/sparse-checkout.c +7 -0

+     int mode, record_mode;
+     const char *default_patterns[] = {"/*", "!/*/"};
+
      static struct option builtin_sparse_checkout_set_options[] = {
+             OPT_BOOL(0, "cone", &set_opts.cone_mode,
+                      N_("initialize the sparse-checkout in cone mode")),
+             OPT_BOOL(0, "sparse-index", &set_opts.sparse_index,
+                      N_("toggle the use of a sparse index")),
              OPT_BOOL(0, "stdin", &set_opts.use_stdin,
                       N_("read patterns from standard in")),

I know this isn't part of this patch, but is stdin really a bool (i.e. someone might specify --no-stdin)? If not, I think OPT_SET_INT might be more appropriate.

Quoted 13 lines

builtin/sparse-checkout.c +3 -0

              OPT_END(),

@@ -700,11 +709,52 @@ static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
 
      repo_read_index(the_repository);
 
+     set_opts.cone_mode = -1;
+     set_opts.sparse_index = -1;
+
      argc = parse_options(argc, argv, prefix,
                           builtin_sparse_checkout_set_options,
                           builtin_sparse_checkout_set_usage,
                           PARSE_OPT_KEEP_UNKNOWN);
 

builtin/sparse-checkout.c static int sparse_checkout_set(int argc, const char **argv, const char *prefix) · line 725

Quoted 6 lines

builtin/sparse-checkout.c +6 -0

+     /* Determine if we need to record the mode; ensure sparse checkout on */
+     record_mode = (set_opts.cone_mode != -1) || !core_apply_sparse_checkout;
+     core_apply_sparse_checkout = 1;
+
+     /* If not specified, use previous definition of cone mode */
+     if (set_opts.cone_mode == -1 && core_apply_sparse_checkout)

I *think* this is supposed go before the core_apply_sparse_checkout = 1; above it (if the intention is to only use the pre-existing cone mode setting when already in a sparse checkout). If not, the core_apply_sparse_checkout part of the condition is redundant and can be removed entirely.

Quoted 34 lines

builtin/sparse-checkout.c +32 -0

+             set_opts.cone_mode = core_sparse_checkout_cone;
+
+     /* Set cone/non-cone mode appropriately */
+     if (set_opts.cone_mode == 1) {
+             mode = MODE_CONE_PATTERNS;
+             core_sparse_checkout_cone = 1;
+     } else {
+             mode = MODE_ALL_PATTERNS;
+     }
+     if (record_mode && set_config(mode))
+             return 1;
+
+     /* Set sparse-index/non-sparse-index mode if specified */
+     if (set_opts.sparse_index >= 0) {
+             if (set_sparse_index_config(the_repository, set_opts.sparse_index) < 0)
+                     die(_("failed to modify sparse-index config"));
+
+             /* force an index rewrite */
+             repo_read_index(the_repository);
+             the_repository->index->updated_workdir = 1;
+     }
+
+     /*
+      * Cone mode automatically specifies the toplevel directory.  For
+      * non-cone mode, if nothing is specified, manually select just the
+      * top-level directory (much as 'init' would do).
+      */
+     if (!core_sparse_checkout_cone && argc == 0) {
+             argv = default_patterns;
+             argc = 2;
+     }
+
      return modify_pattern_list(argc, argv, set_opts.use_stdin, REPLACE);
 }

Quoted 41 lines · Victoria Dye

Quoted 19 lines · Elijah Newren via GitGitGadget

From: Elijah Newren <[email protected]>

The previously suggested workflow:
git sparse-checkout init ...
git sparse-checkout set ...

Suffered from three problems:
1) It would delete nearly all files in the first step, then restore them in the second. That was poor performance and forced unnecessary rebuilds.
2) The two-step process resulted in two progress bars, which was suboptimal from a UI point of view for wrappers that invoked both of these commands but only exposed a single command to their end users.
3) With cone mode, the first step would delete nearly all ignored files everywhere, because everything was considered to be outside of the specified sparsity paths. (The user was not allowed to specify any sparsity paths in the init step.)

Quoted 4 lines

Avoid these problems by teaching set to understand the extra parameters that init takes and performing any necessary initialization if not already in a sparse checkout.

I really like this change! It always seemed weird that set would implicitly init, but without any of the options in init.

Quoted 12 lines

Signed-off-by Elijah Newren <[email protected]>

---
  builtin/sparse-checkout.c | 52 ++++++++++++++++++++++++++++++++++++++-
  1 file changed, 51 insertions(+), 1 deletion(-)

builtin/sparse-checkout.c +0 -0

index e252b82136e..cf6a6c6c3a7 100644
@@ -682,17 +682,26 @@ static int sparse_checkout_add(int argc, const char **argv, const char *prefix)
  }
 

Quoted 8 lines

builtin/sparse-checkout.c static int sparse_checkout_add(int argc, const char **argv, const char *prefix) · line 685

Quoted 3 lines

builtin/sparse-checkout.c +1 -1

  static char const * const builtin_sparse_checkout_set_usage[] = {
-     N_("git sparse-checkout set (--stdin | <patterns>)"),
+     N_("git sparse-checkout set [--cone] [--[no-]sparse-index] (--stdin | <patterns>)"),

Since cone is an OPT_BOOL, shouldn't it appear in the usage string as --[no-]cone? Without a --no-cone option, it's not clear how a user would disable cone mode (since set preserves the existing cone mode setting if --cone isn't given).

Yeah, fair point. When copying from init I probably should have double checked.

Also, it makes me wonder if we should just make cone mode the default...

Quoted 22 lines

Quoted 11 lines

builtin/sparse-checkout.c +2 -0

       NULL
  };
 
  static struct sparse_checkout_set_opts {
+     int cone_mode;
+     int sparse_index;
       int use_stdin;
  } set_opts;
 
  static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
  {

builtin/sparse-checkout.c static int sparse_checkout_add(int argc, const char **argv, const char *prefix) · line 706

Quoted 10 lines

builtin/sparse-checkout.c +7 -0

+     int mode, record_mode;
+     const char *default_patterns[] = {"/*", "!/*/"};
+
       static struct option builtin_sparse_checkout_set_options[] = {
+             OPT_BOOL(0, "cone", &set_opts.cone_mode,
+                      N_("initialize the sparse-checkout in cone mode")),
+             OPT_BOOL(0, "sparse-index", &set_opts.sparse_index,
+                      N_("toggle the use of a sparse index")),
               OPT_BOOL(0, "stdin", &set_opts.use_stdin,
                        N_("read patterns from standard in")),

Quoted 3 lines

I know this isn't part of this patch, but is stdin really a bool (i.e. someone might specify --no-stdin)? If not, I think OPT_SET_INT might be more appropriate.

Good point. OPT_SET_INT() wouldn't fix it, though; you need to use OPT_BOOL_F or OPT_SET_INT_F and pass PARSE_OPT_NONEG as a flag. I can include that.

Quoted 13 lines

Quoted 13 lines

builtin/sparse-checkout.c +3 -0

               OPT_END(),

@@ -700,11 +709,52 @@ static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
 
       repo_read_index(the_repository);
 
+     set_opts.cone_mode = -1;
+     set_opts.sparse_index = -1;
+
       argc = parse_options(argc, argv, prefix,
                            builtin_sparse_checkout_set_options,
                            builtin_sparse_checkout_set_usage,
                            PARSE_OPT_KEEP_UNKNOWN);
 

Quoted 11 lines

builtin/sparse-checkout.c static int sparse_checkout_set(int argc, const char **argv, const char *prefix) · line 725

Quoted 6 lines

builtin/sparse-checkout.c +6 -0

+     /* Determine if we need to record the mode; ensure sparse checkout on */
+     record_mode = (set_opts.cone_mode != -1) || !core_apply_sparse_checkout;
+     core_apply_sparse_checkout = 1;
+
+     /* If not specified, use previous definition of cone mode */
+     if (set_opts.cone_mode == -1 && core_apply_sparse_checkout)

I *think* this is supposed go before the core_apply_sparse_checkout = 1; above it (if the intention is to only use the pre-existing cone mode setting when already in a sparse checkout). If not, the core_apply_sparse_checkout part of the condition is redundant and can be removed entirely.

Eek. I had it there originally, then moved it later while doing various changes. This definitely should be later; thanks for catching.

Quoted 34 lines

Quoted 34 lines

builtin/sparse-checkout.c +32 -0

+             set_opts.cone_mode = core_sparse_checkout_cone;
+
+     /* Set cone/non-cone mode appropriately */
+     if (set_opts.cone_mode == 1) {
+             mode = MODE_CONE_PATTERNS;
+             core_sparse_checkout_cone = 1;
+     } else {
+             mode = MODE_ALL_PATTERNS;
+     }
+     if (record_mode && set_config(mode))
+             return 1;
+
+     /* Set sparse-index/non-sparse-index mode if specified */
+     if (set_opts.sparse_index >= 0) {
+             if (set_sparse_index_config(the_repository, set_opts.sparse_index) < 0)
+                     die(_("failed to modify sparse-index config"));
+
+             /* force an index rewrite */
+             repo_read_index(the_repository);
+             the_repository->index->updated_workdir = 1;
+     }
+
+     /*
+      * Cone mode automatically specifies the toplevel directory.  For
+      * non-cone mode, if nothing is specified, manually select just the
+      * top-level directory (much as 'init' would do).
+      */
+     if (!core_sparse_checkout_cone && argc == 0) {
+             argv = default_patterns;
+             argc = 2;
+     }
+
       return modify_pattern_list(argc, argv, set_opts.use_stdin, REPLACE);
  }

builtin/sparse-checkout.c +15 -0

+
 	static struct option builtin_sparse_checkout_set_options[] = {
+		OPT_BOOL(0, "cone", &set_opts.cone_mode,
+			 N_("initialize the sparse-checkout in cone mode")),
+		OPT_BOOL(0, "sparse-index", &set_opts.sparse_index,
+			 N_("toggle the use of a sparse index")),
 		OPT_BOOL(0, "stdin", &set_opts.use_stdin,
 			 N_("read patterns from standard in")),
 		OPT_END(),

@@ -700,11 +709,52 @@ static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
 
 	repo_read_index(the_repository);
 
+	set_opts.cone_mode = -1;
+	set_opts.sparse_index = -1;
+
 	argc = parse_options(argc, argv, prefix,
 			     builtin_sparse_checkout_set_options,
 			     builtin_sparse_checkout_set_usage,
 			     PARSE_OPT_KEEP_UNKNOWN);
 
+	/* Determine if we need to record the mode; ensure sparse checkout on */
+	record_mode = (set_opts.cone_mode != -1) || !core_apply_sparse_checkout;
+	core_apply_sparse_checkout = 1;
+
+	/* If not specified, use previous definition of cone mode */
+	if (set_opts.cone_mode == -1 && core_apply_sparse_checkout)
+		set_opts.cone_mode = core_sparse_checkout_cone;

builtin/sparse-checkout.c +8 -0

+	/* Set sparse-index/non-sparse-index mode if specified */
+	if (set_opts.sparse_index >= 0) {
+		if (set_sparse_index_config(the_repository, set_opts.sparse_index) < 0)
+			die(_("failed to modify sparse-index config"));
+
+		/* force an index rewrite */
+		repo_read_index(the_repository);
+		the_repository->index->updated_workdir = 1;

builtin/sparse-checkout.c static int sparse_checkout_add(int argc, const char **argv, const char *prefix) · line 698

Quoted 4 lines · Elijah Newren via GitGitGadget

static int sparse_checkout_set(int argc, const char **argv, const char *prefix) {

builtin/sparse-checkout.c +2 -0

+     int mode, record_mode;
+     const char *default_patterns[] = {"/*", "!/*/"};

My gut reaction is that this array should be NULL terminated.

Quoted 28 lines

builtin/sparse-checkout.c +15 -0

+
      static struct option builtin_sparse_checkout_set_options[] = {
+             OPT_BOOL(0, "cone", &set_opts.cone_mode,
+                      N_("initialize the sparse-checkout in cone mode")),
+             OPT_BOOL(0, "sparse-index", &set_opts.sparse_index,
+                      N_("toggle the use of a sparse index")),
              OPT_BOOL(0, "stdin", &set_opts.use_stdin,
                       N_("read patterns from standard in")),
              OPT_END(),

@@ -700,11 +709,52 @@ static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
 
      repo_read_index(the_repository);
 
+     set_opts.cone_mode = -1;
+     set_opts.sparse_index = -1;
+
      argc = parse_options(argc, argv, prefix,
                           builtin_sparse_checkout_set_options,
                           builtin_sparse_checkout_set_usage,
                           PARSE_OPT_KEEP_UNKNOWN);
 
+     /* Determine if we need to record the mode; ensure sparse checkout on */
+     record_mode = (set_opts.cone_mode != -1) || !core_apply_sparse_checkout;
+     core_apply_sparse_checkout = 1;
+
+     /* If not specified, use previous definition of cone mode */
+     if (set_opts.cone_mode == -1 && core_apply_sparse_checkout)
+             set_opts.cone_mode = core_sparse_checkout_cone;

builtin/sparse-checkout.c static int sparse_checkout_set(int argc, const char **argv, const char *prefix) · line 736

Quoted 10 lines

builtin/sparse-checkout.c +10 -0

+
+     /* Set cone/non-cone mode appropriately */
+     if (set_opts.cone_mode == 1) {
+             mode = MODE_CONE_PATTERNS;
+             core_sparse_checkout_cone = 1;
+     } else {
+             mode = MODE_ALL_PATTERNS;
+     }
+     if (record_mode && set_config(mode))
+             return 1;

I think it is appropriate to still have the init steps before the modification of the worktree. I did have a brief pause to think about whether the set_config() should be delayed until modify_pattern_list() succeeds.

Quoted 13 lines

builtin/sparse-checkout.c +13 -0

+     /* Set sparse-index/non-sparse-index mode if specified */
+     if (set_opts.sparse_index >= 0) {
+             if (set_sparse_index_config(the_repository, set_opts.sparse_index) < 0)
+                     die(_("failed to modify sparse-index config"));
+
+             /* force an index rewrite */
+             repo_read_index(the_repository);
+             the_repository->index->updated_workdir = 1;
+     }
+
+     /*
+      * Cone mode automatically specifies the toplevel directory.  For
+      * non-cone mode, if nothing is specified, manually select just the

builtin/sparse-checkout.c static int sparse_checkout_set(int argc, const char **argv, const char *prefix) · line 755

Quoted 5 lines

builtin/sparse-checkout.c +5 -0

+      * top-level directory (much as 'init' would do).
+      */
+     if (!core_sparse_checkout_cone && argc == 0) {
+             argv = default_patterns;
+             argc = 2;

Perhaps use 'default_patterns_nr' as a constant near the definition of 'default_patterns' so these numbers are not so far apart?

builtin/sparse-checkout.c static int sparse_checkout_set(int argc, const char **argv, const char *prefix) · line 759

Quoted 5 lines

builtin/sparse-checkout.c +2 -0

+     }
+
      return modify_pattern_list(argc, argv, set_opts.use_stdin, REPLACE);
 }

Thanks,
-Stolee

From: Elijah Newren <[email protected]>

As noted in the previous commit, using separate init and set steps with sparse-checkout result in a number of issues. The previous commit made set able to handle the work of both commands. Update the documentation to reflect this, and mark init as deprecated.

Signed-off-by Elijah Newren <[email protected]>

---
 Documentation/git-sparse-checkout.txt | 92 ++++++++++++++-------------
 1 file changed, 49 insertions(+), 43 deletions(-)

Documentation/git-sparse-checkout.txt +26 -36

index 42056ee9ff9..d22c925ecf8 100644
@@ -30,28 +30,35 @@ COMMANDS
 'list'::
 	Describe the patterns in the sparse-checkout file.
 
-'init'::
-	Enable the `core.sparseCheckout` setting. If the
-	sparse-checkout file does not exist, then populate it with
-	patterns that match every file in the root directory and
-	no other directories, then will remove all directories tracked
-	by Git. Add patterns to the sparse-checkout file to
-	repopulate the working directory.
+'set'::
+	Enable the necessary config settings
+	(extensions.worktreeConfig, core.sparseCheckout,
+	core.sparseCheckoutCone) if they are not already enabled, and
+	write a set of patterns to the sparse-checkout file from the
+	list of arguments following the 'set' subcommand. Update the
+	working directory to match the new patterns.
 +
-To avoid interfering with other worktrees, it first enables the
-`extensions.worktreeConfig` setting and makes sure to set the
-`core.sparseCheckout` setting in the worktree-specific config file.
+When the `--stdin` option is provided, the patterns are read from
+standard in as a newline-delimited list instead of from the arguments.
 +
-When `--cone` is provided, the `core.sparseCheckoutCone` setting is
-also set, allowing for better performance with a limited set of
-patterns (see 'CONE PATTERN SET' below).
+When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
+input list is considered a list of directories instead of
+sparse-checkout patterns.  This allows for better performance with a
+limited set of patterns (see 'CONE PATTERN SET' below).  Note that the
+set command will write patterns to the sparse-checkout file to include
+all files contained in those directories (recursively) as well as
+files that are siblings of ancestor directories. The input format
+matches the output of `git ls-tree --name-only`.  This includes
+interpreting pathnames that begin with a double quote (") as C-style
+quoted strings.
 +
-Use the `--[no-]sparse-index` option to toggle the use of the sparse
-index format. This reduces the size of the index to be more closely
-aligned with your sparse-checkout definition. This can have significant
-performance advantages for commands such as `git status` or `git add`.
-This feature is still experimental. Some commands might be slower with
-a sparse index until they are properly integrated with the feature.
+Use the `--[no-]sparse-index` option to use a sparse index (the
+default is to not use it).  A sparse index reduces the size of the
+index to be more closely aligned with your sparse-checkout
+definition. This can have significant performance advantages for
+commands such as `git status` or `git add`.  This feature is still
+experimental. Some commands might be slower with a sparse index until
+they are properly integrated with the feature.
 +
 **WARNING:** Using a sparse index requires modifying the index in a way
 that is not completely understood by external tools. If you have trouble

@@ -60,23 +67,6 @@ to rewrite your index to not be sparse. Older versions of Git will not
 understand the sparse directory entries index extension and may fail to
 interact with your repository until it is disabled.
 
-'set'::
-	Write a set of patterns to the sparse-checkout file, as given as
-	a list of arguments following the 'set' subcommand. Update the
-	working directory to match the new patterns. Enable the
-	core.sparseCheckout config setting if it is not already enabled.
-+
-When the `--stdin` option is provided, the patterns are read from
-standard in as a newline-delimited list instead of from the arguments.
-+
-When `core.sparseCheckoutCone` is enabled, the input list is considered a
-list of directories instead of sparse-checkout patterns. The command writes
-patterns to the sparse-checkout file to include all files contained in those
-directories (recursively) as well as files that are siblings of ancestor
-directories. The input format matches the output of `git ls-tree --name-only`.
-This includes interpreting pathnames that begin with a double quote (") as
-C-style quoted strings.
-
 'add'::
 	Update the sparse-checkout file to include additional patterns.
 	By default, these patterns are read from the command-line arguments,

@@ -96,9 +86,27 @@ C-style quoted strings.
 

Documentation/git-sparse-checkout.txt +18 -4

++
+Historically, `set` did not used to handle all the necessary config
+settings, which meant that both `init` and `set` had to be called.
+Invoking both meant the `init` step would first remove nearly all
+tracked files (and in cone mode, ignored files too), then the `set`
+step would add many of the tracked files (but not ignored files) back.
+In addition to the lost files, the performance and UI of this
+combination was poor.
++
+Also, historically, `init` would not actually initialize the
+sparse-checkout file if it already existed.  This meant it was
+possible to return to a sparse-checkout without remembering which
+paths to pass to a subsequent 'set' or 'add' command.  However,
+`--cone` and `--sparse-index` options would not be remembered across
+the disable command, so the easy restore of calling a plain `init`
+decreased in utility.
 
 SPARSE CHECKOUT
 ---------------

@@ -117,10 +125,8 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
-To enable the sparse-checkout feature, run `git sparse-checkout init` to
-initialize a simple sparse-checkout file and enable the `core.sparseCheckout`
-config setting. Then, run `git sparse-checkout set` to modify the patterns in
-the sparse-checkout file.
+To enable the sparse-checkout feature, run `git sparse-checkout set` to
+set the patterns you want to use.
 
 To repopulate the working directory with all files, use the
 `git sparse-checkout disable` command.

Documentation/git-sparse-checkout.txt C-style quoted strings. · line 93

Quoted 3 lines · Elijah Newren via GitGitGadget

+'init'::

Documentation/git-sparse-checkout.txt +2 -0

+	Deprecated command that behaves like `set` with no specified paths.
+	May be removed in the future.

I'm on board with deprecating init, but one usage that's not covered by the updated set is toggling the sparse index *without* modifying the patterns. That likely won't matter to most users, but ones that assume git sparse-checkout set --[no-]sparse-index works the same way as git sparse-checkout init --[no-]sparse-index would find themselves losing their existing pattern set.

Maybe --[no-]sparse-index should be added to git sparse-checkout reapply? For changing settings without updating patterns, that probably makes more sense than init or set anyway. If adding that option is outside the scope of what you want to do in this series, though, I'd be happy with a note somewhere in this documentation explicitly noting that set (unlike init) will change your patterns, even when toggling index.sparse (or core.sparseCheckoutCone).

Quoted 97 lines · Elijah Newren via GitGitGadget

From: Elijah Newren <[email protected]>

As noted in the previous commit, using separate init and set steps with sparse-checkout result in a number of issues. The previous commit made set able to handle the work of both commands. Update the documentation to reflect this, and mark init as deprecated.

Signed-off-by Elijah Newren <[email protected]>

---
 Documentation/git-sparse-checkout.txt | 92 ++++++++++++++-------------
 1 file changed, 49 insertions(+), 43 deletions(-)

Documentation/git-sparse-checkout.txt +26 -36

index 42056ee9ff9..d22c925ecf8 100644
@@ -30,28 +30,35 @@ COMMANDS
 'list'::
      Describe the patterns in the sparse-checkout file.
 
-'init'::
-     Enable the `core.sparseCheckout` setting. If the
-     sparse-checkout file does not exist, then populate it with
-     patterns that match every file in the root directory and
-     no other directories, then will remove all directories tracked
-     by Git. Add patterns to the sparse-checkout file to
-     repopulate the working directory.
+'set'::
+     Enable the necessary config settings
+     (extensions.worktreeConfig, core.sparseCheckout,
+     core.sparseCheckoutCone) if they are not already enabled, and
+     write a set of patterns to the sparse-checkout file from the
+     list of arguments following the 'set' subcommand. Update the
+     working directory to match the new patterns.
 +
-To avoid interfering with other worktrees, it first enables the
-`extensions.worktreeConfig` setting and makes sure to set the
-`core.sparseCheckout` setting in the worktree-specific config file.
+When the `--stdin` option is provided, the patterns are read from
+standard in as a newline-delimited list instead of from the arguments.
 +
-When `--cone` is provided, the `core.sparseCheckoutCone` setting is
-also set, allowing for better performance with a limited set of
-patterns (see 'CONE PATTERN SET' below).
+When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
+input list is considered a list of directories instead of
+sparse-checkout patterns.  This allows for better performance with a
+limited set of patterns (see 'CONE PATTERN SET' below).  Note that the
+set command will write patterns to the sparse-checkout file to include
+all files contained in those directories (recursively) as well as
+files that are siblings of ancestor directories. The input format
+matches the output of `git ls-tree --name-only`.  This includes
+interpreting pathnames that begin with a double quote (") as C-style
+quoted strings.
 +
-Use the `--[no-]sparse-index` option to toggle the use of the sparse
-index format. This reduces the size of the index to be more closely
-aligned with your sparse-checkout definition. This can have significant
-performance advantages for commands such as `git status` or `git add`.
-This feature is still experimental. Some commands might be slower with
-a sparse index until they are properly integrated with the feature.
+Use the `--[no-]sparse-index` option to use a sparse index (the
+default is to not use it).  A sparse index reduces the size of the
+index to be more closely aligned with your sparse-checkout
+definition. This can have significant performance advantages for
+commands such as `git status` or `git add`.  This feature is still
+experimental. Some commands might be slower with a sparse index until
+they are properly integrated with the feature.
 +
 **WARNING:** Using a sparse index requires modifying the index in a way
 that is not completely understood by external tools. If you have trouble

@@ -60,23 +67,6 @@ to rewrite your index to not be sparse. Older versions of Git will not
 understand the sparse directory entries index extension and may fail to
 interact with your repository until it is disabled.
 
-'set'::
-     Write a set of patterns to the sparse-checkout file, as given as
-     a list of arguments following the 'set' subcommand. Update the
-     working directory to match the new patterns. Enable the
-     core.sparseCheckout config setting if it is not already enabled.
-+
-When the `--stdin` option is provided, the patterns are read from
-standard in as a newline-delimited list instead of from the arguments.
-+
-When `core.sparseCheckoutCone` is enabled, the input list is considered a
-list of directories instead of sparse-checkout patterns. The command writes
-patterns to the sparse-checkout file to include all files contained in those
-directories (recursively) as well as files that are siblings of ancestor
-directories. The input format matches the output of `git ls-tree --name-only`.
-This includes interpreting pathnames that begin with a double quote (") as
-C-style quoted strings.
-
 'add'::
      Update the sparse-checkout file to include additional patterns.
      By default, these patterns are read from the command-line arguments,

@@ -96,9 +86,27 @@ C-style quoted strings.
 

Documentation/git-sparse-checkout.txt C-style quoted strings. · line 93

Quoted 10 lines

Documentation/git-sparse-checkout.txt +5 -3

 'disable'::
      Disable the `core.sparseCheckout` config setting, and restore the
-     working directory to include all files. Leaves the sparse-checkout
-     file intact so a later 'git sparse-checkout init' command may
-     return the working directory to the same state.
+     working directory to include all files.
+
+'init'::
+     Deprecated command that behaves like `set` with no specified paths.
+     May be removed in the future.

I'm on board with deprecating init, but one usage that's not covered by the updated set is toggling the sparse index *without* modifying the patterns. That likely won't matter to most users, but ones that assume git sparse-checkout set --[no-]sparse-index works the same way as git sparse-checkout init --[no-]sparse-index would find themselves losing their existing pattern set.

Maybe --[no-]sparse-index should be added to git sparse-checkout reapply? For changing settings without updating patterns, that probably makes more sense than init or set anyway. If adding that option is outside the scope of what you want to do in this series, though, I'd be happy with a note somewhere in this documentation explicitly noting that set (unlike init) will change your patterns, even when toggling index.sparse (or core.sparseCheckoutCone).

Quoted 33 lines

Documentation/git-sparse-checkout.txt +18 -4

++
+Historically, `set` did not used to handle all the necessary config
+settings, which meant that both `init` and `set` had to be called.
+Invoking both meant the `init` step would first remove nearly all
+tracked files (and in cone mode, ignored files too), then the `set`
+step would add many of the tracked files (but not ignored files) back.
+In addition to the lost files, the performance and UI of this
+combination was poor.
++
+Also, historically, `init` would not actually initialize the
+sparse-checkout file if it already existed.  This meant it was
+possible to return to a sparse-checkout without remembering which
+paths to pass to a subsequent 'set' or 'add' command.  However,
+`--cone` and `--sparse-index` options would not be remembered across
+the disable command, so the easy restore of calling a plain `init`
+decreased in utility.
 
 SPARSE CHECKOUT
 ---------------

@@ -117,10 +125,8 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
-To enable the sparse-checkout feature, run `git sparse-checkout init` to
-initialize a simple sparse-checkout file and enable the `core.sparseCheckout`
-config setting. Then, run `git sparse-checkout set` to modify the patterns in
-the sparse-checkout file.
+To enable the sparse-checkout feature, run `git sparse-checkout set` to
+set the patterns you want to use.
 
 To repopulate the working directory with all files, use the
 `git sparse-checkout disable` command.

From: Elijah Newren <[email protected]>

As noted in the previous commit, using separate init and set steps with sparse-checkout result in a number of issues. The previous commit made set able to handle the work of both commands. Update the documentation to reflect this, and mark init as deprecated.

Signed-off-by Elijah Newren <[email protected]>

---
  Documentation/git-sparse-checkout.txt | 92 ++++++++++++++-------------
  1 file changed, 49 insertions(+), 43 deletions(-)

Documentation/git-sparse-checkout.txt +30 -39

index 42056ee9ff9..d22c925ecf8 100644
@@ -30,28 +30,35 @@ COMMANDS
  'list'::
  	Describe the patterns in the sparse-checkout file.
 
-'init'::
-	Enable the `core.sparseCheckout` setting. If the
-	sparse-checkout file does not exist, then populate it with
-	patterns that match every file in the root directory and
-	no other directories, then will remove all directories tracked
-	by Git. Add patterns to the sparse-checkout file to
-	repopulate the working directory.
+'set'::
+	Enable the necessary config settings
+	(extensions.worktreeConfig, core.sparseCheckout,
+	core.sparseCheckoutCone) if they are not already enabled, and
+	write a set of patterns to the sparse-checkout file from the
+	list of arguments following the 'set' subcommand. Update the
+	working directory to match the new patterns.
  +
-To avoid interfering with other worktrees, it first enables the
-`extensions.worktreeConfig` setting and makes sure to set the
-`core.sparseCheckout` setting in the worktree-specific config file.
+When the `--stdin` option is provided, the patterns are read from
+standard in as a newline-delimited list instead of from the arguments.
  +
-When `--cone` is provided, the `core.sparseCheckoutCone` setting is
-also set, allowing for better performance with a limited set of
-patterns (see 'CONE PATTERN SET' below).
+When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the
+input list is considered a list of directories instead of
+sparse-checkout patterns.  This allows for better performance with a
+limited set of patterns (see 'CONE PATTERN SET' below).  Note that the
+set command will write patterns to the sparse-checkout file to include
+all files contained in those directories (recursively) as well as
+files that are siblings of ancestor directories. The input format
+matches the output of `git ls-tree --name-only`.  This includes
+interpreting pathnames that begin with a double quote (") as C-style
+quoted strings.
  +
-Use the `--[no-]sparse-index` option to toggle the use of the sparse
-index format. This reduces the size of the index to be more closely
-aligned with your sparse-checkout definition. This can have significant
-performance advantages for commands such as `git status` or `git add`.
-This feature is still experimental. Some commands might be slower with
-a sparse index until they are properly integrated with the feature.
+Use the `--[no-]sparse-index` option to use a sparse index (the
+default is to not use it).  A sparse index reduces the size of the
+index to be more closely aligned with your sparse-checkout
+definition. This can have significant performance advantages for
+commands such as `git status` or `git add`.  This feature is still
+experimental. Some commands might be slower with a sparse index until
+they are properly integrated with the feature.
  +
  **WARNING:** Using a sparse index requires modifying the index in a way
  that is not completely understood by external tools. If you have trouble

@@ -60,23 +67,6 @@ to rewrite your index to not be sparse. Older versions of Git will not
  understand the sparse directory entries index extension and may fail to
  interact with your repository until it is disabled.
 
-'set'::
-	Write a set of patterns to the sparse-checkout file, as given as
-	a list of arguments following the 'set' subcommand. Update the
-	working directory to match the new patterns. Enable the
-	core.sparseCheckout config setting if it is not already enabled.
-+
-When the `--stdin` option is provided, the patterns are read from
-standard in as a newline-delimited list instead of from the arguments.
-+
-When `core.sparseCheckoutCone` is enabled, the input list is considered a
-list of directories instead of sparse-checkout patterns. The command writes
-patterns to the sparse-checkout file to include all files contained in those
-directories (recursively) as well as files that are siblings of ancestor
-directories. The input format matches the output of `git ls-tree --name-only`.
-This includes interpreting pathnames that begin with a double quote (") as
-C-style quoted strings.
-
  'add'::
  	Update the sparse-checkout file to include additional patterns.
  	By default, these patterns are read from the command-line arguments,

@@ -96,9 +86,27 @@ C-style quoted strings.
 
  'disable'::
  	Disable the `core.sparseCheckout` config setting, and restore the
-	working directory to include all files. Leaves the sparse-checkout
-	file intact so a later 'git sparse-checkout init' command may
-	return the working directory to the same state.
+	working directory to include all files.
+
+'init'::
+	Deprecated command that behaves like `set` with no specified paths.

Documentation/git-sparse-checkout.txt +9 -4

+Also, historically, `init` would not actually initialize the
+sparse-checkout file if it already existed.  This meant it was
+possible to return to a sparse-checkout without remembering which
+paths to pass to a subsequent 'set' or 'add' command.  However,
+`--cone` and `--sparse-index` options would not be remembered across
+the disable command, so the easy restore of calling a plain `init`
+decreased in utility.
 
  SPARSE CHECKOUT
  ---------------

@@ -117,10 +125,8 @@ directory, it updates the skip-worktree bits in the index based
  on this file. The files matching the patterns in the file will
  appear in the working directory, and the rest will not.
 
-To enable the sparse-checkout feature, run `git sparse-checkout init` to
-initialize a simple sparse-checkout file and enable the `core.sparseCheckout`
-config setting. Then, run `git sparse-checkout set` to modify the patterns in
-the sparse-checkout file.
+To enable the sparse-checkout feature, run `git sparse-checkout set` to
+set the patterns you want to use.
 
  To repopulate the working directory with all files, use the
  `git sparse-checkout disable` command.

Quoted 2 lines · Elijah Newren via GitGitGadget

From: Elijah Newren <[email protected]>

Documentation/git-sparse-checkout.txt C-style quoted strings. · line 102

Quoted 9 lines

++

Documentation/git-sparse-checkout.txt +8 -0

+Historically, `set` did not used to handle all the necessary config
+settings, which meant that both `init` and `set` had to be called.
+Invoking both meant the `init` step would first remove nearly all
+tracked files (and in cone mode, ignored files too), then the `set`
+step would add many of the tracked files (but not ignored files) back.
+In addition to the lost files, the performance and UI of this
+combination was poor.
++

Super nit: Perhaps update 'set did not used to handle' to 'set did not handle'.

Quoted 4 lines · Lessley Dennington

Quoted 2 lines · Elijah Newren via GitGitGadget

From: Elijah Newren <[email protected]>

...

Quoted 11 lines

Documentation/git-sparse-checkout.txt C-style quoted strings. · line 102

Quoted 9 lines

++

Documentation/git-sparse-checkout.txt +8 -0

+Historically, `set` did not used to handle all the necessary config
+settings, which meant that both `init` and `set` had to be called.
+Invoking both meant the `init` step would first remove nearly all
+tracked files (and in cone mode, ignored files too), then the `set`
+step would add many of the tracked files (but not ignored files) back.
+In addition to the lost files, the performance and UI of this
+combination was poor.
++

Super nit: Perhaps update 'set did not used to handle' to 'set did not handle'.

Yeah, that sounds better. I'll wait a bit longer for other comments, then send a fix for this along with any other needed fixes (even if just included Acks & Reviewed-bys I get). Thanks!

As described at [1], the split of init and set subcommands in sparse-checkout causes multiple issues:

* Poor performance (deleting all tracked files, then later restoring many and maybe even most of them)
* Poor UI (multiple progress bars in wrappers that hide both commands under 1 user-facing command)
* Loss of ignored files under directories the user wanted to keep

This series fixes this bug by providing a single command to switch to a
sparse-checkout: set. It does so by making set able to do the combined work of init and set. It keeps init as-is to give folks time to adapt, but marks it as deprecated.

A quick overview:

* Patches 1-2: small preparatory refactorings

* Patch 3: the crux of the series

* Patches 4-5: documentation modifications (Patch 4 is worth reviewing; it marks init as deprecated -- are others okay with that?)
* Patch 6: trivial modification of git clone --sparse to use git sparse-checkout set rather than git sparse-checkout init.

As described at [1], the split of init and set subcommands in sparse-checkout causes multiple issues:

* Poor performance (deleting all tracked files, then later restoring many and maybe even most of them)
* Poor UI (multiple progress bars in wrappers that hide both commands under 1 user-facing command)
* Loss of ignored files under directories the user wanted to keep

This series fixes this bug by providing a single command to switch to a
sparse-checkout: set. It does so by making set able to do the combined work of init and set. It keeps init as-is to give folks time to adapt, but marks it as deprecated. It also makes reapply able to toggle cone/non-cone mode and sparse-index/non-sparse-index mode.

Changes since v1:

* Inserted new patches 3 & 4 as additional preparatory cleanups
* Took the new mode-toggling work code in sparse_checkout_set from the previous series and moved it into a new function, as a preparatory patch, and made it usable by init/set/reapply
* Also updated reapply to allow mode-toggling
* Updated the documentation as per above
* Various other small items from review comments

As described at [1], the split of init and set subcommands in sparse-checkout causes multiple issues:

* Poor performance (deleting all tracked files, then later restoring many and maybe even most of them)
* Poor UI (multiple progress bars in wrappers that hide both commands under 1 user-facing command)
* Loss of ignored files under directories the user wanted to keep

This series fixes this bug by providing a single command to switch to a
sparse-checkout: set. It does so by making set able to do the combined work of init and set. It keeps init as-is to give folks time to adapt, but marks it as deprecated. It also makes reapply able to toggle cone/non-cone mode and sparse-index/non-sparse-index mode.

Changes since v1:

* Inserted new patches 3 & 4 as additional preparatory cleanups
* Took the new mode-toggling work code in sparse_checkout_set from the previous series and moved it into a new function, as a preparatory patch, and made it usable by init/set/reapply
* Also updated reapply to allow mode-toggling
* Updated the documentation as per above
* Various other small items from review comments

A quick overview:

* Patches 1-4: small preparatory refactorings
* Patch 5: patch adding new function for toggling {cone,sparse-checkout} modes
* Patch 6: the crux of the series; make set able to handle both init and set options
* Patch 7: make reapply also able to do mode toggling
* Patches 8-9: documentation modifications (Patch 4 is worth reviewing; it marks init as deprecated -- are others okay with that?)
* Patch 10: trivial modification of git clone --sparse to use git sparse-checkout set rather than git sparse-checkout init.

[1]
https://lore.kernel.org/git/CABPp-BE8TJ8QGAQWsSGT7S+9Xp-XmApcC9PSw3K=RQOP0rt+PQ@mail.gmail.com/

Elijah Newren (10):
sparse-checkout: pass use_stdin as a parameter instead of as a global
sparse-checkout: break apart functions for sparse_checkout_(set|add)
sparse-checkout: add sanity-checks on initial sparsity state
sparse-checkout: disallow --no-stdin as an argument to set
sparse-checkout: split out code for tweaking settings config
sparse-checkout: enable set to initialize sparse-checkout mode
sparse-checkout: enable reapply to take --[no-]{cone,sparse-index} git-sparse-checkout.txt: update to document init/set/reapply changes
Documentation: clarify/correct a few sparsity related statements
clone: avoid using deprecated sparse-checkout init

 Documentation/git-clone.txt           |   8 +-
 Documentation/git-sparse-checkout.txt | 100 +++++++------
 builtin/clone.c                       |   2 +-
 builtin/sparse-checkout.c             | 196 ++++++++++++++++++++------
 t/t1091-sparse-checkout-builtin.sh    |  10 +-
 5 files changed, 219 insertions(+), 97 deletions(-)

base-commit: abe6bb3905392d5eb6b01fa6e54d7e784e0522aa
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1151%2Fnewren%2Fsparse-checkout-no-init-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1151/newren/sparse-checkout-no-init-v2
Pull-Request: https://github.com/git/git/pull/1151

Range-diff vs v1:

  1:  e41cfe3c1bb =  1:  e41cfe3c1bb sparse-checkout: pass use_stdin as a parameter instead of as a global
  2:  6f7de8f5412 =  2:  6f7de8f5412 sparse-checkout: break apart functions for sparse_checkout_(set|add)
  -:  ----------- >  3:  bade5e52390 sparse-checkout: add sanity-checks on initial sparsity state
  -:  ----------- >  4:  0180bfc4a93 sparse-checkout: disallow --no-stdin as an argument to set
  -:  ----------- >  5:  3f5255eeef9 sparse-checkout: split out code for tweaking settings config
  3:  a90687eb4c1 !  6:  3c640f5bcef sparse-checkout: enable `set` to initialize sparse-checkout mode
     @@ builtin/sparse-checkout.c: static int sparse_checkout_add(int argc, const char *
       
       static char const * const builtin_sparse_checkout_set_usage[] = {
      -	N_("git sparse-checkout set (--stdin | <patterns>)"),
     -+	N_("git sparse-checkout set [--cone] [--[no-]sparse-index] (--stdin | <patterns>)"),
     ++	N_("git sparse-checkout set [--[no-]cone] [--[no-]sparse-index] (--stdin | <patterns>)"),
       	NULL
       };
       
     @@ builtin/sparse-checkout.c: static int sparse_checkout_add(int argc, const char *
       
       static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
       {
     -+	int mode, record_mode;
     -+	const char *default_patterns[] = {"/*", "!/*/"};
     ++	int default_patterns_nr = 2;
     ++	const char *default_patterns[] = {"/*", "!/*/", NULL};
      +
       	static struct option builtin_sparse_checkout_set_options[] = {
      +		OPT_BOOL(0, "cone", &set_opts.cone_mode,
      +			 N_("initialize the sparse-checkout in cone mode")),
      +		OPT_BOOL(0, "sparse-index", &set_opts.sparse_index,
      +			 N_("toggle the use of a sparse index")),
     - 		OPT_BOOL(0, "stdin", &set_opts.use_stdin,
     - 			 N_("read patterns from standard in")),
     - 		OPT_END(),
     + 		OPT_BOOL_F(0, "stdin", &set_opts.use_stdin,
     + 			   N_("read patterns from standard in"),
     + 			   PARSE_OPT_NONEG),
      @@ builtin/sparse-checkout.c: static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
       
       	repo_read_index(the_repository);
     @@ builtin/sparse-checkout.c: static int sparse_checkout_set(int argc, const char *
       			     builtin_sparse_checkout_set_usage,
       			     PARSE_OPT_KEEP_UNKNOWN);
       
     -+	/* Determine if we need to record the mode; ensure sparse checkout on */
     -+	record_mode = (set_opts.cone_mode != -1) || !core_apply_sparse_checkout;
     -+	core_apply_sparse_checkout = 1;
     -+
     -+	/* If not specified, use previous definition of cone mode */
     -+	if (set_opts.cone_mode == -1 && core_apply_sparse_checkout)
     -+		set_opts.cone_mode = core_sparse_checkout_cone;
     -+
     -+	/* Set cone/non-cone mode appropriately */
     -+	if (set_opts.cone_mode == 1) {
     -+		mode = MODE_CONE_PATTERNS;
     -+		core_sparse_checkout_cone = 1;
     -+	} else {
     -+		mode = MODE_ALL_PATTERNS;
     -+	}
     -+	if (record_mode && set_config(mode))
     ++	if (update_modes(&set_opts.cone_mode, &set_opts.sparse_index))
      +		return 1;
      +
     -+	/* Set sparse-index/non-sparse-index mode if specified */
     -+	if (set_opts.sparse_index >= 0) {
     -+		if (set_sparse_index_config(the_repository, set_opts.sparse_index) < 0)
     -+			die(_("failed to modify sparse-index config"));
     -+
     -+		/* force an index rewrite */
     -+		repo_read_index(the_repository);
     -+		the_repository->index->updated_workdir = 1;
     -+	}
     -+
      +	/*
      +	 * Cone mode automatically specifies the toplevel directory.  For
      +	 * non-cone mode, if nothing is specified, manually select just the
     @@ builtin/sparse-checkout.c: static int sparse_checkout_set(int argc, const char *
      +	 */
      +	if (!core_sparse_checkout_cone && argc == 0) {
      +		argv = default_patterns;
     -+		argc = 2;
     ++		argc = default_patterns_nr;
      +	}
      +
       	return modify_pattern_list(argc, argv, set_opts.use_stdin, REPLACE);
  -:  ----------- >  7:  acb10889a1f sparse-checkout: enable reapply to take --[no-]{cone,sparse-index}
  4:  95d3df78b2f !  8:  17b033caf4b git-sparse-checkout.txt: update to document that set handles init

@@ Metadata
Author: Elijah Newren <[email protected]>

## Commit message ##
- git-sparse-checkout.txt: update to document that set handles init
+ git-sparse-checkout.txt: update to document init/set/reapply changes

As noted in the previous commit, using separate init and set steps
- with sparse-checkout result in a number of issues. The previous commit
- made set able to handle the work of both commands. Update the
- documentation to reflect this, and mark init as deprecated.
+ with sparse-checkout result in a number of issues. The previous commits
+ made set able to handle the work of both commands, and enabled reapply
+ to tweak the {cone,sparse-index} settings. Update the documentation to
+ reflect this, and mark init as deprecated.

Signed-off-by Elijah Newren <[email protected]>

@@ Documentation/git-sparse-checkout.txt: COMMANDS
+files that are siblings of ancestor directories. The input format +matches the output of git ls-tree --name-only. This includes +interpreting pathnames that begin with a double quote (") as C-style
-+quoted strings.
++quoted strings. This may become the default in the future; --no-cone ++can be passed to request non-cone mode.
+
-Use the --[no-]sparse-index option to toggle the use of the sparse -index format. This reduces the size of the index to be more closely
@@ Documentation/git-sparse-checkout.txt: to rewrite your index to not be sparse. O
Update the sparse-checkout file to include additional patterns.
By default, these patterns are read from the command-line arguments,
@@ Documentation/git-sparse-checkout.txt: C-style quoted strings.
+ cases, it can make sense to run git sparse-checkout reapply later
+ after cleaning up affected paths (e.g. resolving conflicts, undoing
+ or committing changes, etc.).
+++
++The reapply command can also take --[no-]cone and --[no-]sparse-index ++flags, with the same meaning as the flags from the set command, in order ++to change which sparsity mode you are using without needing to also respecify ++all sparsity paths.

'disable'::
Disable the core.sparseCheckout config setting, and restore the

  5:  9d455f1fb51 =  9:  922a65b4019 Documentation: clarify/correct a few sparsity related statements
  6:  2ad404874ee = 10:  d47b2c88242 clone: avoid using deprecated `sparse-checkout init`

From: Elijah Newren <[email protected]>

Most sparse-checkout subcommands (list, add, reapply, disable) only make sense when already in a sparse state. Add a quick check that will error out early if this is not the case.

Reviewed-by Derrick Stolee <[email protected]>

Reviewed-by Victoria Dye <[email protected]>

Signed-off-by Elijah Newren <[email protected]>

---
 builtin/sparse-checkout.c          | 12 ++++++++++++
 t/t1091-sparse-checkout-builtin.sh | 10 +++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

builtin/sparse-checkout.c +12 -0

index e252b82136e..e9f644ac362 100644
@@ -56,6 +56,9 @@ static int sparse_checkout_list(int argc, const char **argv)
 	char *sparse_filename;
 	int res;
 
+	if (!core_apply_sparse_checkout)
+		die(_("this worktree is not sparse"));
+
 	argc = parse_options(argc, argv, NULL,
 			     builtin_sparse_checkout_list_options,
 			     builtin_sparse_checkout_list_usage, 0);

@@ -671,6 +674,9 @@ static int sparse_checkout_add(int argc, const char **argv, const char *prefix)
 		OPT_END(),
 	};
 
+	if (!core_apply_sparse_checkout)
+		die(_("no sparse-checkout to add to"));
+
 	repo_read_index(the_repository);
 
 	argc = parse_options(argc, argv, prefix,

@@ -719,6 +725,9 @@ static int sparse_checkout_reapply(int argc, const char **argv)
 		OPT_END(),
 	};
 
+	if (!core_apply_sparse_checkout)
+		die(_("must be in a sparse-checkout to reapply sparsity patterns"));
+
 	argc = parse_options(argc, argv, NULL,
 			     builtin_sparse_checkout_reapply_options,
 			     builtin_sparse_checkout_reapply_usage, 0);

@@ -740,6 +749,9 @@ static int sparse_checkout_disable(int argc, const char **argv)
 	struct pattern_list pl;
 	struct strbuf match_all = STRBUF_INIT;
 
+	if (!core_apply_sparse_checkout)
+		die(_("no active sparse-checkout to disable"));
+
 	argc = parse_options(argc, argv, NULL,
 			     builtin_sparse_checkout_disable_options,
 			     builtin_sparse_checkout_disable_usage, 0);

t/t1091-sparse-checkout-builtin.sh +9 -1

index 272ba1b566b..90a281bcf64 100755
@@ -41,7 +41,15 @@ test_expect_success 'setup' '
 	)
 '
 
-test_expect_success 'git sparse-checkout list (empty)' '
+test_expect_success 'git sparse-checkout list (not sparse)' '
+	test_must_fail git -C repo sparse-checkout list >list 2>err &&
+	test_must_be_empty list &&
+	test_i18ngrep "this worktree is not sparse" err
+'
+
+test_expect_success 'git sparse-checkout list (not sparse)' '
+	git -C repo sparse-checkout set &&
+	rm repo/.git/info/sparse-checkout &&
 	git -C repo sparse-checkout list >list 2>err &&
 	test_must_be_empty list &&
 	test_i18ngrep "this worktree is not sparse (sparse-checkout file may not exist)" err

Quoted 6 lines · Elijah Newren via GitGitGadget

From: Elijah Newren <[email protected]>

Most sparse-checkout subcommands (list, add, reapply, disable) only make sense when already in a sparse state. Add a quick check that will error out early if this is not the case.

Quoted 7 lines

Reviewed-by Derrick Stolee <[email protected]>

Reviewed-by Victoria Dye <[email protected]>

Signed-off-by Elijah Newren <[email protected]>

---
 builtin/sparse-checkout.c          | 12 ++++++++++++
 t/t1091-sparse-checkout-builtin.sh | 10 +++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

I won't complain too much but some looks a bit questionable to die on. For example, when asked to "please disable" something that is already disabled, I do not think the user's intention includes "if already disabled, please die"; rather it is "I want the end result to be in the disabled state", isn't it?

I think what is common among the ones that I find questionable to die is that they do not use end-user input from argv. "Please add X to sparsity patterns" may not make much sense when we are not already sparse", unlike "Please disable", for example.

Side note. I suspect that it can be argued that we might just auto-enable sparse state upon the first request to add something, but I personally feel that is dwimming too much, as behaviours of git in normal mode and sparse mode are so different.

So, for the same reason, I think "list" that shows "there is nothing" without an error, when sparse-checkout is not active, would also be perfectly defensible, and some people may find that dying a bit too much in such a situation.

Or does the system work differently between

(A) core_apply_sparse_checkout is true and the sparsity pattern list is empty, and

(B) sparse-checkout is not in effect at all.

If that is the case, please ignore all of the above.

From: Elijah Newren <[email protected]>

Folks may want to switch to or from cone mode, or to or from a sparse-index without changing their sparsity paths. Allow them to do so using the reapply command.

Reviewed-by Derrick Stolee <[email protected]>

Reviewed-by Victoria Dye <[email protected]>

Signed-off-by Elijah Newren <[email protected]>

---
 builtin/sparse-checkout.c | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

builtin/sparse-checkout.c +17 -1

index 1ecdc3ddd5a..9d2a05677c4 100644
@@ -759,13 +759,22 @@ static int sparse_checkout_set(int argc, const char **argv, const char *prefix)
 }
 
 static char const * const builtin_sparse_checkout_reapply_usage[] = {
-	N_("git sparse-checkout reapply"),
+	N_("git sparse-checkout reapply [--[no-]cone] [--[no-]sparse-index] "),
 	NULL
 };
 
+static struct sparse_checkout_reapply_opts {
+	int cone_mode;
+	int sparse_index;
+} reapply_opts;
+
 static int sparse_checkout_reapply(int argc, const char **argv)
 {
 	static struct option builtin_sparse_checkout_reapply_options[] = {
+		OPT_BOOL(0, "cone", &reapply_opts.cone_mode,
+			 N_("initialize the sparse-checkout in cone mode")),
+		OPT_BOOL(0, "sparse-index", &reapply_opts.sparse_index,
+			 N_("toggle the use of a sparse index")),
 		OPT_END(),
 	};
 

@@ -777,6 +786,13 @@ static int sparse_checkout_reapply(int argc, const char **argv)
 			     builtin_sparse_checkout_reapply_usage, 0);
 
 	repo_read_index(the_repository);
+
+	reapply_opts.cone_mode = -1;
+	reapply_opts.sparse_index = -1;
+
+	if (update_modes(&reapply_opts.cone_mode, &reapply_opts.sparse_index))
+		return 1;
+
 	return update_working_directory(NULL);
 }

Quoted 5 lines · Elijah Newren via GitGitGadget

From: Elijah Newren <[email protected]>

Folks may want to switch to or from cone mode, or to or from a sparse-index without changing their sparsity paths. Allow them to do so using the reapply command.

Interesting.

Are there certain pattern that would make sense only in one of the modes but not the other? If there isn't any such pattern, this feature perfectly makes sense, I would think.

If an existing pattern changes its meaning between the old mode and the new mode, that is very much fine---that is what the user wanted to achieve by switching between the modes with "reapply".

Thanks.