How do I clone a single branch in Git?

Question

I have a local Git repository called \'skeleton\' that I use for storing project skeletons. It has a few branches, for different kinds of projects:

casey@aga         


        

Answer 1

There are ample answers here which mention:

# (We'll refer to this as "the 1st command" below.)
git clone -b branch_name --single-branch \
https://github.com/some_project/some_project.git

...or some version of that, and a few which mention just:

# (We'll refer to this as "the 2nd command" below.)
git clone -b branch_name https://github.com/some_project/some_project.git

...withOUT the --single-branch part.

But, I'd like to expound upon these two things a bit and show a more familiar set of equivalent commands so we can see what is happening with each under-the-hood.

Let's assume that you have a remote repo on GitHub at https://github.com/micronucleus/micronucleus.git, with remote branches master and version_2.5 (this is a real example you can actually run right now).

Breakdown of the 2nd command from above:

The 2nd command (git clone -b version_2.5 https://github.com/micronucleus/micronucleus.git) clones ALL REMOTE BRANCHES to your local PC, but then checks out the version_2.5 branch instead of the master branch. That one command is the equivalent of doing this:

git clone https://github.com/micronucleus/micronucleus.git
cd micronucleus  # cd into the repo you just cloned
git checkout version_2.5
# To be pedantic, also delete the local `master` branch since
# technically it won't exist yet since you haven't yet checked
# it out with `git checkout master`, which would create it from
# your locally-stored remote-tracking branch, `origin/master`
git branch -d master

The -b version_2.5 part automatically checked out the version_2.5 branch for us instead of master.

git branch -a shows us that ALL branches, however, were cloned to our local PC. Here you can see our local branch version_2.5, which we are on, plus the locally-stored remote-tracking branches origin/HEAD (which points to origin/master), plus origin/master, and origin/version_2.5:

$ git branch -a
* version_2.5
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/version_2.5

We can also look at what our fetch references are. You can either open up the .git/config file to see them directly, or just run git config remote.origin.fetch:

$ git config remote.origin.fetch
+refs/heads/*:refs/remotes/origin/*

You can see above that our git fetch command (which is also triggered by git pull since that is equivalent to git fetch && git merge) is configured to fetch ALL heads for ALL branches in the origin remote. I'm not an expert on this part, but I believe that's what +refs/heads/*:refs/remotes/origin/* means.

Breakdown of the 1st command from above:

The 1st command (git clone -b version_2.5 --single-branch https://github.com/micronucleus/micronucleus.git) clones ONLY the version_2.5 branch to your local PC, and it also checks it out. That one command is the equivalent of doing this (in the end result at least, except that it also downloads much less data in the beginning since it only clones ONE branch NOT all of them):

git clone https://github.com/micronucleus/micronucleus.git
cd micronucleus  # cd into the repo you just cloned
git checkout version_2.5

# Delete ALL other branches, including remote-tracking ones, which are not the 
# `version_2.5` branch:
# One local branch
git branch -d master
# ALL other locally-stored remote-tracking branches
git branch -dr origin/HEAD 
git branch -dr origin/master

# Fix your `.git/config` file so that `git fetch` does the right thing, fetching
# ONLY the `version_2.5` branch head from the `origin/version_2.5` remote branch:
git config remote.origin.fetch \
"+refs/heads/version_2.5:refs/remotes/origin/version_2.5"

The -b version_2.5 part caused the version_2.5 branch to be checked out instead of the master branch by default (as previously explained above), and the --single-branch part caused:

1. NONE of the other branches to be cloned to our PC, and
2. git fetch to be configured such that NONE of the other branches will ever be fetched when we call git fetch or git pull!

This command truly cloned and will fetch only the one branch we wanted, and that's it!

git branch -a shows us that ONLY the version_2.5 branch was cloned and checked out. Here we see by the * which branch is checked-out, and we see also that we have a locally-stored remote-tracking branch for origin/version_2.5:

$ git branch -a
* version_2.5
  remotes/origin/version_2.5

We can also look at what our fetch references are. You can either open up the .git/config file to see them directly, or just run git config remote.origin.fetch:

$ git config remote.origin.fetch
+refs/heads/version_2.5:refs/remotes/origin/version_2.5

You can see above that our git fetch command will only fetch the version_2.5 branch head from the origin/version_2.5 remote branch. That's it! Beware that no other remote branches will ever be fetched.

Summary:

So, now you see that using -b branch_name basically just ensures the branch_name branch is checked-out after the clone, but still clones ALL remote branches, whereas adding also --single-branch ensures that ONLY branch_name is cloned, fetched, pulled, and tracked. No other remote branches will be cloned to your PC whatsoever.

Personally, I prefer the -b branch_name option alone, because I want all branches cloned to my local PC. The one exception might be on a huge, shared mono-repo which has dozens, or even hundreds or thousands of remote branches. In that case, just use -b branch_name --single-branch to clone just the one main branch you care about and be done. Better to download 50 GiB of data for the master branch in a huge mono-repo, for instance, than to download 200 GiB of data so you can have 2000 of your peers' branches they are working on too!

References:

1. Clone only one branch
2. How do you stop tracking a remote branch in Git?