diff options
author | Junio C Hamano <gitster@pobox.com> | 2020-06-23 01:55:03 +0300 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2020-06-23 01:55:03 +0300 |
commit | 81be89e0bee5bebc478a19b317d8ef4d5f6704a9 (patch) | |
tree | 3da0cc8d7436f63d67f7b79a5660109463659669 /Documentation | |
parent | 9740ef888edadcb12442faf2a690016bb8a2c03c (diff) | |
parent | e7d7c73249bf68be1fd912db045dcb4b6a0b6570 (diff) |
Merge branch 'en/sparse-with-submodule-doc'
The effect of sparse checkout settings on submodules is documented.
* en/sparse-with-submodule-doc:
git-sparse-checkout: clarify interactions with submodules
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/git-sparse-checkout.txt | 30 |
1 files changed, 26 insertions, 4 deletions
diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt index 7c8943af7a..a0eeaeb02e 100644 --- a/Documentation/git-sparse-checkout.txt +++ b/Documentation/git-sparse-checkout.txt @@ -200,10 +200,32 @@ directory. SUBMODULES ---------- -If your repository contains one or more submodules, then those submodules will -appear based on which you initialized with the `git submodule` command. If -your sparse-checkout patterns exclude an initialized submodule, then that -submodule will still appear in your working directory. +If your repository contains one or more submodules, then submodules +are populated based on interactions with the `git submodule` command. +Specifically, `git submodule init -- <path>` will ensure the submodule +at `<path>` is present, while `git submodule deinit [-f] -- <path>` +will remove the files for the submodule at `<path>` (including any +untracked files, uncommitted changes, and unpushed history). Similar +to how sparse-checkout removes files from the working tree but still +leaves entries in the index, deinitialized submodules are removed from +the working directory but still have an entry in the index. + +Since submodules may have unpushed changes or untracked files, +removing them could result in data loss. Thus, changing sparse +inclusion/exclusion rules will not cause an already checked out +submodule to be removed from the working copy. Said another way, just +as `checkout` will not cause submodules to be automatically removed or +initialized even when switching between branches that remove or add +submodules, using `sparse-checkout` to reduce or expand the scope of +"interesting" files will not cause submodules to be automatically +deinitialized or initialized either. + +Further, the above facts mean that there are multiple reasons that +"tracked" files might not be present in the working copy: sparsity +pattern application from sparse-checkout, and submodule initialization +state. Thus, commands like `git grep` that work on tracked files in +the working copy may return results that are limited by either or both +of these restrictions. SEE ALSO |