From: "Ævar Arnfjörð Bjarmason" <firstname.lastname@example.org> To: Elijah Newren via GitGitGadget <email@example.com> Cc: firstname.lastname@example.org, Victoria Dye <email@example.com>, Derrick Stolee <firstname.lastname@example.org>, Lessley Dennington <email@example.com>, Elijah Newren <firstname.lastname@example.org> Subject: Re: [PATCH v2 4/5] Update documentation related to sparsity and the skip-worktree bit Date: Wed, 16 Feb 2022 10:15:25 +0100 [thread overview] Message-ID: <email@example.com> (raw) In-Reply-To: <firstname.lastname@example.org> On Fri, Jan 14 2022, Elijah Newren via GitGitGadget wrote: > From: Elijah Newren <email@example.com> > > Make several small updates, to address a few documentation issues > I spotted: > * sparse-checkout focused on "patterns" even though the inputs (and > outputs in the case of `list`) are directories in cone-mode > * The description section of the sparse-checkout documentation > was a bit sparse (no pun intended), and focused more on internal > mechanics rather than end user usage. This made sense in the > early days when the command was even more experimental, but let's > adjust a bit to try to make it more approachable to end users who > may want to consider using it. Keep the scary backward > compatibility warning, though; we're still hard at work trying to > fix up commands to behave reasonably in sparse checkouts. > * both read-tree and update-index tried to describe how to use the > skip-worktree bit, but both predated the sparse-checkout command. > The sparse-checkout command is a far easier mechanism to use and > for users trying to reduce the size of their working tree, we > should recommend users to look at it instead. > * The update-index documentation pointed out that assume-unchanged > and skip-worktree sounded similar but had different purposes. > However, it made no attempt to explain the differences, only to > point out that they were different. Explain the differences. > * The update-index documentation focused much more on (internal?) > implementation details than on end-user usage. Try to explain > its purpose better for users of update-index, rather than > fellow developers trying to work with the SKIP_WORKTREE bit. > * Clarify that when core.sparseCheckout=true, we treat a file's > presence in the working tree as being an override to the > SKIP_WORKTREE bit (i.e. in sparse checkouts when the file is > present we ignore the SKIP_WORKTREE bit). > > Note that this commit, like many touching documentation, is best viewed > with the `--color-words` option to diff/log. > > Signed-off-by: Elijah Newren <firstname.lastname@example.org> > --- > Documentation/git-read-tree.txt | 12 +++-- > Documentation/git-sparse-checkout.txt | 76 ++++++++++++++++----------- > Documentation/git-update-index.txt | 57 +++++++++++++++----- > 3 files changed, 98 insertions(+), 47 deletions(-) > > diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt > index 8c3aceb8324..99bb387134d 100644 > --- a/Documentation/git-read-tree.txt > +++ b/Documentation/git-read-tree.txt > @@ -375,9 +375,14 @@ have finished your work-in-progress), attempt the merge again. > SPARSE CHECKOUT > --------------- > > +Note: The `update-index` and `read-tree` primitives for supporting the > +skip-worktree bit predated the introduction of > +linkgit:git-sparse-checkout. Users are encouraged to use > +`sparse-checkout` in preference to these low-level primitives. I was honestly a bit confused about whether we were really referring to the git-update-index and git-read-tree commands here, or some sparse-checkout (re-)usage of the same as "primitives", but reading it again & the commit message we're just talking about the commands here. So this really just wants to assure readers that they're advised to use the shiny porcelain command instead of the plumbing. I think we should refer to these as e.g. "linkgit:git-update-index" not "`update-index`" here, and call them e.g. "plumbing commands" instead of "primitives" here, which will address that (the reader wonders "what's a primitive?"). > -Initialize and modify the sparse-checkout configuration, which reduces > -the checkout to a set of paths given by a list of patterns. > +This command is used to create sparse checkouts, which means that it > +changes the working tree from having all tracked files present, to only > +have a subset of them. It can also switch which subset of files are > +present, or undo and go back to having all tracked files present in the > +working copy. In terms of prose I think it's preferred to keep matter-of-fact "Slices and dices apples, making them easier to eat" instead of "This command slices and dices apples, which means that it's easier to eat them". I've forgotten what the linguisting term for that is, but it's more consistent with our docs, and makes for easier reading. > +The subset of files is chosen by providing a list of directories in > +cone mode (which is recommended), or by providing a list of patterns > +in non-cone mode. As someone with light familiarity with sparse-checkout: I'm still not sure if this is telling me that it's preferred to list directories v.s. patterns, or if it's telling me it's better to operate in "cone mode" v.s. "non-cone mode", or some combination of the two. IOW I think peeling out that "(which is recommended)" and making it clearly refer to which (or both?) of the two we're talking about would be much better. > +When in a sparse-checkout, other Git commands behave a bit differently. > +For example, switching branches will not update paths outside the > +sparse-checkout directories/patterns, and `git commit -a` will not record > +paths outside the sparse-checkout directories/patterns as deleted. (I didn't read through the rest in any detail)
next prev parent reply other threads:[~2022-02-16 9:24 UTC|newest] Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top 2022-01-13 16:43 [PATCH 0/5] Remove the present-despite-SKIP_WORKTREE class of bugs (for sparse-checkouts) Elijah Newren via GitGitGadget 2022-01-13 16:43 ` [PATCH 1/5] t1011: add testcase demonstrating accidental loss of user modifications Elijah Newren via GitGitGadget 2022-01-13 16:43 ` [PATCH 2/5] unpack-trees: fix accidental loss of user changes Elijah Newren via GitGitGadget 2022-01-13 16:43 ` [PATCH 3/5] repo_read_index: clear SKIP_WORKTREE bit from files present in worktree Elijah Newren via GitGitGadget 2022-01-13 16:43 ` [PATCH 4/5] Update documentation related to sparsity and the skip-worktree bit Elijah Newren via GitGitGadget 2022-01-13 16:43 ` [PATCH 5/5] Accelerate clear_skip_worktree_from_present_files() by caching Elijah Newren via GitGitGadget 2022-01-13 23:35 ` Elijah Newren 2022-01-14 15:59 ` [PATCH v2 0/5] Remove the present-despite-SKIP_WORKTREE class of bugs (for sparse-checkouts) Elijah Newren via GitGitGadget 2022-01-14 15:59 ` [PATCH v2 1/5] t1011: add testcase demonstrating accidental loss of user modifications Elijah Newren via GitGitGadget 2022-02-16 8:51 ` Ævar Arnfjörð Bjarmason 2022-02-16 16:02 ` Elijah Newren 2022-01-14 15:59 ` [PATCH v2 2/5] unpack-trees: fix accidental loss of user changes Elijah Newren via GitGitGadget 2022-01-14 15:59 ` [PATCH v2 3/5] repo_read_index: clear SKIP_WORKTREE bit from files present in worktree Elijah Newren via GitGitGadget 2022-02-16 8:57 ` Ævar Arnfjörð Bjarmason 2022-02-16 16:08 ` Elijah Newren 2022-02-19 1:06 ` Jonathan Nieder 2022-02-19 16:42 ` Elijah Newren 2022-02-19 18:14 ` Jonathan Nieder 2022-02-20 5:28 ` Elijah Newren 2022-02-20 16:56 ` Derrick Stolee 2022-02-22 23:17 ` Jonathan Nieder 2022-01-14 15:59 ` [PATCH v2 4/5] Update documentation related to sparsity and the skip-worktree bit Elijah Newren via GitGitGadget 2022-02-16 9:15 ` Ævar Arnfjörð Bjarmason [this message] 2022-02-16 16:21 ` Elijah Newren 2022-01-14 15:59 ` [PATCH v2 5/5] Accelerate clear_skip_worktree_from_present_files() by caching Elijah Newren via GitGitGadget 2022-01-15 1:39 ` Victoria Dye 2022-02-16 9:32 ` Ævar Arnfjörð Bjarmason 2022-02-16 16:30 ` Elijah Newren 2022-02-17 4:40 ` Elijah Newren 2022-01-15 1:51 ` [PATCH v2 0/5] Remove the present-despite-SKIP_WORKTREE class of bugs (for sparse-checkouts) Victoria Dye
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style List information: http://vger.kernel.org/majordomo-info.html * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [PATCH v2 4/5] Update documentation related to sparsity and the skip-worktree bit' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Code repositories for project(s) associated with this inbox: https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).