git-sparse-checkout.txt: add a new EXAMPLES section
Since many users like to learn from examples, provide a section in the manual with example commands that would be used and a brief explanation of what each does. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Elijah Newren committed
Apr 22, 2022 at 02:32 UTC
5d295dc39606990688766916a2bcf93dc0efb61b
1 file changed
+37
-6
Documentation/git-sparse-checkout.txt
+37
-6
@@ -136,6 +136,43 @@ paths to pass to a subsequent 'set' or 'add' command. However,
136
the disable command, so the easy restore of calling a plain `init`
137
decreased in utility.
138
139
+EXAMPLES
140
+--------
141
+`git sparse-checkout set MY/DIR1 SUB/DIR2`::
142
+
143
+ Change to a sparse checkout with all files (at any depth) under
144
+ MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all
145
+ files immediately under MY/ and SUB/ and the toplevel
146
+ directory). If already in a sparse checkout, change which files
147
+ are present in the working copy to this new selection. Note
148
+ that this command will also delete all ignored files in any
149
+ directory that no longer has either tracked or
150
+ non-ignored-untracked files present.
151
+
152
+`git sparse-checkout disable`::
153
+
154
+ Repopulate the working directory with all files, disabling sparse
155
+ checkouts.
156
+
157
+`git sparse-checkout add SOME/DIR/ECTORY`::
158
+
159
+ Add all files under SOME/DIR/ECTORY/ (at any depth) to the
160
+ sparse checkout, as well as all files immediately under
161
+ SOME/DIR/ and immediately under SOME/. Must already be in a
162
+ sparse checkout before using this command.
163
+
164
+`git sparse-checkout reapply`::
165
+
166
+ It is possible for commands to update the working tree in a
167
+ way that does not respect the selected sparsity directories.
168
+ This can come from tools external to Git writing files, or
169
+ even affect Git commands because of either special cases (such
170
+ as hitting conflicts when merging/rebasing), or because some
171
+ commands didn't fully support sparse checkouts (e.g. the old
172
+ `recursive` merge backend had only limited support). This
173
+ command reapplies the existing sparse directory specifications
174
+ to make the working directory match.
175
+
176
INTERNALS -- SPARSE CHECKOUT
177
----------------------------
178
@@ -154,12 +191,6 @@ directory, it updates the skip-worktree bits in the index based
191
on this file. The files matching the patterns in the file will
192
appear in the working directory, and the rest will not.
193
157
-To enable the sparse-checkout feature, run `git sparse-checkout set` to
158
-set the patterns you want to use.
159
-
160
-To repopulate the working directory with all files, use the
161
-`git sparse-checkout disable` command.
162
-
194
195
INTERNALS -- CONE PATTERN SET
196
-----------------------------