If you’re not very familiar with Git branching, or you’d like to refresh your understanding about it, please head to Git Branching and Merging, then come back and move on.
In this article you’ll learn what are remote and tracking branches, how they work and how to use them.
Do not type the
$ sign you see in the command examples. That’s just an indicator that you should run the command that follows it in your command line tool.
What are Remote Branches?
“Remote references are references to the state of branches on your remote repositories. They’re local branches that you can’t move; they’re moved automatically whenever you do any network communication.” (Chacon 50)
So a remote branch is a local branch (created in your local repo) that points to and contains a copy of a branch in some remote repo. It’s also ready-only, so you cannot change it, it’s supposed to be updated when we run a
fetch command. A bit confusing? I know, it really is at a first look.
Starting a New Local Repo
For the sake of learning, we’ll create a very simple Git project/repo and play with it to better understand branching and remote branches. So now please create a new directory, add a couple files in it, and run
$ git init. Now if you run
$ git status you should see your files listed as Untracked files. So let’s run
$ git add ., and then
$ git commit -m "adding some files.". Nice, now we have a local repo with some files committed to it.
Starting a New Remote Repo
Adding a Remote Reference to Your Local Repo
After you have setup your remote repo, let’s add a reference to it in your local repo. To do that, run a command like:
$ git remote add origin [your-remote-url-goes-here]
Note that we’re giving that remote an alias of
origin, but it could be anything we wanted. If you run
$ git remote now you should see something like:
If you want more info about your remote repo you can append
-v option to that command:
$ git remote -v
In that case you should see something like:
origin [your-remote-repo-url] (fetch) origin [your-remote-repo-url] (push)
Note that Git lists two references to it, one for reading from your remote repo (fetch), and another for writing to your remote repo (push).
Pushing to a Remote Repo
Now we can push to our remote repo, so let’s do just that:
$ git push origin master
You should see something like:
Counting objects... ... Writing objects: 100%... ... * [new branch] master -> master
That means the operation was successfully completed. Git should have created a master branch in your remote repo, and created a reference to it in your local repo. That reference is our remote branch (our remote master branch in this case), created in our local repo. By default, when we push to a remote repo, and there’s no remote branch setup for that local branch we’re pushing, Git creates one for us automatically, and names it as
remotes/remote-name/branch-name, so in this case
Checking Your Remote Branches
If you run
$ git branch -r now (
-r option means remote), you should see something like:
You can also run
$ git branch -a to see all branches, local and remote. In that case, you should see something like:
* master remotes/origin/master
remotes/origin/master remote branch is a copy of your remote repo’s master branch, a branch living in your remote repo. At this time they are the same, but when you work on a project with other members, they will also update the project’s remote repo, so your
remotes/origin/master remote branch will become outdated at some point. Just keep that in mind for now.
Switching to Remote Branches
You can really switch to remote branches if you want. Let’s just try that by running:
$ git checkout origin/master
You should see some output, including something like Note: checking out ‘origin/master’. Note that you can omit
remotes/ prefix when referring to remote branches.
What’s coolest is that it’s a local operation, because you have a copy of the contents of your remote repo’s master branch exactly as it is. Nice, isn’t it?
Cool, now I feel you have a better understanding about what are remote branches. Next, let’s see how to update them when someone else pushes code to a remote repo we’re working on.
Updating Our Remote Branches
We know that to send our local changes to a remote repository we run a
push command. But It’s a good practice to always run a
fetch command before
push, as we’ve seen here. The only exception is when we’re pushing a new branch to our remote repo, effectively creating that new branch in our remote repo. In that case, since that branch didn’t exist in that remote repo yet, there’s nothing to fetch from.
fetch command synchronizes our local repo with a remote repo:
$ git fetch [remote-name]
By synchronize we understand a copy of all branches in the remote repo to our local repo as remote branches. If a remote branch already exists in our local repo, it is updated.
fetch command doens’t touch our local branches (master, etc), only our remote ones (
origin/master, etc). So our master branch keeps outdated if we get new changes from our remote repo when we run
fetch. We need to
merge those changes into our local master branch after running
fetch. We’ll do that in a moment, first let’s see why we need to run
push one more time.
Why Do We Need to Run Fetch Before Push?
If someone else has pushed content to a remote repo, you need to
fetch those changes first, and
merge them into your local branch. Only then you can
push your changes. Git doesn’t allow us to push our changes to a remote repo if our local branch is outdated in relation to our target branch. In other words, if someone else has updated our remote repo’s master branch, we first need to merge those changes into our local master branch, and only then push our changes. That’s the same for any branch, not only master. Note that you don’t need to worry about branches that other people are pushing to a remote repo if you’re not working on them.
Faking a Team Member
Since we’re not working on a real project at the moment, let’s fake a team member working on our project, pushing changes. To do that, you can create another folder in your filesystem (outside your current repo, so not a subfolder of it), and clone your remote repo into it by running:
$ git clone [your-remote-url-goes-here]
Now, point to that new repo in your command line tool, make some small changes to any file, then commit and push it:
$ git add . $ git commit -m "some change from cloned repo." $ git push origin master
You should see some output, including Writing objects: 100%.
Integrating Team Members’ Changes
Now, let’s get our command line tool back to point to the first repo we created, the one we started by using
$ git init.
At this point, you should note that this first repo is now outdated, as our remote repo was just updated by another team member. But let’s pretend we don’t know about that, we’re working on our own stuff. So let’s make some other change, to another file (or to the same file but on a different line just so we avoid any conflicts), add it, commit it, and try to push it:
$ git add . $ git commit -m "some change from init repo." $ git push origin master
You should see an error message like:
To [your-remote-url] ! [rejected] master -> master (fetch first) error: failed to push some refs to '[your-remote-url]' hint: Updates were rejected because the remote contains work that you do not have locally.
Yup, that’s expected. Git makes it pretty clear stating that Updates were rejected because the remote contains work that you do not have locally.
So let’s fetch those changes by running
$ git fetch origin. You should see some output, including something like Unpacking objects: 100%. Nice, now our (local) remote branch
origin/master is updated with the contents of our remote repo’s master branch. Let’s merge those changes into our local master branch by running:
$ git merge origin/master
That should launch your system’s default text editor with Git’s default merge commit message, something like Merge remote-tracking branch ‘origin/master’. Just save and close it. If for some reason you get an error message like:
error: There was a problem with the editor 'vi'. Not committing merge; use 'git commit' to complete the merge.
Don’t worry, you just have to commit it manually. In that case just run:
$ git commit -m "Merge remote-tracking branch 'origin/master'"
Nice! Your local master branch is now up to date with
origin/master, and ready to be pushed, so let’s do that:
$ git push origin master
You should see a successful message, including Writing objects: 100%.
And that’s it for remote branches. That’s a pretty common flow that you’re probably going through when working on a remote repo alongside other people.
Remember: you only have to worry about merging remote changes if there were changes pushed to the remote repo by another person, so changes that you do not have in your local repo, and if they changed branches that you’re working on.
Now, let’s take a look at a closely related topic: tracking branches.
What Are Tracking Branches?
“Tracking branches are local branches that have a direct relationship to a remote branch. If you’re on a tracking branch and run git push, Git automatically knows which server and branch to push to.” (Chacon 57)
A tracking branch is just your regular local branch, but with some extra tracking information. It tells your local branches to track remote branches.
Trying to Push, the Short Version
Let’s continue playing with our local repo. Make sure that you point your command line tool to your local repo that you started by running
$ git init, not the one you cloned (this is important). Now, change some file, add and commit it. Now, just try to run
$ git push. You should see an error message like:
fatal: The current branch master has no upstream branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin master
That means Git doesn’t know where to push your local branch to. It doesn’t know which remote repo to use, and how it should name it in the target repo (you can push your local master branch using a different name, Git doesn’t assumes you want to use the same name).
Pushing, the Long Version
So far, we’ve been running
push like so:
$ git push origin master
That tells Git to push our current branch to our
origin remote and name it
master. If such branch exists in our remote repo, it’s updated, otherwise it’s created.
But we’re looking for a short version of that. And that’s why we need tracking branches.
Creating Tracking Branches
Let’s make our local master branch track our remote master branch. Git told us how to do that in that error message:
$ git push --set-upstream origin master
But there’s a shorthand for that command:
$ git push -u origin master
You can do that at any time. If you don’t have local changes to push, Git returns a message like Everything up-to-date as usual, but in this case, since we’re providing a
-u parameter it also returns a message like Branch master set up to track remote branch master from origin. Nice, looks like it worked! Do you think so?
Pushing, the Short Version
Let’s make sure that worked. Let’s make one more change to any file, add and commit it. Now, let’s try to push it the short version, without providing
$ git push
You should see a regular success message. Awesome! Now you have your master branch tracking your remote master branch, and can easily pull and push to it without having to provide
branch-name every time. You can do the same for pull, running just
$ git pull. Nice, huh?
Creating New Tracking Branches
When you create new branches, you can append
-u when you first push it to your remote repo, like:
$ git push -u your-remote-name your-branch-name
There’s no problem if you forget to do that the first time you push your new branch to your remote repo, you can do that at any time.
More Advantages of Using Tracking Branches
Besides being able to run
pull in a short form, another advantage of having tracking branches is that they show you when you are ahead or behind your remote branch when you run
$ git status, meaning you need to push your changes, or pull someone else’s changes. The following is a typical output of
$ git status from an unchaged local master branch that IS NOT a tracking one:
On branch master nothing to commit, working tree clean
But if that branch was a tracking one, you’d see something like:
On branch master Your branch is up-to-date with 'origin/master'. nothing to commit, working tree clean
Did you notice that extra line? It says your branch is up-to-date with your remote branch. But there’s a gotcha here: if someone else updates your remote repo, you’ll still get that message, because Git is looking at your local remote branch (
remotes/origin/master), not going to your remote repo to look at that branch there. In that case, if you run
$ git fetch your local remote branch will be updated, then if you run
$ git status again, you should see something like:
On branch master Your branch is behind 'origin/master' by 2 commits, and can be fast-forwarded. (use "git pull" to update your local branch) nothing to commit, working tree clean
Git tells you that you’re behind
origin/master, and that you can run
$ git pull to update your local branch.
Now, when you make local changes, commit them, and run
$ git status before pushing your changes, you should see a message like:
On branch master Your branch is ahead of 'origin/master' by 1 commit. (use "git push" to publish your local commits) nothing to commit, working tree clean
Git tells you that you’re ahead of
origin/master, and that you can run
$ git push to update your remote branch with your local changes.
A Tracking Branch For Free When Cloning
One thing to note is that when you clone a repo, Git creates a remote branch on your new local repo for each branch that exists in that remote repo. It also creates your local default master branch, as it does when we start a repo by running
$ git init. But since it also adds a
origin remote for you (a reference to a remote repo), pointing to that remote repo you cloned, it goes even further and sets up your just created local master branch to track your remote master branch, which points to your
origin remote. Nice, isn’t it? And how nice is getting to know some of the things Git does behind the scenes for us?
When You Need to Work On Another Guy’s Branch
Let’s picture a scenario where you just cloned a repo that contains some branches created by some team members. When you clone a repo, Git creates remote branches for you automatically, remember? But it doesn’t create local branches for you except master. So, let’s consider you have to do some work on one of those remote branches, say
new-feature-a, started by another guy.
Let’s pretend you see the following when you run
$ git branch -a in that hypothetical repo:
* master remotes/origin/master remotes/origin/new-feature-a remotes/origin/new-feature-b
Ok, so you know there is a
new-feature-a branch created in your remote repo by someone else, and you need to work on it, but you don’t have such local branch yet. In that case, what you want is kind of a clone of that remote branch as a local branch, and why not, having it as a tracking branch of that remote one. That looks like a few things to do, but you can do all of them with a single command:
$ git checkout -b [your-local-branch-name] [remote-name/branch-name]
Note that you can name your local branch anything you want, but most of the times you’ll want to match your remote branch’s name. In our hypothetical case, we do so by running:
$ git checkout -b new-feature-a origin/new-feature-a
You should see an output like:
Branch new-feature-a set up to track remote branch new-feature-a from origin. Switched to a new branch 'new-feature-a'
That command creates a local
new-feature-a branch with the same content of
origin/new-feature-a, and makes it a tracking branch of
That’s it. You can now say that you know what remote and tracking branches are! Cool, right? But don’t worry if things are still a little confusing. As a next step you should practice it a lot. Play with commands, create repositories, branches, merges, conflicts (and solve them!), and hopefully everything will look more natural in a few days.
Chacon, Scott. Pro Git. Apress, 2009.