Programming October 30, 2011

Remote branches with TortoiseGit

Git makes branching easy. Coming from other version control systems the work flow isn't always as easy to understand though. Here's what I've found works well when using Tortoise Git.

As a user of TortoiseGit I’ve always been a bit confused when it comes to dealing with remote branches. Git makes it really easy and fast to work with branches compared to many version control systems that aren’t distributed, but coming from the world of TFS or SubVersion where a branch is basically a physical directory that one can check in and check out in Git it’s pretty much just a pointer. This means that a branch is unique to each repository and the workflow when wanting to push a local branch to a remote repository, or the opposite, is a bit different.

The documentation for handling branches using the console is great, but when I’ve been using TortoiseGit I’ve often felt confused and insecure when dealing with remote branches. I therefor decided to do some research and experimentation and document a workflow that seems to work.

Creating a local branch

Given that we’ve created a local repository and added a remote to it, in my case a GitHub repository, we can create a local branch by right clicking in a directory in the repository and pick the Create Branch menu item.

TortoiseGit Create Branch right click menu option

We then get the Create Branch dialog where we enter a name for the branch and hit OK.

TortoiseGit Create Branch dialog

Unless we didn’t check the “Switch to new branch” checkbox in the Create Branch dialog our working directory is still the master branch. To switch to the newly created branch we right click and pick the Switch/Checkout menu item.

TortoiseGit Switch/Checkout right click menu option

In the following dialog we choose our newly created local branch and hit OK.

TortoiseGit Checkout/Switch dialog

Our working directory is now the newly created branch (“branch1” in my case). We can now make some changes and commit them to the local branch. This is reflected in the Commit menu item in TortoiseGit’s right click menu.

TortoiseGit Commit right click menu option

Pushing the local branch to a new remote branch (on GitHub)

When we want to share our local branch with others, or store it in a remote repository to back it up or be able to retrieve it from another computer we need to push. To me this is slightly confusing as pushing it doesn’t mean pushing that actual branch to the remote repository but rather creating a new branch in the remote repository and pushing the changes. To do this we use the Push right click menu option just like we would have if we were working in the master branch.

TortoiseGit Push right click menu option

In the following Push dialog we simply hit OK.

TortoiseGit Push dialog

This is one of the parts that have confused me the most. I’ve always wondered if this didn’t mean that the changes in the local branch wasn’t going to be pushed to the master branch in the remote repository. But looking at the Git Command Progress dialog after hitting OK we see that TortoiseGit pushes the local branch to a branch with the same name in the remote repository which will then be created as it doesn’t yet exist.

TortoiseGit Git Command Progress dialog

After pushing the branch to GitHub (if that’s where our remote repository is) we can see it and switch to it using the Branches button to the right of the page.

GitHub Switch Branches/Tags dialog

After having made some more changes that we’ve committed to our local branch we can push them to the corresponding remote branch using the same workflow.

TortoiseGit Push dialog

As we can see in the Command Progress dialog the changes in our local branch is pushed to the corresponding remote branch.

TortoiseGit Git Command Progress dialog

Fetching the remote branch

When someone else wants to fetch our new branch from the remote repository, our after having switched to another computer or local repository ourselves, we need to fetch the new branch from the remote repository. One might think that this involves first creating a new local branch and then pulling from the remote branch but according to my research that’s not a good idea. Instead, what we want to do is create a new local branch based on the remote branch. We do this by first choosing the Create Branch right click menu option.

TortoiseGit Create Branch right click menu option

In the Create Branch dialog we can name our new branch whatever we want, but to avoid confusion we most likely want to give it the same name as the remote branch. The trick then is to check the Base on/Branch radio button and choose the remote branch.

TortoiseGit Create Branch dialog

After hitting OK we get a confirmation that the new local branch has been created and that it tracks the remote branch. Just like before we also need to either check the “Switch to new branch” checkbox or manually checkout the new branch in order to start working in it.

TortoiseGit Branch set up dialog

After having committed changes to our local branch we can push changes to the remote branch using the Push right click menu option. We need however to make sure that the correct branch is selected in the Remote drop down in the Push dialog.

TortoiseGit Push dialog


Once we want to merge changes in the branch into the master branch we checkout the master branch using the Checkout/Switch right click menu option.

TortoiseGit Checkout/Switch dialog

We then use the Merge right click menu option…

TortoiseGit Merge right click menu option

…to bring up the Merge dialog where we select to merge from our local branch.

TortoiseGit Merge dialog

With the merge done we can push the changes (the merge) from our local master to the remote master branch.

TortoiseGit Push dialog

The remote repository will then figure out what has happened and if we look at the Network tab in GitHub it will appear as the branch we’ve been working with never existed (more or less).

Deleting the local branch

If we’re done with our branch after having merged it into master, or if we want to discard the branch for some other reason, we can remove the local branch by first opening up the Checkout/Switch dialog to get at the Browse refs dialog.

TortoiseGit Checkout/Switch dialog

In the Browse refs dialog we can right click on the local branch and choose to delete it.

TortoiseGit Browse refs dialog - Delete Local Branch

Deleting the remote branch

To delete a remote branch we can do the same thing, but instead of right clicking on our local branch we expand the remotes tree in the left part of the dialog and then locate the remote branch.

TortoiseGit Browse refs dialog - Delete Remote Branch


I’m no expert at Git (although I hope to be some day) so if you see something wrong in this post don’t hesitate to let me know! This workflow does seem to work well for me though.

PS. For updates about new posts, sites I find useful and the occasional rant you can follow me on Twitter. You are also most welcome to subscribe to the RSS-feed.

Joel Abrahamsson

Joel Abrahamsson

I'm a passionate web developer and systems architect living in Stockholm, Sweden. I work as CTO for a large media site and enjoy developing with all technologies, especially .NET, Node.js, and ElasticSearch. Read more


comments powered by Disqus

More about Programming