Smart branching with SourceTree and Git-flow

By on August 1, 2012

Note: for brevity this article refers to Git and git-flow, but SourceTree supports exactly the same concepts in Mercurial via Hg Flow too.

In early 2010, Vincent Driessen wrote an article called “A successful Git branching model” which recommended an approach called git-flow to use git branches in your development cycle. The idea was to standardise branching and merging when developing features, handling releases and managing hot fixes, in order to be consistent and gain the advantages of git’s ‘branchy’ development model. Using many separate branches in Git gives you lots of flexibility, but it can get complex. Adopting a standardised approach has many advantages:

SourceTree 1.5 now integrates with git-flow and presents it to you in a friendly and intuitive way.

Summary of the concept

The general idea of git-flow is to use the following branch structure in your repository:

SourceTree helps you utilise these branches via git-flow actions which we will describe below.

Getting started with git-flow

There’s a handy new addition to the toolbar in SourceTree 1.5 (keyboard shortcut Cmd-Alt-F):

Based on the current state of the repository, the Git-flow button will bring up a dialog with the most likely action you’d want to perform next. So if you haven’t set up git-flow on this repo yet, it’ll help you do that by default. If you’re on the development branch, it will default to starting a new feature. If you’re already on a feature branch, it will offer to finish your current feature and merge it back into the development branch, and so on. You can always get to all the other git-flow actions via this button as well, but most of the time the default option will be the action you’ll want SourceTree to perform.

If you haven’t used git-flow already on this repository, the first thing SourceTree will do is initialise your repository to use it. You’ll probably just want to use the defaults in the initialisation window so that’s not covered here. For more details please see the Help section included in SourceTree. Next up, we’ll concentrate on the actions we can perform with Git-flow and SourceTree.

Starting a feature

You can commit trivial changes directly to the development branch (‘develop’) if you like, but any time you start on something non-trivial you should explicitly start a new feature. This ‘Start Feature’ action will be the default action when you click the Git-flow button if you are currently on the dev branch.

The first thing to note is the ‘Preview’ window, which is present on all of the action dialogs and shows you what will actually happen when you confirm the dialog. In this case, a new feature branch called ‘feature/my-new-feature’ will be created (I used the default prefix when I initialised this repository). You commit your feature implementations to this branch. If you want, you can push the feature branch to your remote while you work on it (your team can decide on whether that’s normal practice or not).

If at any time you want to switch branches, either to another feature branch or to somewhere else, just use the normal mechanisms in SourceTree to do that, such as double-clicking a log entry or a branch in the sidebar. Git-flow determines your context simply from the branch you currently have checked out, so it’s fine to jump around if you like.

Finishing a feature

Eventually when you’re done implementing a feature, use the ‘Finish Feature’ action (again, this will be the default action from the toolbar button if you’re on a feature branch):

Again, the Preview shows you what will happen — the feature branch will merge into the main development branch, essentially queueing it for inclusion in the next release. Feature branches are deleted by default but you can opt to retain them if you like.

Starting a release

You start a release branch when you want to start preparing a new release, which probably coincides with a feature freeze. Accessing the Start Release option –either from the menu or from the toolbar action selection window — brings up the following dialog:

The preview shows that a new release branch will be created. Most of the time, you want to start the release from the latest commit in the development branch, but you can choose to base it on another commit if you wish. This essentially freezes the release, so it’s not affected by subsequent development. You can also perform preparatory tasks for the release process on this branch, such as updating the version number in source files, updating changelogs, or committing other tweaks. Once these tweaks are done, you can finish the release as described below.

Finishing a release

Once all the adjustments required for the release are done and committed, you can conclude the release process.If you’re on the release branch already, the git-flow button will show you the following dialog:

The preview illustrates that the release branch will be merged into the production branch (‘master’ or ‘default’ normally) to indicate an update to the deployed version. Sourcetree will also create a tag here for the release. The release branch changes will also merge back into the development branch to make sure the develop branch is kept up to date.

Starting a hotfix

What if you need to just fix a bug on the latest release? You don’t want to create a new release, because that will pick up the recent changes from the development branch. So instead, you can start a hot fix:

Hot fixes always start from the latest production code from the ‘master’ or ‘default’ branch. Other than that, they’re basically the same as release branches. Moreover, when you’re finished with the hot-fix, they behave the same way as finishing a release branch. The changes are merged back into both the production branch and the development branch, and a tag is created on the production branch for the hot fix release.

Wrapping up

Git-flow is a great way to automate your handling of branch-based development in Git, and SourceTree now provides a simple and clear way to use it with an easy-to-use and intuitive GUI. Big thanks to Vincent Driessen for coming up with git-flow in the first place!

