From 466b38654bba64b0f8a4fe1811906bfc61c9c729 Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Fri, 22 Sep 2023 20:48:12 +0200
Subject: [PATCH] Added blog post on git sparse-checkout

---
 docs/blog/posts/git-sparse-checkout.md | 97 ++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 docs/blog/posts/git-sparse-checkout.md

diff --git a/docs/blog/posts/git-sparse-checkout.md b/docs/blog/posts/git-sparse-checkout.md
new file mode 100644
index 000000000..e5cb8bc2f
--- /dev/null
+++ b/docs/blog/posts/git-sparse-checkout.md
@@ -0,0 +1,97 @@
+---
+date: 2023-09-22
+authors: [squidfunk]
+categories:
+  - Build
+  - Performance
+links:
+  - publishing-your-site.md#with-github-actions
+  - creating-your-site.md#building-your-site
+---
+
+# Using `git sparse-checkout` for faster documentation builds
+
+__Leveraging `git sparse-checkout` in GitHub Actions enabled us to speed up
+documentation builds in our repository, cutting checkout times from 20 to 30
+seconds to just 2 seconds.__
+
+Developing an efficient approach to build documentation in CI workflows is
+essential, especially when working in large repositories with thousands of
+commits, like ours. Of course, we want to build documentation quickly and
+efficiently, ensuring fast and productive workflows. When using the wonderful
+[`git-revision-date-localized`][git-revision-date-localized] plugin to display
+[document contributors] at the bottom of each page, we are required to set
+`fetch-depth: 0`, which resulted in checkout times of 20 to 30 seconds on our
+repository. By leveraging [`git sparse-checkout`][git sparse-checkout] within
+[GitHub Actions], we were able to bring down checkout time to 2 seconds.
+
+  [git sparse-checkout]: https://git-scm.com/docs/git-sparse-checkout
+  [GitHub Actions]: ../../publishing-your-site.md#with-github-actions
+  [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
+  [document contributors]: ../../setup/adding-a-git-repository.md#document-contributors
+
+<!-- more -->
+
+## A Primer
+
+[`git sparse-checkout`][git sparse-checkout] allows you to check out only a
+subset of the files in a repository, making it incredibly useful for large
+repositories where a full checkout takes long and includes many files that are
+not relevant when building documentation.
+
+## GitHub Actions
+
+To enable [`git sparse-checkout`][git sparse-checkout] within [GitHub Actions]
+and ensure that you are only building the documentation that you need, add the
+following lines to your workflow file:
+
+``` yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+    sparse-checkout: |
+      docs
+      includes
+```
+
+[`git sparse-checkout`][git sparse-checkout] always checks out all files
+residing in the repository’s root. This means that regardless of the specified
+paths or directories for sparse checkout, the files located in the root of the
+repository will always be included in the checkout process.
+
+Thus, you only need to specify the directories that are necessary for building
+documentation. In our case, we only need the `docs` and `includes` folders,
+but if you need additional directories, you can just add them to the end of the
+list. A complete example workflow for [GitHub Actions]:
+
+``` yaml hl_lines="13-18"
+name: documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          sparse-checkout: |
+            docs
+            includes
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force
+```
+
+## Conclusion
+
+That's all there is! We're super happy with the results and hope that this will
+help you to speed up your documentation builds in [GitHub Actions] as well. As
+always, feel free to share your thoughts and experiences in the comments below.