.5 Git Branching - Remote Branches
Remote branches 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. Remote branches act as bookmarks to remind you where the branches on your remote repositories were the last time you connected to them.
They take the form
(remote)/(branch). For instance, if you wanted to see what the
master branch on your
origin remote looked like as of the last time you communicated with it, you would check the
origin/master branch. If you were working on an issue with a partner and they pushed up an
iss53 branch, you might have your own local
iss53 branch; but the branch on the server would point to the commit at
This may be a bit confusing, so let’s look at an example. Let’s say you have a Git server on your network at
git.ourcompany.com. If you clone from this, Git automatically names it
origin for you, pulls down all its data, creates a pointer to where its
master branch is, and names it
origin/master locally; and you can’t move it. Git also gives you your own
master branch starting at the same place as origin’s
master branch, so you have something to work from (see Figure 3-22).
Figure 3-22. A Git clone gives you your own master branch and origin/master pointing to origin’s master branch.
If you do some work on your local master branch, and, in the meantime, someone else pushes to
git.ourcompany.com and updates its master branch, then your histories move forward differently. Also, as long as you stay out of contact with your origin server, your
origin/master pointer doesn’t move (see Figure 3-23).
Figure 3-23. Working locally and having someone push to your remote server makes each history move forward differently.
To synchronize your work, you run a
git fetch origin command. This command looks up which server origin is (in this case, it’s
git.ourcompany.com), fetches any data from it that you don’t yet have, and updates your local database, moving your
origin/master pointer to its new, more up-to-date position (see Figure 3-24).
Figure 3-24. The git fetch command updates your remote references.
To demonstrate having multiple remote servers and what remote branches for those remote projects look like, let’s assume you have another internal Git server that is used only for development by one of your sprint teams. This server is at
git.team1.ourcompany.com. You can add it as a new remote reference to the project you’re currently working on by running the
git remote add command as we covered in Chapter 2. Name this remote
teamone, which will be your shortname for that whole URL (see Figure 3-25).
Figure 3-25. Adding another server as a remote.
Now, you can run
git fetch teamone to fetch everything the remote
teamone server has that you don’t have yet. Because that server is a subset of the data your
origin server has right now, Git fetches no data but sets a remote branch called
teamone/master to point to the commit that
teamone has as its
master branch (see Figure 3-26).
Figure 3-26. You get a reference to teamone’s master branch position locally.
When you want to share a branch with the world, you need to push it up to a remote that you have write access to. Your local branches aren’t automatically synchronized to the remotes you write to — you have to explicitly push the branches you want to share. That way, you can use private branches for work you don’t want to share, and push up only the topic branches you want to collaborate on.
If you have a branch named
serverfix that you want to work on with others, you can push it up the same way you pushed your first branch. Run
git push (remote) (branch):
$ git push origin serverfix Counting objects: 20, done. Compressing objects: 100% (14/14), done. Writing objects: 100% (15/15), 1.74 KiB, done. Total 15 (delta 5), reused 0 (delta 0) To firstname.lastname@example.org:schacon/simplegit.git * [new branch] serverfix -> serverfix
This is a bit of a shortcut. Git automatically expands the
serverfix branchname out to
refs/heads/serverfix:refs/heads/serverfix, which means, “Take my serverfix local branch and push it to update the remote’s serverfix branch.” We’ll go over the
refs/heads/ part in detail in Chapter 9, but you can generally leave it off. You can also do
git push origin serverfix:serverfix, which does the same thing — it says, “Take my serverfix and make it the remote’s serverfix.” You can use this format to push a local branch into a remote branch that is named differently. If you didn’t want it to be called
serverfix on the remote, you could instead run
git push origin serverfix:awesomebranch to push your local
serverfix branch to the
awesomebranch branch on the remote project.
The next time one of your collaborators fetches from the server, they will get a reference to where the server’s version of
serverfix is under the remote branch
$ git fetch origin remote: Counting objects: 20, done. remote: Compressing objects: 100% (14/14), done. remote: Total 15 (delta 5), reused 0 (delta 0) Unpacking objects: 100% (15/15), done. From email@example.com:schacon/simplegit * [new branch] serverfix -> origin/serverfix
It’s important to note that when you do a fetch that brings down new remote branches, you don’t automatically have local, editable copies of them. In other words, in this case, you don’t have a new
serverfix branch — you only have an
origin/serverfix pointer that you can’t modify.
To merge this work into your current working branch, you can run
git merge origin/serverfix. If you want your own
serverfix branch that you can work on, you can base it off your remote branch:
$ git checkout -b serverfix origin/serverfix Branch serverfix set up to track remote branch refs/remotes/origin/serverfix. Switched to a new branch "serverfix"
This gives you a local branch that you can work on that starts where
Checking out a local branch from a remote branch automatically creates what is called a tracking branch. Tracking branches are local branches that have a direct relationship to a remote branch. If you’re on a tracking branch and type
git push, Git automatically knows which server and branch to push to. Also, running
git pull while on one of these branches fetches all the remote references and then automatically merges in the corresponding remote branch.
When you clone a repository, it generally automatically creates a
master branch that tracks
origin/master. That’s why
git push and
git pull work out of the box with no other arguments. However, you can set up other tracking branches if you wish — ones that don’t track branches on
origin and don’t track the
master branch. The simple case is the example you just saw, running
git checkout -b [branch] [remotename]/[branch]. If you have Git version 1.6.2 or later, you can also use the
$ git checkout --track origin/serverfix Branch serverfix set up to track remote branch refs/remotes/origin/serverfix. Switched to a new branch "serverfix"
To set up a local branch with a different name than the remote branch, you can easily use the first version with a different local branch name:
$ git checkout -b sf origin/serverfix Branch sf set up to track remote branch refs/remotes/origin/serverfix. Switched to a new branch "sf"
Now, your local branch sf will automatically push to and pull from origin/serverfix.
Suppose you’re done with a remote branch — say, you and your collaborators are finished with a feature and have merged it into your remote’s
master branch (or whatever branch your stable codeline is in). You can delete a remote branch using the rather obtuse syntax
git push [remotename] :[branch]. If you want to delete your
serverfix branch from the server, you run the following:
$ git push origin :serverfix To firstname.lastname@example.org:schacon/simplegit.git - [deleted] serverfix
Boom. No more branch on your server. You may want to dog-ear this page, because you’ll need that command, and you’ll likely forget the syntax. A way to remember this command is by recalling the
git push [remotename] [localbranch]:[remotebranch] syntax that we went over a bit earlier. If you leave off the
[localbranch] portion, then you’re basically saying, “Take nothing on my side and make it be