Skip to content
shellmap

Clone a repo with shallow history

Clone only the last N commits — for CI runners, ephemeral builds, and tooling that doesn't need full git history.

How to clone a repo with shallow history in each shell

Bashunix
git clone --depth 1 https://github.com/HK2-AI/shellmap.git

`--depth 1` = only the tip commit (no history). Add `--single-branch` to also skip fetching other branches' tips. For CI building from a specific tag/branch: `--depth 1 --branch v1.0 --single-branch`.

Zshunix
git clone --depth 1 https://github.com/HK2-AI/shellmap.git
Fishunix
git clone --depth 1 https://github.com/HK2-AI/shellmap.git
PowerShellwindows
git clone --depth 1 https://github.com/HK2-AI/shellmap.git
cmd.exewindows
git clone --depth 1 https://github.com/HK2-AI/shellmap.git

Equivalents listed for Bash, Zsh, Fish, PowerShell, cmd.exe.

Gotchas & notes

  • **`--depth N` vs `--filter=blob:none` (partial clone)** — `--depth N` chops history at N commits; you can't `git log` past N-1 generations, `git blame` is incomplete, and unshallowing later requires `git fetch --unshallow` (a full re-fetch of all the old commits). **`--filter=blob:none`** (partial clone, git 2.19+) keeps the full commit GRAPH but lazily downloads file blobs on demand — `git log` and `git blame` work for metadata; checking out an old commit pulls the blobs at that moment. For CI builds the right answer is usually `--depth 1`; for developer workflows that occasionally need old code, `--filter=blob:none --no-checkout` then `git checkout` lazily-fetches.
  • `--single-branch` matters: without it, even with `--depth 1`, git fetches the TIP commit of EVERY remote branch (because `--depth` limits HISTORY not BREADTH). On a repo with 1000 branches, `--depth 1` alone still downloads 1000 commits + their root trees. `git clone --depth 1 --single-branch --branch main` is the minimum for a single-branch CI build. Re-enabling later: `git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"` then `git fetch`.
  • Shallow-clone limitations: (1) Cannot push to a shallow clone's history (the server can't reconcile your commits with missing parents). Workaround: `git fetch --unshallow` before pushing. (2) Cannot rebase past the shallow boundary — `git rebase main` fails if the merge-base is older than your depth. (3) GitHub PR merge-base computations fail for shallow forks: GitHub Actions `actions/checkout@v4` defaults to `fetch-depth: 1` (shallow) which BREAKS `nx affected` and other tools that compare against merge-base — set `fetch-depth: 0` (full) or `fetch-depth: 50` (last 50 commits, usually enough for merge-base).
  • Bandwidth: full clone of `chromium/chromium` is ~20 GB, `--depth 1` is ~3 GB, `--filter=blob:none` is ~150 MB (then blobs fetched on demand). Linux kernel: full ~5 GB, `--depth 1` ~250 MB, `--filter=blob:none` ~40 MB. For pure-build CI use `--depth 1 --single-branch --branch main`. For tooling that needs `git log` / `git blame` (changelog generation, AUTHORS file, IDE git integration), use `--filter=blob:none` instead. NEVER use `--depth 1` if you plan to push back — recovery is painful.

Related commands

Related tasks