Clone, Shallow, and Partial Clone

## What "shallow" means A normal clone copies the complete commit graph: every commit reachable from the remote's refs, plus all the trees (directory listings) and blobs (file contents) those commits reference. For a long-lived project that is often hundreds of megabytes of history nobody on the machine will ever read. `git clone --depth <n> <url>` asks the server to send only the last `<n>` commits of the branch being cloned, plus the objects needed to check that state out. The result is a **shallow repository**: an ordinary Git repository in every other respect, but with a deliberately truncated history. ## How Git records the truncation The file `.git/shallow` holds the commit IDs that sit on the boundary. Git treats each of those commits as if it had no parents, so history simply stops there. Nothing is corrupt and nothing is lying about content — the commits you do have are byte-for-byte the real ones, with their real IDs. Only the ancestry beyond the boundary is unavailable, because those objects were never transferred. This is why `git log --oneline` in a `--depth 1` clone prints exactly one line, and why `git log --graph` shows no ancestry. ## What --depth implies about branches `--depth` turns on `--single-branch` automatically. The practical consequences: - Only one branch is fetched — the one given with `--branch <name>`, or the remote's default branch if you did not say. - The `remote.origin.fetch` line in `.git/config` is narrowed to that single branch instead of the usual `+refs/heads/*:refs/remotes/origin/*`, so later `git fetch` calls keep fetching only that branch until you widen it. - Only tags that point into the history you received come along; `--no-tags` skips even those. If you want the tips of all branches but still no deep history, `git clone --depth 1 --no-single-branch <url>` does that. ## Variants of the depth request `--depth <n>` is a commit count, but Git can also truncate by other criteria: `--shallow-since=<date>` keeps commits newer than a date, and `--shallow-exclude=<ref>` keeps history that is not already reachable from the named ref or tag. All three produce the same kind of shallow repository with a `.git/shallow` boundary. ## What it costs Anything that needs ancestry degrades. `git log` and `git blame` stop at the boundary. `git describe` cannot find a tag if the tag is older than the boundary. `git merge-base` may not find a common ancestor with another branch, so merges, rebases and "diff against the target branch" style commands can fail or produce nonsense. `git bisect` can only search the commits present. A shallow clone is also not a substitute for a **partial clone**. Shallow truncates the *history* (fewer commits); a partial clone (`--filter=blob:none`) keeps the whole commit graph but omits *file contents* until something asks for them. They solve different problems and can be combined. ## When to use it Use `--depth 1` when the job only needs the current source tree: compiling, running a linter over the checkout, building a container image, publishing a static site. Avoid it when the job needs history: tag-derived version numbers, changed-file detection against a base branch, blame-driven ownership checks, or anything that merges or rebases. The shallowness is not permanent — `git fetch --unshallow` refills the history later, at the cost of the download you were trying to avoid.