Merge pull request #1890 from dscho/explain-better-how-to-develop-thi…

…s-site-with-sparse-checkouts

README: clarify how to start working on this site locally

README.md

@@ -8,7 +8,26 @@ This site is built with [Hugo](https://gohugo.io/) and served via GitHub Pages.
 
 ## Local development setup
 
-It is highly recommended to clone this repository using [`scalar`](https://git-scm.com/docs/scalar); This allows to work only on the parts of the repository relevant to your interests. You can select which directories are checked out using the [`git sparse-checkout add <directory>...`](https://git-scm.com/docs/git-sparse-checkout) command. The relevant directories are:
+> [!NOTE]
+> It is highly recommended to clone this repository using [`scalar`](https://git-scm.com/docs/scalar); This allows to work only on the parts of the repository relevant to your interests. You can select which directories are checked out using the [`git sparse-checkout add <directory>...`](https://git-scm.com/docs/git-sparse-checkout) command. Typically, you will want to start like this:
+
+```ShellSession
+$ scalar clone https://github.com/git/git-scm.com
+$ cd git-scm.com/src
+$ git sparse-checkout set layouts content static assets hugo.yml data script
+
+If your Git installation comes without `scalar`, you can create a sparse, partial clone manually, like this:
+
+```ShellSession
+$ git clone --filter=blob:none --no-checkout https://github.com/git/git-scm.com
+$ cd git-scm.com
+$ git sparse-checkout set layouts content static assets hugo.yml data script
+$ git reset --hard
+```
+> [!NOTE]
+> If you _already_ have a full clone and wish to accelerate development by focusing only on a small subset of the pages, you may want to run the `git sparse-checkout set [...]` command mentioned above.
+
+Here is a detailed list of the relevant directories:
 
 - If you want to test any page rendering using Hugo:
   - layouts/