Shallow Clones in Git: When and How to Use Them

Shallow clones in Git fetch only part of the commit history. They are useful when a CI job, deployment step, or quick inspection task needs the current code but not years of history.

They are not the best default for every developer workstation. A shallow clone can save time and disk space, but it also limits history-based commands until you fetch more commits.

What is a Shallow Clone?

A standard clone fetches enough history for normal branch work, history inspection, old tag checkout, and offline investigation. A shallow clone truncates that history at a depth you choose.

For example, --depth 1 fetches the tip commit for the selected branch. --depth 50 fetches more recent history, but still not the full ancestry.

Benefits of Using Shallow Clones

The main benefit is lower transfer cost:

• Faster first checkout for large repositories.
• Less disk use on short-lived build agents.
• Lower bandwidth use on slow or metered networks.
• Less history for Git to process during the initial clone.

In a CI pipeline that builds the current commit and throws the workspace away, a shallow clone is often a clean win.

Drawbacks and Limitations of Shallow Clones

The tradeoff is missing history:

• git log stops at the shallow boundary.
• git blame may not be able to follow older changes.
• Old tags or commits may be unavailable until fetched.
• Rebases and merges can be harder if Git needs a missing merge base.
• Some release or audit workflows expect a full history.

If your work often involves debugging old regressions, preparing releases, or backporting changes, start with a full clone.

How to Create a Shallow Clone

Use git clone --depth:

git clone --depth <number> <repository_url>

For example, to clone a repository and only fetch the latest 10 commits:

git clone --depth 10 https://github.com/example/large-repo.git

For a build job that only needs the branch tip:

git clone --depth 1 https://github.com/example/project.git

To clone a specific branch:

git clone --depth 1 -b develop https://github.com/example/project.git

You can also add --single-branch when you only want history for that branch:

git clone --depth 1 --single-branch --branch develop https://github.com/example/project.git

Managing Shallow Clones

Fetching More History (Deepening the Clone)

If you need more history after cloning, deepen the repository:

git fetch --deepen=50 origin

That fetches 50 more commits beyond the current shallow boundary.

You can also set the total depth you want:

git fetch --depth=100 origin

The important point: git remote set-depth is not a valid Git command. Depth is controlled through clone and fetch options.

Fetching Tags

Shallow clones may not include all tags, especially tags pointing to older commits. Fetch tags only if your workflow needs them:

git fetch --tags origin

Unshallowing a Repository

To convert a shallow clone into a full clone, fetch the rest of the history:

git fetch --unshallow origin

This command will download the remaining history from the remote repository.

Pushing from a Shallow Clone

Pushing from a shallow clone can work when your new commits are based on the remote branch tip you fetched. It is still a poor fit for long-running development because missing history can make rebases, conflict resolution, and review harder.

If you hit history-related push or merge problems, fetch more history or unshallow the clone before continuing.

When to Use Shallow Clones

Use them when the job is short-lived and history is not important:

• CI/CD checkout.
• Read-only inspection.
• Temporary reproduction environments.
• Documentation builds.
• Large repositories on slow networks.

When Not to Use Shallow Clones

Avoid them when you regularly need:

• Deep git log, git blame, or git bisect.
• Release work that uses old tags.
• Complex merge or rebase work.
• Offline debugging across history.
• Contribution workflows that expect a full clone.

Practical Takeaway

Use git clone --depth 1 for disposable jobs that only need the latest code. Use a full clone for normal development unless you have a clear reason not to.

If a shallow clone starts getting in your way, deepen it with git fetch --deepen=<number> origin or convert it with git fetch --unshallow origin. That is usually faster and safer than fighting missing-history errors one command at a time.