From f7cf3f8690d28315fafec073939789bbb028db3e Mon Sep 17 00:00:00 2001
From: Tony Metzidis <anthony.metzidis@gmail.com>
Date: Fri, 1 Mar 2024 08:08:39 -0800
Subject: [PATCH] add FAQ/git docs on partial clone to reduce repo size (#126)

* add FAQ/git docs on partial clone to reduce repo size

* consolidate FAQ dir
---
 docs/{ => FAQ}/faqs.md | 11 +++++++++++
 docs/FAQ/git.md        | 41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 rename docs/{ => FAQ}/faqs.md (87%)
 create mode 100644 docs/FAQ/git.md

diff --git a/docs/faqs.md b/docs/FAQ/faqs.md
similarity index 87%
rename from docs/faqs.md
rename to docs/FAQ/faqs.md
index a5c3f00..78d3e28 100644
--- a/docs/faqs.md
+++ b/docs/FAQ/faqs.md
@@ -103,3 +103,14 @@ to "pay" for listing. Here's how:
 
 ^ This will add 1000 credits to your account. But you know, you can't really buy
 anything with it :D
+
+## How Can I Reduce the Size of My Clones
+`forem` clones are currently 1.5G due to old vendor/cache gem's committed to the
+git repo.  Use the steps below to reduce your clone size by 80% -- meaning
+faster _clone_ , deploy , _log_ and less disk usage
+
+```
+# do a partial clone 
+$ git clone --single-branch --branch main --filter=blob:none  git@github.com:forem/forem.git
+```
+see [Advanced Git FAQ](./git/) for more details and docs.
\ No newline at end of file
diff --git a/docs/FAQ/git.md b/docs/FAQ/git.md
new file mode 100644
index 0000000..5668599
--- /dev/null
+++ b/docs/FAQ/git.md
@@ -0,0 +1,41 @@
+# Reducing Git Repo Size
+`forem` clones are currently 1.5G due to old vendor/cache gem's committed to the
+git repo.  Use the steps below to reduce your clone size by 80% -- meaning
+faster _clone_ , deploy , _log_ and less disk usage
+
+**caveat**: This uses a "partial clone" method which fetches a complete working
+tree but avoids cloning older objects from the history  . See 
+[this guide](https://about.gitlab.com/blog/2019/03/13/partial-clone-for-massive-repositories/)
+and the [git docs on partial clones](https://git-scm.com/docs/partial-clone) for a
+more complete command and config overview. 
+
+## Preferred Method for New Clones
+```
+# do a partial clone 
+$ git clone --single-branch --branch main --filter=blob:none  git@github.com:forem/forem.git
+```
+### Test to Confirm the Repo Size
+```
+# your repo will be about 300MB instead of 1500MB
+$ du -sh .
+280M  .
+```
+
+## Existing Clones (for experts)
+You can clean up existing clones, but with this method you will have to rebase
+any changes before submitting PRs. Added work will be required.
+
+#### 1. Update the ref config in `.git/config`
+update `fetch` and `partialCloneFilter`
+```
+[remote "upstream"]
+        url = git@github.com:forem/forem.git
+        fetch = +refs/heads/main:refs/remotes/upstream/main
+        promisor = true
+        partialclonefilter = blob:none
+```
+#### 2. Prune Old Objects Out of your Clone
+Prerequisite: [git-filter-repo](https://github.com/newren/git-filter-repo) needs to be installed
+```
+git filter-repo --force --invert-paths --path-glob 'vendor/cache'
+```