GIT: git checkout a Remote Branch

One of the first Git commands you've learned was certainly "git checkout":

$ git checkout development

In its simplest form, it allows you to switch (and even create) local branches - something you need countless times in your day-to-day work.

However, git checkout's power is not limited to local branches: it can also be used to create a new local branch from a remote one.

Collaborating with Branches

Remember that branches are the main way of collaboration in Git. Let's say that one of your colleagues wants you to collaborate on (or review) a piece of code:

1. She will push the corresponding branch to your common remote server.
2. In order to see this newly published branch, you will have to perform a simple "git fetch" for the remote.
3. Using the "git checkout" command, you can then create a local version of this branch - and start collaborating!

git checkout for Remote Branches

The syntax for making git checkout "remote-ready" is rather easy: simply add the "--track" flag and the remote branch's ref like in the following example:

$ git checkout --track origin/newsletter
Branch newsletter set up to track remote branch newsletter from origin.
Switched to a new branch 'newsletter'

Based on the remote branch "origin/newsletter", we now have a new local branch named "newsletter".

Note that, by default, Git uses the same name for the local branch. Being a good convention, there's rarely the need to change this.

Committing and Exchanging Data

From here on, you can make changes and commit them to your new local branch like you're used to.

Remember to publish your changes to the remote by using "git push" from time to time. Only then will your colleague(s) be able to see and understand your changes.

GIT: How can I tell a local branch to track a remote branch?

Understanding and making use of tracking relationships makes version control a whole lot easier. Let's talk about both the concept and the practice of "tracking" branches.

What are tracking connections in Git?

By default, branches in Git have nothing to do with each other. However, when you tell a local branch to "track" a remote branch, you create a connection between these two branches. Your local branch now has a "counterpart" on the remote server.

Why should you set up tracking connections?

Let's say your current local HEAD branch is named "dev". And let's also say that you have set it up to track the "dev" branch on the remote named "origin". This relationship is invaluable for two reasons:

1. Pushing and pulling becomes a lot easier. You can simply use the shorthand commands "git pull" and "git push" - instead of having to think about the exact parameters like in "git push origin dev". Even more importantly than being "easier", this also prevents you from making mistakes!
2. Git can now inform you about "unpushed" and "unpulled" commits. Let's make an example:
   (a) if you have 2 commits only locally that you haven't pushed to the remote yet, your local branch is "2 commits ahead" of its remote counterpart branch.
   (b) if, on the other hand, there are 4 commits on the remote branch that you haven't downloaded yet, then your local branch is "4 commits behind" its remote counterpart branch.

   

   This information helps tremendously in staying up-to-date. Git tells you about this right in the output for "git status":

   $ git status
   # On branch dev
   # Your branch and 'origin/dev' have diverged,
   # and have 1 and 2 different commits each, respectively.
   #
   nothing to commit (working directory clean)

How do you track a remote branch?

There are three main scenarios for creating a tracking connection.

When you're starting to work on an existing remote branch

Let's say one of your colleagues has already started and published a branch on your remote server. You now want to chime in and start working on that topic, too. In that scenario, simply use the --track flag with the "git checkout" command:

$ git checkout --track origin/dev
Branch dev set up to track remote branch dev from origin.
Switched to a new branch 'dev'

This creates a new local branch with the same name as the remote one - and directly establishes a tracking connection between the two.

When you're publishing a local branch

Let's now look at the opposite scenario: you started a new local branch and now want to publish it on the remote for the first time:

$ git push -u origin dev

You can tell Git to track the newly created remote branch simply by using the -u flag with "git push".

When you decide at a later point in time

In cases when you simply forgot, you can set (or change) a tracking relationship for your current HEAD branch at any time:

$ git branch -u origin/dev