Quick Links
Key Takeaways
To checkout a branch from a remote repository, use the 'git fetch' command, and then 'git branch -r' to list the remote branches. Pick the branch you need and use a command of the form 'git checkout -b new-branch-name origin/remote-branch-name.' If you use multiple repositories change the 'origin' part of the checkout command to the name of the remote you wish to checkout the branch from.
If your development team uses Git, you'll eventually need to check out someone else's work as a branch from a remote repository. Like most branch actions in Git, switching to a remote branch is actually quite simple.
Git, Branches, and Remotes
The Git philosophy is to branch often. Branches allow development to take place without altering the main code base. When you are satisfied that your new, tested code is ready, you merge your new branch into another branch. Usually, this is the main or master branch, but you can merge any two branches.
Because of this flexibility, and the lightweight and fast way that Git handles branches and merges, branching was transformed. In older version control systems, branching was a big deal. Branching and merging were slow and error-prone. Git gave developers easy, fast branching that's used to underpin many different workflows.
If you work or volunteer as part of a development team using Git, you'll have a "central" Git repository, remote from each software engineer's computer. This is known as the remote repository, or just the "remote." It's where the commits and changes to your local repository get sent when you perform a push.
Of course, that's what the other developers are doing, too. This makes it easy to collaborate. If you need to access another developer's work, you just retrieve their code from a branch on the remote repository. If they need to access your work, they'll retrieve your code from a branch on the repository that tracks one of your local branches.
In Git, a development project can have multiple remotes. However, a local branch can only track a single remote branch. So, as long as you are working with the appropriate remote, checking out a remote branch with multiple remotes is the same as using a single remote.
Finding Your Local Branches
You need to avoid name conflicts. If you have a local branch that happens to have the same name as the remote branch you are going to check out, you have two options. You can rename your local branch and check out the remote branch. That way, your local branch that tracks the remote branch has the same name as the remote branch. Or, you can checkout the remote branch and tell Git to create a local tracking branch with a new name.
To find out the names of the branches in your local repository, use the
git branch
command.
git branch
This local repository has a master branch and three other branches. The asterisk indicates which is the current branch. Moving from branch to branch requires checking out the branch you want to work with.
git checkout new-feature
git status
The first command changes the branch for us, so that "new-feature" is the current branch. The git status command verifies that for us.
We can hop back and forth between branches, committing new changes, pulling updates from the remote, and pushing local updates to the remote.
Checking Out a Remote Branch
There's a branch on the remote repository that isn't present on our machine. A developer called Mary has created a new feature. We want to switch to that remote branch so we can build that version of the software locally.
If we perform a fetch, Git will pull back the metadata from the remote repository.
git fetch
Because this is the first fetch we've done since Mary pushed her branch to the remote repository, We're told there is a new branch called "origin/mary-feature." The default name for the first remote repository added to a project is "origin."
Whether we see this message or not, we can always ask Git to list the branches in the remote repository.
The -r (remote) option tells Git to report on the branches that are on the remote repository.
git branch -r
The point to note here is that Git is checking its local copy of the remote's metadata. That's why we used the git fetch command to make sure the local copy of the metadata is up to date.
Once we spot the branch we want, we can go ahead and check it out. We use the git checkout command with the -b (branch) option, followed by the name we'll use for the local branch, followed by the name of the remote branch.
git checkout -b mary-feature origin/mary-feature
We can see that we've checked out the remote branch and created a local branch that will track changes in the remote branch.
git branch
Our new local branch is now our current working branch.
Handling Name Clashes
If you have a local branch that has the same name as the remote branch, you can either rename your local branch before checking out the remote branch, or checkout the remote branch and specify a different local branch name.
To checkout the remote branch into a differently-named local branch, we can use the same command we used earlier, and choose a new local branch name.
git checkout -b mary-test origin/mary-feature
This creates a local branch called "mary-test" that will track local commits to that branch. Pushes will go to the remote "origin/mary-feature" branch.
This is probably the best way to handle local name clashes. If you really want to keep the name of the local and remote branch the same, you'll need to rename your local branch before checking out the remote. Renaming a branch is trivial in Git.
git branch -m mary-feature old-mary-branch
You're now clear to checkout the remote "origin/mary-feature" branch.
Handling Multiple Remote Repositories
If you have multiple remote repositories configured, you need to take care you are working with the appropriate repository when you check out the remote branch.
To list your remote repositories, use the remote command with the -v (view) option.
git remote -v
To see all the available branches, we need to fetch the metadata from all our remotes, then list the remote branches.
git fetch --all
git branch --all
We can see the branch we want is in the "origin" remote. The command to check it out is in the same format we've already used. We need to specify the remote name, "origin", as well as the branch name, "mary-feature."
git checkout -b mary-feature origin/mary-feature
Before You Checkout
Before you checkout keep a few things in mind, and you'll be fine.
Make sure you avoid name clashes. If you have a local branch with the same name as the remote branch, decide whether you'll rename the local branch or create a branch with a different name to track the remote branch.
If you use multiple remote repositories, make sure you use the correct remote.