Hi,
On Wed, Nov 8, 2023 at 3:38 AM Josef Wolf <jw@xxxxxxxxxxxxx> wrote:
>
> Thanks for the reply, Elijah!
>
[...]
> > > Error message suggests, there already exists a file named "new-filename". This
> > > is not true at all. There is no file named "new-filename" in the entire
> > > repository. Not in any directory of any branch.
> >
> > You are correct; the wording of the error message here is suboptimal
> > and seems to have been focused more on the git-add case (the error
> > message is shared by git-add, git-mv, and git-rm). Thanks for
> > pointing it out! We could improve that wording, perhaps with
> > something like:
> >
> > The following paths and/or pathspecs match paths that are
> > outside of your sparse-checkout definition, so will not be
> > updated:
> >
> > Which is still slightly slanted towards git-add and git-rm cases, but
> > I hope it works better than the current message. Thoughts?
>
> Yes, the wording was pretty much confusing me, since i could not find a file
> named "new-file" anywhere in the repo.
>
>
> There are more things confusing concerning sparse mode:
Sweet, thanks for taking the time to write these up. It certainly
helps confirm some of the directions we picked and changes we made to
make things a little clearer, and helps us continue working in that
direction. Some comments below on individual points...
> - It is not clear from git-sparse-checkout(1) when changes to
> $GIT_DIR/info/sparse-checkout are catched up. In my case: would it be enough
> to add the new pathname just before git-mv or would a fresh git-checkout be
> needed after modifying $GIT_DIR/info/sparse-checkout? You have clarified
> this in your response, but shouldn't this be clear from the manpage?
I believe at least part of this confusion is due to using the old
style of handling sparse checkouts; namely, by actually editing
$GIT_DIR/info/sparse-checkout. We have taken pains to guide people
away from that workflow, because it is both more work, and leads to
more confusion. If you instead do a
git sparse-checkout set --no-cone <pattern1> <pattern2> ... <patternN>
or a
git sparse-checkout add <another-pattern>
then the sparse-checkout command handles populating the
$GIT_DIR/info/sparse-checkout for you as well as any needed checkout,
meaning that there isn't a "catch up" step as there traditionally was.
And it makes it a bit clearer that if you add some path to your
sparse-checkout, then your sparse-checkout is ready to handle the
additional path right away.
> - git-sparse-checkout(1) refers to "skip-worktree bit". This concept is
> potentially not very familiar to the average git user which uses mostly
> porcelain. Thus, edge cases remain to be unclear.
I totally agree that the "skip-worktree bit" is something we should
avoid exposing to the user. I called it out previously:
"""
Most sparse checkout users are unaware of this implementation
detail, and the term should generally be avoided in user-facing
descriptions and command flags. Unfortunately, prior to the
`sparse-checkout` subcommand this low-level detail was exposed,
and as of time of writing, is still exposed in various places.
"""
However, we should also note that you reported using v2.34.1, which is
really quite old. The current git-sparse-checkout(1) has been almost
completely overhauled in the meantime:
$ git show v2.34.1:Documentation/git-sparse-checkout.txt | wc -l
263
$ git diff --stat v2.34.1 v2.43.0-rc1 -- Documentation/git-sparse-checkout.txt
Documentation/git-sparse-checkout.txt | 446 +++++++++++++++++++++++++---------
1 file changed, 333 insertions(+), 113 deletions(-)
And, in particular, "skip-worktree" doesn't appear until quite a bit
later in the file, and then only appears in a section labelled
"INTERNALS -- SPARSE CHECKOUT".
> - The pathspecs refers to .gitignore (which by itself is not very clear). But
> there are differences:
> 1. giignore is relative to containing directoy, which don't seem to make
> much sense for sparse mode
> 2. sparse specs are the opposite of gitignore, which seems to have different
> meaning in some edge-cases.
Yeah, copying .gitignore syntax and merely referring to the gitignore
manual for specification of the patterns was a huge design mistake.
I've hated it since the beginning. The internals actually managed to
make it *even more* confusing for quite some time as it referred to
everything as "excludes", regardless of whether used for gitignore or
sparse-checkout. But yeah, these and other inherent problems with
non-cone mode are called out in the "INTERNALS -- NON-CONE PROBLEMS"
section of the manual, and is a big piece of why we recommend users
migrate away from it if possible.
> - For cone, it is not clear how the two "accepted patterns" look like what the
> semantics are.
Yeah, it is a bit complex, and I advocated for just using a different
control file for cone mode to help us step away from the blight of
$GIT_DIR/info/sparse-checkout and its inherent tie to gitignore. I
didn't win that one.
However, why does it actually matter? You shouldn't be bothering with
the patterns or editing the $GIT_DIR/info/sparse-checkout file for
cone mode. You just
git sparse-checkout set <directory1> <directory2> ... <directoryN>
and then the file will be set up for you.
> I understand that specifying a directory adds siblings
> recursively. But what does the "Parent" mode mean exactly and when/how is
> this recognized? I guess, this is just a mis-namer? IMHO, parent of /a/b/c would
> be /a/b and not /a/b/c/* (as git-sparse-chekout(1) suggests).
No, /a/b/c/* is not the parent, that's the portion that says that all
things below a/b/c (i.e. all descendant files) should be included.
The parent parts would be where it adds /a/b/ and /a/ as patterns to
ensure things directly under a/ and directly under a/b/ are included.
I think the newer version of the manual might explain this a little
better, but honestly, attempting to explain it is a losing battle.
Users shouldn't read or edit the sparse-checkout file in cone mode.
We let them, but we strongly recommend against it. Just pass the
actual directory names to `git sparse-checkout {set,add}` and let it
take care of the patterns for you.
