From 80a664bc23f6412c789181098a104dca6f2ad950 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 28 Aug 2026 07:57:34 +0300
Subject: [PATCH] =?UTF-8?q?docs:=20=D1=80=D0=B5=D0=BA=D0=BE=D0=BC=D0=B5?=
 =?UTF-8?q?=D0=BD=D0=B4=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20blobless-=D0=BA?=
 =?UTF-8?q?=D0=BB=D0=BE=D0=BD=20=D0=B2=D0=BC=D0=B5=D1=81=D1=82=D0=BE=20?=
 =?UTF-8?q?=D0=BF=D0=BE=D0=BB=D0=BD=D0=BE=D0=B3=D0=BE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Замерено, не оценено: полный клон — 215 МБ .git, blobless — 26 МБ. История
коммитов и теги в обоих полные, поэтому диапазоны, merge-base и git diff по
истории работают одинаково; diff трёх коммитов в blobless-клоне занимает секунду
и добавляет мегабайт.

Разница в том, что содержимое старых файлов скачивается только если его кто-то
спросит. 32% пака — скриншоты документации, десять PNG, переснятых 196 раз; ещё
заметная доля — закоммиченный бандл, 1.16 МБ на каждую продуктовую правку. Старые
ревизии ни того, ни другого практически никто не читает.

Про --depth=1 сказано отдельно, что он не замена: размер тот же, но merge-base
нет, и процессный гейт вместе со smoke-select перестают работать.

Issue: #345
User-Visible: no
---
 CONTRIBUTING.md | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4bb6a5f0..6d91dade 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -57,7 +57,7 @@ issue, but they do not replace it or maintain a separate checklist.
 ## Five-minute setup
 
 ```bash
-git clone https://github.com/Matysh/houseplan-card && cd houseplan-card
+git clone --filter=blob:none https://github.com/Matysh/houseplan-card && cd houseplan-card
 npm ci                    # frontend toolchain
 npm run typecheck         # tsc --noEmit (strict)
 npm test                  # node:test — pure logic, i18n parity, tap-action security
@@ -66,6 +66,24 @@ pip install pytest voluptuous && python -m pytest tests_backend -q   # pure back
 npm install                # also installs .githooks through the prepare script
 ```
 
+### Why `--filter=blob:none` (#345)
+
+A full clone is **215 MB of `.git`**; a blobless one is **26 MB** — measured, not
+estimated. Both carry all 1611 commits and all 182 tags, so ranges, `merge-base`
+and `git diff` across history work identically; `git diff origin/dev~3..origin/dev`
+in a blobless clone takes about a second and grows `.git` by one megabyte.
+
+The difference is that historical *file contents* are fetched only if something
+actually asks for them. That matters here because 32% of the pack is documentation
+screenshots — ten PNGs re-captured 196 times — and another sizeable share is the
+committed bundle, one 1.16 MB file per product change. Almost nobody ever reads an
+old revision of either.
+
+Drop the flag if you work offline with history, or need `git log -p` over the whole
+tree repeatedly. Do **not** replace it with `--depth=1`: a shallow clone is about
+the same size but has no `merge-base`, so the process gate, `smoke-select` and
+every `origin/dev..HEAD` range stop working.
+
 The HA-harness backend tests (`tests_backend/test_ha_*.py`) need Python ≥3.13 and
 `pytest-homeassistant-custom-component home-assistant-frontend`; CI runs them on
 every push — locally they are skipped when `homeassistant` is not importable.