From: "ZheNing Hu via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
"Junio C Hamano" <gitster@pobox.com>,
"Derrick Stolee" <derrickstolee@github.com>,
"Victoria Dye" <vdye@github.com>,
"Elijah Newren" <newren@gmail.com>,
"Nguyễn Thái Ngọc Duy" <pclouds@gmail.com>,
"Martin Ågren" <martin.agren@gmail.com>,
"ZheNing Hu" <adlternative@gmail.com>,
"ZheNing Hu" <adlternative@gmail.com>
Subject: [PATCH v3 1/2] docs: fix sparse-checkout docs link
Date: Sat, 04 Feb 2023 16:16:55 +0000 [thread overview]
Message-ID: <3bdd3ceb16c56587474e110306d473cc0cd7f185.1675527416.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1458.v3.git.1675527416.gitgitgadget@gmail.com>
From: ZheNing Hu <adlternative@gmail.com>
There is a linking error when other documents want to refer to
technical/sparse-checkout.txt, Also, there is something wrong
with the format of the paragraphs in sparse-checkout.txt, which
makes acsiidoc compile errors.
So fix the format of sparse-checkout.txt, and link it in the
Makefile to correct that.
Signed-off-by: ZheNing Hu <adlternative@gmail.com>
---
Documentation/Makefile | 1 +
Documentation/technical/sparse-checkout.txt | 55 +++++++++++++--------
2 files changed, 36 insertions(+), 20 deletions(-)
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9c67c3a1c50..7540da27b8c 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -121,6 +121,7 @@ TECH_DOCS += technical/reftable
TECH_DOCS += technical/scalar
TECH_DOCS += technical/send-pack-pipeline
TECH_DOCS += technical/shallow
+TECH_DOCS += technical/sparse-checkout
TECH_DOCS += technical/trivial-merge
SP_ARTICLES += $(TECH_DOCS)
SP_ARTICLES += technical/api-index
diff --git a/Documentation/technical/sparse-checkout.txt b/Documentation/technical/sparse-checkout.txt
index fa0d01cbda4..15ab4034881 100644
--- a/Documentation/technical/sparse-checkout.txt
+++ b/Documentation/technical/sparse-checkout.txt
@@ -1,3 +1,6 @@
+Sparse Checkout Design Notes
+============================
+
Table of contents:
* Terminology
@@ -14,7 +17,8 @@ Table of contents:
* Reference Emails
-=== Terminology ===
+Terminology
+-----------
cone mode: one of two modes for specifying the desired subset of files
in a sparse-checkout. In cone-mode, the user specifies
@@ -92,7 +96,8 @@ vivifying: When a command restores a tracked file to the working tree (and
file), this is referred to as "vivifying" the file.
-=== Purpose of sparse-checkouts ===
+Purpose of sparse-checkouts
+---------------------------
sparse-checkouts exist to allow users to work with a subset of their
files.
@@ -255,7 +260,8 @@ will perceive the checkout as dense, and commands should thus behave as if
all files are present.
-=== Usecases of primary concern ===
+Usecases of primary concern
+---------------------------
Most of the rest of this document will focus on Behavior A and Behavior
B. Some notes about the other two cases and why we are not focusing on
@@ -300,7 +306,8 @@ Behavior C do not assume they are part of the Behavior B camp and propose
patches that break things for the real Behavior B folks.
-=== Oversimplified mental models ===
+Oversimplified mental models
+----------------------------
An oversimplification of the differences in the above behaviors is:
@@ -313,7 +320,8 @@ An oversimplification of the differences in the above behaviors is:
they can later lazily be populated instead.
-=== Desired behavior ===
+Desired behavior
+----------------
As noted previously, despite the simple idea of just working with a subset
of files, there are a range of different behavioral changes that need to be
@@ -544,7 +552,8 @@ understanding these differences can be beneficial.
* gitk?
-=== Behavior classes ===
+Behavior classes
+----------------
From the above there are a few classes of behavior:
@@ -611,7 +620,8 @@ From the above there are a few classes of behavior:
specification.
-=== Subcommand-dependent defaults ===
+Subcommand-dependent defaults
+-----------------------------
Note that we have different defaults depending on the command for the
desired behavior :
@@ -751,7 +761,8 @@ desired behavior :
implemented.
-=== Sparse specification vs. sparsity patterns ===
+Sparse specification vs. sparsity patterns
+------------------------------------------
In a well-behaved situation, the sparse specification is given directly
by the $GIT_DIR/info/sparse-checkout file. However, it can transiently
@@ -823,7 +834,8 @@ under behavior B index operations are lumped with history and tend to
operate full-tree.
-=== Implementation Questions ===
+Implementation Questions
+------------------------
* Do the options --scope={sparse,all} sound good to others? Are there better
options?
@@ -894,7 +906,8 @@ operate full-tree.
is seamless for them.
-=== Implementation Goals/Plans ===
+Implementation Goals/Plans
+--------------------------
* Get buy-in on this document in general.
@@ -922,15 +935,16 @@ operate full-tree.
commands. IMPORTANT: make sure diff machinery changes don't mess with
format-patch, fast-export, etc.
-=== Known bugs ===
+Known bugs
+----------
This list used to be a lot longer (see e.g. [1,2,3,4,5,6,7,8,9]), but we've
been working on it.
-0. Behavior A is not well supported in Git. (Behavior B didn't used to
- be either, but was the easier of the two to implement.)
+. Behavior A is not well supported in Git. (Behavior B didn't used to
+be either, but was the easier of the two to implement.)
-1. am and apply:
+. am and apply:
apply, without `--index` or `--cached`, relies on files being present
in the working copy, and also writes to them unconditionally. As
@@ -950,7 +964,7 @@ been working on it.
files and then complain that those vivified files would be
overwritten by merge.
-2. reset --hard:
+. reset --hard:
reset --hard provides confusing error message (works correctly, but
misleads the user into believing it didn't):
@@ -973,13 +987,13 @@ been working on it.
`git reset --hard` DID remove addme from the index and the working tree, contrary
to the error message, but in line with how reset --hard should behave.
-3. read-tree
+. read-tree
`read-tree` doesn't apply the 'SKIP_WORKTREE' bit to *any* of the
entries it reads into the index, resulting in all your files suddenly
appearing to be "deleted".
-4. Checkout, restore:
+. Checkout, restore:
These command do not handle path & revision arguments appropriately:
@@ -1032,7 +1046,7 @@ been working on it.
S tracked
H tracked-but-maybe-skipped
-5. checkout and restore --staged, continued:
+. checkout and restore --staged, continued:
These commands do not correctly scope operations to the sparse
specification, and make it worse by not setting important SKIP_WORKTREE
@@ -1048,11 +1062,12 @@ been working on it.
the sparse specification, but then it will be important to set the
SKIP_WORKTREE bits appropriately.
-6. Performance issues; see:
+. Performance issues; see:
https://lore.kernel.org/git/CABPp-BEkJQoKZsQGCYioyga_uoDQ6iBeW+FKr8JhyuuTMK1RDw@mail.gmail.com/
-=== Reference Emails ===
+Reference Emails
+----------------
Emails that detail various bugs we've had in sparse-checkout:
--
gitgitgadget
next prev parent reply other threads:[~2023-02-04 16:17 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-01-11 15:42 [PATCH] ls-files: add %(skipworktree) atom to format option ZheNing Hu via GitGitGadget
2023-01-12 10:00 ` Elijah Newren
2023-01-12 19:58 ` Junio C Hamano
2023-01-13 4:43 ` Elijah Newren
2023-01-13 17:07 ` ZheNing Hu
2023-01-13 16:50 ` ZheNing Hu
2023-01-14 3:00 ` Elijah Newren
2023-01-12 10:07 ` Ævar Arnfjörð Bjarmason
2023-01-13 16:59 ` ZheNing Hu
2023-01-19 17:34 ` [PATCH v2 0/2] " ZheNing Hu via GitGitGadget
2023-01-19 17:34 ` [PATCH v2 1/2] docs: fix sparse-checkout docs link ZheNing Hu via GitGitGadget
2023-01-20 5:12 ` Elijah Newren
2023-01-20 9:35 ` Martin Ågren
2023-01-23 15:16 ` ZheNing Hu
2023-01-23 15:15 ` ZheNing Hu
2023-01-19 17:34 ` [PATCH v2 2/2] ls-files: add %(skipworktree) atom to format option ZheNing Hu via GitGitGadget
2023-01-20 5:30 ` Elijah Newren
2023-01-20 16:34 ` Junio C Hamano
2023-01-23 15:35 ` ZheNing Hu
2023-01-23 22:39 ` Junio C Hamano
2023-01-23 15:33 ` ZheNing Hu
2023-02-04 16:16 ` [PATCH v3 0/2] " ZheNing Hu via GitGitGadget
2023-02-04 16:16 ` ZheNing Hu via GitGitGadget [this message]
2023-02-04 16:16 ` [PATCH v3 2/2] " ZheNing Hu via GitGitGadget
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 \
--in-reply-to=3bdd3ceb16c56587474e110306d473cc0cd7f185.1675527416.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=adlternative@gmail.com \
--cc=avarab@gmail.com \
--cc=derrickstolee@github.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=martin.agren@gmail.com \
--cc=newren@gmail.com \
--cc=pclouds@gmail.com \
--cc=vdye@github.com \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public 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).