Quick Links
Summary
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
TheGitphilosophy is to branch often.Branchesallow development to take place without altering the main code base. When you are satisfied that your new, tested code is ready, youmerge your new branchinto 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 havemultiple 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 thegit branchcommand.
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.
The first command changes the branch for us, so that “new-feature” is the current branch. Thegit statuscommand 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 weperform afetch, Git will pull back the metadata from the remote repository.
Because this is the firstfetchwe’ve done since Mary pushed her branch to the remote repository, We’re told there is anew branchcalled “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.
The point to note here is that Git is checking its local copy of the remote’s metadata. That’s why we used thegit fetchcommand to ensure 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 thegit checkoutcommand with the-b(branch) option, followed by the name we’ll use for the local branch, followed by the name of the remote branch.
We can see that we’ve checked out the remote branch and created a local branch that will track changes in the remote 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.
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 branchis trivial in Git.
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 theremotecommand with the-v(view) option.
To see all the available branches, we need to fetch themetadatafrom all our remotes, then list the remote branches.
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.”
Before You Checkout
Before you checkout keep a few things in mind, and you’ll be fine.
ensure 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.
