Clone one Git branch without fetching the whole repository

“Clone this branch” can mean two different things. You may only want a particular branch checked out after cloning, or you may need Git to avoid fetching the histories of every other branch. --branch handles the checkout choice; --single-branch narrows the configured fetch. Confusing those goals is why an apparently focused clone can still transfer far more data than expected.

Establish what the server actually exposes

Before creating a working copy, confirm the remote URL and exact branch name. Branch names are case-sensitive, and a tag with the same short name can make an imprecise request surprising.

git ls-remote --symref https://git.example.test/team/app.git HEAD
git ls-remote --heads https://git.example.test/team/app.git 'refs/heads/release/2026-q3'

The second command should return one line. No output usually means the name is wrong, the branch is hidden, or authentication cannot see it. A transport or permission error is not evidence that the branch is absent. Diagnose credentials and network policy separately; do not put access tokens in a command line, repository URL, or shared log.

Use a single-branch clone when the ref boundary matters

git clone \
  --branch release/2026-q3 \
  --single-branch \
  -- https://git.example.test/team/app.git app-release
cd app-release

The -- ends option parsing, and the explicit destination avoids deriving an awkward directory name. Current Git documentation says --branch points the new HEAD at the named branch (or tag), while --single-branch fetches only history leading to that tip and configures later ordinary fetches to update that branch. Without --single-branch, --branch primarily selects the initial checkout.

This is still a real clone with the selected branch’s reachable history and objects. If the selected history contains old large blobs, limiting refs may save little. It also does not automatically initialize submodules or Git LFS objects; those are separate data paths with separate credentials and lifecycle.

Choose the right bandwidth control

For an ephemeral build that needs only recent commits, add a shallow boundary:

git clone --branch release/2026-q3 --single-branch --depth 1 \
  -- https://git.example.test/team/app.git app-release

A shallow clone changes history semantics. Merge-base calculations, blame, changelog generation, versioning based on old tags, and pushes can fail or produce incomplete answers. Deepen deliberately if a job later needs more history:

git fetch --deepen=100 origin release/2026-q3
# Or, after reviewing the cost:
git fetch --unshallow

When full commit history matters but large file contents do not, a server-supported partial clone can be a better trade:

git clone --branch release/2026-q3 --single-branch \
  --filter=blob:none \
  -- https://git.example.test/team/app.git app-release

That defers blobs until they are needed. It reduces the initial transfer but creates future network dependencies, so an offline build or poorly cached CI fleet may become less predictable. Sparse checkout limits which paths populate the working tree; it is not, by itself, a promise that unrelated objects were never transferred.

Verify the clone rather than trusting the prompt

git branch --show-current
git status --short --branch
git remote get-url origin
git config --get-all remote.origin.fetch
git show-ref --verify refs/heads/release/2026-q3
git rev-parse --is-shallow-repository

A focused clone normally has a fetch refspec for the selected remote branch rather than the usual wildcard. Record the exact commit ID used by a deployment with git rev-parse HEAD; a moving branch name is not a reproducible release identifier. For supply-chain-sensitive work, verify the commit or tag signature according to the project’s trust policy.

When the branch must expand later

A single-branch clone is not permanently trapped. Add another remote-tracking branch explicitly instead of replacing the configuration blindly:

git remote set-branches --add origin hotfix/urgent
git fetch origin hotfix/urgent
git switch --track -c hotfix/urgent origin/hotfix/urgent

Inspect remote.origin.fetch after the change. If the team now needs every branch, deliberately restore the wildcard refspec and fetch, budgeting disk and network impact. Avoid copying a .git directory from another checkout: alternates, worktree metadata, credentials, and ownership can make that shortcut fragile or unsafe.

Failure modes and recovery

• Remote branch not found: verify refs/heads/… with ls-remote, spelling, visibility, and authentication.
• Detached HEAD: --branch also accepts a tag. Create a branch only if you intend to commit, and confirm its upstream before pushing.
• Unexpectedly large transfer: inspect the chosen branch’s reachable objects; consider shallow or partial clone based on the job’s actual history needs.
• Missing submodule content: review .gitmodules, then use a controlled recursive clone or git submodule update --init with approved URLs.
• Shallow history breaks a release tool: deepen or unshallow the disposable clone. Do not fabricate tags or history.

If a clone was made with the wrong scope and no valuable local work exists, the safest rollback is often to preserve any diagnostic logs, remove only the explicitly named disposable checkout, and clone again with the reviewed options. If local commits exist, first create a recovery branch or bundle and verify it before changing refspecs. In production, the smallest initial download improves CI speed, but a complete clone improves offline behavior and makes history-dependent tooling predictable. Treat clone shape as part of the build contract.

Attribution and current verification

This guide was prompted by Scud’s Stack Overflow question and Michael Krelin - hacker’s accepted answer, used under CC BY-SA. The accepted --branch --single-branch solution remains correct. Its present fetch behavior, tag caveat, shallow-clone implications, partial-clone filter, and submodule options were independently verified against the current official git-clone documentation, with ref inspection checked against git-ls-remote.