From 151a4ade62880b7d480e5b34df1db9bcc9fedb15 Mon Sep 17 00:00:00 2001
From: stevenyomi <95685115+stevenyomi@users.noreply.github.com>
Date: Fri, 28 Oct 2022 21:52:34 +0800
Subject: [PATCH] Update sparse checkout guide (#14009)

---
 CONTRIBUTING.md | 56 ++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 51 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6ee7fcf43..08cfcd5c2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -57,15 +57,47 @@ Some alternative steps can be followed to ignore "repo" branch and skip unrelate
 <details><summary>Steps</summary>
 
 1. Make sure to delete "repo" branch in your fork. You may also want to disable Actions in the repo settings.
+
+    **Also make sure you are using the latest version of Git as many commands used here are pretty new.**
+
 2. Do a partial clone.
     ```bash
-    git clone --filter=blob:none --no-checkout <fork-repo-url>
+    git clone --filter=blob:none --sparse <fork-repo-url>
     cd tachiyomi-extensions/
     ```
 3. Configure sparse checkout.
+
+    There are two modes of pattern matching. The default is cone (🔺) mode.
+    Cone mode enables significantly faster pattern matching for big monorepos
+    and the sparse index feature to make Git commands more responsive.
+    In this mode, you can only filter by file path, which is less flexible
+    and might require more work when the project structure changes.
+
+    You can skip this code block to use legacy mode if you want easier filters.
+    It won't be much slower as the repo doesn't have that many files.
+
+    To enable cone mode together with sparse index, follow these steps:
+
+    ```bash
+    git sparse-checkout set --cone --sparse-index
+    # add project folders
+    git sparse-checkout add .run buildSrc core gradle lib multisrc/src/main/java/generator
+    # add a single source
+    git sparse-checkout add src/<lang>/<source>
+    # add a multisrc theme
+    git sparse-checkout add multisrc/src/main/java/eu/kanade/tachiyomi/multisrc/<source>
+    git sparse-checkout add multisrc/overrides/<source>
+    ```
+
+    To remove a source, open `.git/info/sparse-checkout` and delete the exact
+    lines you typed when adding it. Don't touch the other auto-generated lines
+    unless you fully understand how cone mode works, or you might break it.
+
+    To use the legacy non-cone mode, follow these steps:
+
     ```bash
     # enable sparse checkout
-    git sparse-checkout set
+    git sparse-checkout set --no-cone
     # edit sparse checkout filter
     vim .git/info/sparse-checkout
     # alternatively, if you have VS Code installed
@@ -85,6 +117,10 @@ Some alternative steps can be followed to ignore "repo" branch and skip unrelate
     # or type the source name directly
     <source>
     ```
+
+    Explanation: the rules are like `gitignore`. We first exclude all sources
+    while retaining project folders, then add the needed sources back manually.
+
 4. Configure remotes.
     ```bash
     # add upstream
@@ -100,8 +136,6 @@ Some alternative steps can be followed to ignore "repo" branch and skip unrelate
     git remote update
     # track master of upstream instead of fork
     git branch master -u upstream/master
-    # checkout
-    git switch master
     ```
 5. Useful configurations. (optional)
     ```bash
@@ -109,10 +143,22 @@ Some alternative steps can be followed to ignore "repo" branch and skip unrelate
     git config remote.origin.prune true
     # fast-forward only when pulling master branch
     git config pull.ff only
+    # Add an alias to sync master branch without fetching useless blobs.
+    # If you run `git pull` to fast-forward in a blobless clone like this,
+    # all blobs (files) in the new commits are still fetched regardless of
+    # sparse rules, which makes the local repo accumulate unused files.
+    # Use `git sync-master` to avoid this. Be careful if you have changes
+    # on master branch, which is not a good practice.
+    git config alias.sync-master '!git switch master && git fetch upstream && git reset --keep FETCH_HEAD'
     ```
 6. Later, if you change the sparse checkout filter, run `git sparse-checkout reapply`.
 
-Read more on [partial clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/), [sparse checkout](https://github.blog/2020-01-17-bring-your-monorepo-down-to-size-with-sparse-checkout/) and [negative refspecs](https://github.blog/2020-10-19-git-2-29-released/#user-content-negative-refspecs).
+Read more on
+[Git's object model](https://github.blog/2020-12-17-commits-are-snapshots-not-diffs/),
+[partial clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/),
+[sparse checkout](https://github.blog/2020-01-17-bring-your-monorepo-down-to-size-with-sparse-checkout/),
+[sparse index](https://github.blog/2021-11-10-make-your-monorepo-feel-small-with-gits-sparse-index/),
+and [negative refspecs](https://github.blog/2020-10-19-git-2-29-released/#user-content-negative-refspecs).
 </details>
 
 ## Getting help