Try the Git-flow workflow yourself with Sourcetree 1.5!


  • Posted August 1, 2012 at 1:49 pm | Permalink

    A real pity that you only offer Git-flow for Mac OS X and neither for Windows nor for Linux.

    • Jeffrey J. Hoover
      Posted August 1, 2012 at 2:29 pm | Permalink

      an interesting reversal of the common practice of releasing for windows first and mac later (maybe)…

    • asdf
      Posted August 2, 2012 at 1:09 am | Permalink

      No real developers use Windows anymore.  This is why.  There’s no “GitHub for Linux” or “GitHub for Windblows” either.

      • Posted August 2, 2012 at 2:43 am | Permalink

        You are wrong, there is GitHub for Windows

      • Posted May 21, 2013 at 7:34 am | Permalink

        Your hideous neckbeard is showing.

      • asdf
        Posted May 4, 2014 at 11:32 am | Permalink

        Obvious fanboy. No serious programmer uses OSX, a designer maybe.

        • Isuru
          Posted October 24, 2014 at 2:37 pm | Permalink

          So what about iOS developers out there? Your ignorance and narrow minded attitude amazes me.

        • Simon Lee
          Posted August 3, 2015 at 2:12 pm | Permalink

          I do, and have made over £2m doing so. I’d say that was pretty serious.

      • Mekku
        Posted August 7, 2014 at 1:35 am | Permalink

        Does it really matter what OS or platform you’re on?
        Seems like pointless arguing to me.

        All that matters are your developer skills and mindset. Carry on!

      • kamal
        Posted April 20, 2015 at 2:58 am | Permalink

        You are narrow minded!

      • Felix
        Posted June 5, 2015 at 6:50 am | Permalink

        Elitist twat – get off your high horse. Real developers use whatever suits them best.

    • asdf
      Posted August 2, 2012 at 1:13 am | Permalink

      git itself wasn’t available for windows for _years_ after it was introduced.  Nobody cared.  Windows is for old people and big slow stagnant corporations.

      • Timbo
        Posted July 24, 2014 at 6:00 pm | Permalink

        Like stackoverflow?

  • Joel Parker Henderson
    Posted August 1, 2012 at 4:12 pm | Permalink

    I will pay money for this on Linux.

    • Posted August 2, 2012 at 12:26 pm | Permalink

      How much money?

    • A
      Posted December 10, 2012 at 5:46 pm | Permalink

      This is already made for linux and windows and osx.. the git flow is set of scripts that you can get and install.. then use via command line like git flow feature start alabala.. sourcetree is a git gui that will issue those command for you.

  • Torger Wuellner
    Posted August 2, 2012 at 7:04 am | Permalink

    For Hg, the main branch for development is typically “default.” Is there a reason the GUI is setting production to “default” or “master” when initializing the flow?

    • Anonymous
      Posted August 2, 2012 at 7:14 am | Permalink

      When using hg-flow, ‘default’ is the production branch, not the development branch, just like the production branch is ‘master’ on git-flow. In both the recommended style is to use a new branch called ‘develop’ for development. SourceTree defaults to these conventions because git-flow and hg-flow use them.

  • infotexture
    Posted September 11, 2012 at 3:24 pm | Permalink

    Git Flow and Subversion

    Any chance SourceTree might be able to support a git-flow workflow for Git clones of Subversion repositories?

    Git-flow uses the `–no-ff` flag to ensure that a merge commit is always created to preserve the information about the historical existence of a feature branch, but this approach conflicts with the recommendation for git-svn to avoid such merge commits by rebasing.

    Could SourceTree include some logic that would enforce the use of the `–no-ff` flag when starting and finishing features, yet still default to rebasing whenever a feature or release branch is pushed upstream to the `git-svn` remote?

    • Anonymous
      Posted September 12, 2012 at 1:47 am | Permalink

      You could make this work for features by selecting the ‘rebase’ option when finishing a feature, but in general git-flow and git-svn are just not very compatible, because hotfixes always need to use merging, and as you know git merges can’t be sent to Subversion.

      Maybe you could track your git-svn branch in a completely different local branch, called ‘svn-upstream- or similar, then work with git-flow in the usual branches, then when you want to send things upstream do a git merge –squash (not exposed in SourceTree yet though) into the svn-upstream branch, replicating the changes without needing the merge metadata.

      Generally though, I think I’d have to consider git-svn to be fundamentally incompatible with git-flow. Another reason to encourage the masters of the upstream repo to switch to DVCS 😉

  • Brian Clear
    Posted January 3, 2013 at 10:00 am | Permalink

    spent two day cramming hg/hg flow and sourcetree… so far so good. one problem I have though is when I finish a release the TAG WITH THIS MESSAGE is greyed out. in the screenshot above theyre enabled. I thought one of the tenet so Hg/git Flow was to tag the default/master when you finish a release or do I finish then tag default. I presume its the tagged default branch is where I ultimately package up my code for the App Store say?
    I’ve tested on two separate repos.

    • Anonymous
      Posted January 3, 2013 at 10:21 am | Permalink

      This is actually because hg-flow doesn’t support messages on tags right now. The same UI is used for git-flow and hg-flow but some options are disabled where they’re not available.

      • Brian Clear
        Posted January 4, 2013 at 2:38 am | Permalink

        ok cheers. One other thing I noticed while using it is that it would be nice to assign a color to branches ourselves. the light blue and light pink swap when you switch branch. Not a problem when you are on the main screen as I only switch branches using the toolbar on the left. But when you click on merge youre only shown the revisions table and asked to pick a branch to merge in. The graph lines on the left also move around so can be confusing. Is there a bug site/wishlist site? cheers. Also adding support for DeltaWalker for diff would be good too.

        • Anonymous
          Posted January 5, 2013 at 4:31 am | Permalink

          Yes, this has been requested once before, you can add your 2c and/or upvote the feature request here (backlog priorities are very much influenced by the number of user requests):

          I did try to support Deltawalker once before but found it to be very unreliable and buggy, such that I didn’t want to officially stand behind it as fully supported. This was a while ago now though. You can actually add it yourself by using the ‘Other’ option and providing the settings yourself – any diff/merge tool can be configured that way.

          • Mark
            Posted June 29, 2013 at 1:35 am | Permalink

            You can actually add it yourself by using the ‘Other’ option and providing the settings yourself – any diff/merge tool can be configured that way.

            a very good thought, +100500

  • Muhammad Ishaq
    Posted July 9, 2013 at 1:50 pm | Permalink

    has a small issue. am using on windows.

    when finishing a feature (merging back to develop) it always goes for fast-forward if possible even if you have disabled it in the preferences, this has the adverse affect of losing branch history. may be it’s just me. am doing Git Flow manually for now.

    • Anonymous
      Posted July 10, 2013 at 8:36 am | Permalink

      Yeah, it’s in the git-flow code to fast-forward on feature finish if there have been no changes in the destination branch, there’s no option to turn that off in the git-flow script hence why the ST option doesn’t affect it.

      • Muhammad Ishaq
        Posted July 10, 2013 at 9:06 am | Permalink

        Thank you for reply Steve, that explains it. so should I file this as an issue with gitflow script on GitHub? no idea why Vincent said “no fast forwards” in the blog post and didn’t do it in the script 🙂

  • Sivakumar Kailasam
    Posted August 1, 2013 at 8:13 pm | Permalink

    Is it possible to finish a feature/release/hot-fix with a pull request instead of directly merging it?

    • Ciprian Diaconasu
      Posted September 22, 2013 at 7:49 am | Permalink

      Yes, we would need this too, because how are we able to do code reviews if the code is merged on develop with no pull request from the feature branch to develop?

      • Anonymous
        Posted September 23, 2013 at 2:18 am | Permalink

        You can do this with SourceTree for Mac 1.7 and SourceTree for Windows 1.2. Just submit a pull request from within SourceTree and when the pull request is accepted, your fetch will bring that merge in to your local copy, effectively finishing the feature.

        • Ciprian Diaconasu
          Posted September 23, 2013 at 3:22 am | Permalink

          Thanks for the tip!

        • Brandon Paluzzi
          Posted August 13, 2014 at 7:26 am | Permalink

          Sorry to resurrect this thread from the dead — quick question on this flow though. If I create a pull request from a feature, GitHub is always trying to merge into “master”, instead of into “develop”. It’s easy enough to change on the GitHub interface, but I just wanted to make sure I wasn’t missing something obvious on the SourceTree side.

          • Anonymous
            Posted August 13, 2014 at 7:31 am | Permalink

            This is the default GitHub behaviour, if the target project is git-flow based then you want to change the default branch to ‘develop’ in the Settings page on GitHub so that the default merge target for pull requests is develop instead of master.

          • Brandon Paluzzi
            Posted August 13, 2014 at 7:32 am | Permalink

            Holy cow! Thanks so much for the quick response. Much appreciated. Ahhh… that makes sense. We’re just contemplating switching to git-flow, so I’m still getting a handle on the ins and outs. I sent you a tweet as well, please feel free to ignore that. Really really awesome support! Thanks Steve!

  • Joost van der Drift
    Posted December 10, 2013 at 10:40 am | Permalink

    I have an existing HG repository with several feature branches and the ‘default’ branch for production and a ‘Test’ branch which contains several features that are in test but are not ready to go to production yet.
    If I want to start using HG Flow on this repo, how do I deal with the existing branches? I do not want to loose the features included in my ‘Test’ branch.

    • Anonymous
      Posted December 11, 2013 at 2:30 am | Permalink

      You won’t lose any existing branches, it would only be an issue if one of your existing branches had the same name as one of the hgflow ‘special’ branches like develop. Any other branches will remain as normal and you’re free to manually manage those if you want.

      • Joost van der Drift
        Posted December 30, 2013 at 3:02 am | Permalink

        Well I took the plunge…
        and not all went well. The ‘develop’ branch was not created and another branch had many changes, as if SourceTree tried to make that branch the ‘develop’ branch. I could not discard these changes, so I had to commit them.
        After that I was able to create the ‘development’ branch manually from the ‘default’ branch

  • Jatin
    Posted April 29, 2014 at 12:40 am | Permalink

    Hello all,
    i installed Source tree setup and clone my project but now master barch selected in source tree. but i want to change branch. so how to change branch can any help me please

    • Anonymous
      Posted April 29, 2014 at 3:44 am | Permalink

      Please use for community questions in future, but the quickest way to switch branch is just double-click on the branch in the sidebar or in the log.

  • Anonymous
    Posted May 22, 2014 at 4:50 pm | Permalink

    Really enjoying using in lieu of the command line and assorted IDE plugins as it really has simplified the SCM workflow which is significantly enhanced with the addition of the Git-flow workflow too.

  • Medallion
    Posted June 11, 2014 at 12:30 am | Permalink

    I started a feature sometime with git Flow but did not finish it as suppose. Instead I mistakenly right click on the feature and delete it using sourceTree GUI. Now if I try creating new feature, it automatically append the name of that feature I deleted and I’m guessing its because I didn’t finish the feature with git Flow. Please how do I get rid of that feature give that I don’t have it anymore.. as I want my new feature to have it own given name not the name of the previous feature I forgot to finish. Thanks

    • Anonymous
      Posted June 11, 2014 at 2:51 am | Permalink

      Just deleting the branch should have freed up the name for use again. The only problem would be if you’d pushed the branch to your remote, in which case you should delete the remote branch via the interface on your host, e.g. in Bitbucket you can do it in the branches view:

  • Posted September 29, 2014 at 3:39 am | Permalink

    an old blog post… but still useful. Thank you

  • Adam Johns
    Posted April 26, 2015 at 9:38 am | Permalink

    “If you want, you can push the feature branch to your remote while you work on it (your team can decide on whether that’s normal practice or not).” Isn’t not pushing to remote extremely dangerous? What if you’ve been working on a feature for a week and then your computer crashes. If you never pushed to remote you just lost a week’s worth of development. Is there an equally bad possibility of pushing to remote?

  • stevenlehar
    Posted July 6, 2015 at 10:41 am | Permalink

    An issue came up in StackOverflow

    that if e.g. you do an initial commit to [master], followed by a branch to [develop] and perhaps another branch to [feature1] (as suggested in Vincent Dreissen’s A Successful Git-Branching Model) GitFlow shows this as a linear trail, all in blue color, whereas it should actually depict a branching trail that changes color between the nodes. I realize that after you do the merges (merge develop & feature, merge master & develop) the graph looks OK in the end, but it sure is confusing for noobies to branch and branch and to see no new branches on GitFlow.

  • Sly Cooper
    Posted July 19, 2015 at 3:58 pm | Permalink

    Cancelling a hotfix?

    Especially when there is a merge conflict when finishing a hotfix and sourcetree glitches out and you can “finish” the fix over and over and it still won’t disappear locally so you have to manually delete the local hotfix branch…

  • Unicorn Coder
    Posted September 16, 2015 at 2:01 pm | Permalink

    Sometimes when you code. You run into coding problems. Also sometimes it makes you turn into a unicorn. This happens alot. Any help appreciate. thank you

    Posted September 16, 2015 at 2:50 pm | Permalink


  • Sudeep
    Posted February 29, 2016 at 3:06 am | Permalink

    using sourcetree app in IOS ,wehen clone a GIT advance option is not working..

    Any one please help..urgent

  • Josua Hönger
    Posted August 1, 2016 at 1:12 am | Permalink

    I have tried to use this and bumped into the following situation:
    when trying to finish a Release-branch or a hotfix-branch, it will only work if there was meanwhile no change in the develop branch. but in reality, this is almost always the case and Sourctree GitFlow fails. I resolved this by manually merge my Release-branch (or hotfix-branch) to the master first, after that I pull the latest development branch into it, then I marge it to the develop branch (and then I manually delete my Release or hotfix branch)

    Am I doing something wrong here?

13 Trackbacks