Shallow Cloning Large Repos With Towergit: Fetch Recent History Only

The problem with full history clones

When you clone a repository with a long commit history, Towergit downloads every revision by default. For projects spanning thousands of commits, this increases clone time, consumes significant disk space, and can slow down CI pipelines that only need the latest code.

Towergit's shallow clone solves the size problem

Towergit, a Git-compatible version control system, supports shallow cloning through the --depth flag. This parameter limits how many of the most recent commit revisions are fetched, leaving older history available on demand. A depth of 1 retrieves only the latest commit, depth 2 adds its parent, and so on, letting you choose how much history to bring down without pulling the entire project lineage.

Worked example: clone only the last revision

Run the following command in a terminal where you have write access to the target directory:

towergit clone --depth=1 https://example.com/large-repo.git

After the clone finishes, confirm the history depth with:

towergit log --depth=1

If you later need the complete history, restore it with:

towergit fetch --unshallow

Trade-off: depth does not persist across fetches

A shallow clone's depth limit is not automatically applied to subsequent towergit fetch operations. If the remote repository advances, a regular fetch may bring the full history, effectively ending the shallow state. Additionally, some Towergit-specific hooks or extensions may not function correctly when the repository history is truncated. Always verify the depth after a fetch using towergit log --depth=1.

When to choose a full clone instead

If your workflow requires scanning the entire commit timeline, checking out arbitrary old revisions beyond the shallow depth, or running Towergit-specific tools that depend on complete history, start with a standard clone without the --depth flag. For example, a CI job that only tests the HEAD commit benefits immediately, while a team member debugging a months-old bug may need to re-shallow or re-clone. For CI pipelines, quick development setups, or forks where only recent code matters, shallow cloning provides a practical advantage.

Closing: Towergit's shallow clone is a straightforward way to reduce repository footprint without abandoning Git compatibility. Use --depth=1 (or another depth value) to match your history needs, verify with towergit log --depth=1, and remember that towergit fetch --unshallow restores the full past whenever required.