mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
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 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:
parent
4e256731d6
commit
ba2f3f58ac
|
@ -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.
|
||||
|
|
Loading…
Reference in a new issue