[v2,7/9] git-sparse-checkout.txt: flesh out non-cone mode pattern discussion a bit

Commit Message

Elijah Newren March 12, 2022, 3:11 a.m. UTC

From: Elijah Newren <[e-mail]>

Signed-off-by: Elijah Newren <[e-mail]>
---
 Documentation/git-sparse-checkout.txt | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

Comments

Junio C Hamano March 14, 2022, 8:57 p.m. UTC | #1

"Elijah Newren via GitGitGadget" <[e-mail]> writes:

>  INTERNALS -- FULL PATTERN SET
>  -----------------------------
>  
> -By default, the sparse-checkout file uses the same syntax as `.gitignore`
> -files.
> -
> -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
> -files are included, you can also specify what files are _not_ included,
> -using negative patterns. For example, to remove the file `unwanted`:
> +As noted above, the sparse-checkout file uses the same syntax as
> +`.gitignore` files; see linkgit:gitignore[5] for details.  Here,

Here, following the suggestion to fix the early part of "Cone mode
patterns" section, move the "it is more flexible but requires more
cycles to process" you had there to replace the "As noted above".

Elijah Newren April 22, 2022, 2:30 a.m. UTC | #2

On Mon, Mar 14, 2022 at 1:57 PM Junio C Hamano <[e-mail]> wrote:
>
> "Elijah Newren via GitGitGadget" <[e-mail]> writes:
>
> >  INTERNALS -- FULL PATTERN SET
> >  -----------------------------
> >
> > -By default, the sparse-checkout file uses the same syntax as `.gitignore`
> > -files.
> > -
> > -While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
> > -files are included, you can also specify what files are _not_ included,
> > -using negative patterns. For example, to remove the file `unwanted`:
> > +As noted above, the sparse-checkout file uses the same syntax as
> > +`.gitignore` files; see linkgit:gitignore[5] for details.  Here,
>
> Here, following the suggestion to fix the early part of "Cone mode
> patterns" section, move the "it is more flexible but requires more
> cycles to process" you had there to replace the "As noted above".

Makes sense; I'll restructure it with this and some of the other
modifications you mentioned earlier to simplify the cone mode
discussion.

Patch

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index dddf5ac6942..ae6ea8b48b0 100644
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -274,12 +274,23 @@  manually to ensure Git can behave optimally.
 INTERNALS -- FULL PATTERN SET
 -----------------------------
 
-By default, the sparse-checkout file uses the same syntax as `.gitignore`
-files.
-
-While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
-files are included, you can also specify what files are _not_ included,
-using negative patterns. For example, to remove the file `unwanted`:
+As noted above, the sparse-checkout file uses the same syntax as
+`.gitignore` files; see linkgit:gitignore[5] for details.  Here,
+though, the patterns are usually being used to select which files to
+include rather than which files to exclude.  (However, it can get a
+bit confusing since gitignore-style patterns have negations defined by
+patterns which begin with a '!', so you can also select files to _not_
+include.)
+
+For example, to select everything, and then to remove the file
+`unwanted` (so that every file will appear in your working tree except
+the file named `unwanted`):
+
+    git sparse-checkout set --no-cone '/*' '!unwanted'
+
+These patterns are just placed into the
+`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file
+at this point would be
 
 ----------------
 /*