undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-sparse-checkout.txt: update to document init/set/reapply changes

Browse Source 
As noted in the previous commit, using separate `init` and `set` steps
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.

Reviewed-by: Derrick Stolee <dstolee@microsoft.com>
Reviewed-by: Victoria Dye <vdye@github.com>
Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Elijah Newren 2021-12-14 04:09:10 +00:00 committed by Junio C Hamano
parent 4e256731d6
commit ba2f3f58ac
1 changed files with 55 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
Documentation/git-sparse-checkout.txt
View File

@ -30,28 +30,36 @@ 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. 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
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 +68,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,
@ -93,12 +84,35 @@ 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
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.
+
Historically, `set` did not 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 +131,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.