Shallow clones and partial checkouts — fetching less history

A shallow clone truncates history at a depth; a partial clone defers blobs on demand. Both cut bandwidth; both impose limits. The trade is fetch cost versus local capability.

Shallow clones

git clone --depth 1 "$REPO_URL" repo
git clone --depth 50 --branch main "$REPO_URL" repo
git clone --shallow-since="2024-01-01" "$REPO_URL" repo

--depth 1 fetches only the tip (cheapest). --shallow-since is date-bounded.

flowchart LR
    A[("full")] -->|"depth 1"| B[("tip")]
    A -->|"depth 50"| C[("last 50")]
    A -->|"shallow-since"| D[("since date")]

Shallow clones cannot run most history ops: git log --all shows only the present window; git bisect cannot reach older bugs.

Partial clones

git clone --filter=blob:none "$REPO_URL" repo
git clone --filter=tree:0 "$REPO_URL" repo
git clone --filter=blob:limit=1m "$REPO_URL" repo

--filter=blob:none defers all blobs. --filter=tree:0 defers all trees (rarely useful). --filter=blob:limit=1m defers blobs above 1 MB.

flowchart LR
    A[("full")] -->|"filter blob:none"| B[("commits+trees")]
    B -->|"checkout needs blob"| C["on-demand"]

A partial clone has full history, but ops that read a blob trigger fetches. git log -p fetches per hunk.

Choosing a strategy

• CI cold cache. --depth 1, no --filter.
• Engineer workstation. --filter=blob:none, no --depth.
• CI release tag. --branch $TAG --depth 1.
• Long-lived feature. No shallow, no partial; the history is the value.

Shallow can git fetch --unshallow; partial can git fetch --filter= to materialise.

Production discipline

1. Default CI to --depth 1, no --filter.
2. Default workstations to --filter=blob:none, no --depth.
3. Pin release builds to --branch $TAG.
4. Document the unshallow path.

Cross-course references

• Linux for Production Sysadmins Part XXVI: filesystem analogue.
• Terraform for Production Sysadmins Part IX: state in a backend.

Quiz