git-flow

A collection of Git extensions to provide high-level repository operations for Vincent Driessen's branching model.

Installing git-flow

The easiest way to install git-flow is using Rick Osborne's excellent git-flow installer, which can be run using the following command:

$ wget -q -O - http://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | sudo sh

For OSX users, the wget command isn't available by default, but curl is, so you can run:

$ curl http://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | sudo sh

For Windows users who wish to use the automated install, it is suggested that you install Cygwin first to install tools like sh and wget. Then simply follow the command:

c:\Users\<user> wget -q -O - http://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | sh

If you prefer a manual installation, please use the following instructions. After downloading the sources from Github, also fetch the submodules:

$ git submodule init
$ git submodule update

Then, you can install git-flow, using:

$ sudo make install

By default, git-flow will be installed in /usr/local. To change the prefix where git-flow will be installed, simply specify it explicitly, using:

$ sudo make prefix=/opt/local install

Or simply point your PATH environment variable to your git-flow checkout directory.

Installation note:
git-flow depends on the availability of the command line utility getopt, which may not be available in your Unix/Linux environment. Please use your favorite package manager to install getopt. For Cygwin, install the util-linux package to get getopt.

Integration with your shell

For those who use the Bash or ZSH shell, please check out the excellent work on the git-flow-completion project by bobthecow. It offers tab-completion for all git-flow subcommands and branch names.

For Windows users, msysgit is a good starting place for installing git.

FAQ

• Can I still do manual branches and merges when I use git-flow?
  Of course you can. git-flow does not forbid you to keep using vanilla Git commands!

  So if you want to merge master into develop for whatever reason you want to, you can safely do so without breaking git-flow compatibility. Do you want to manually merge a feature branch X into another feature branch Y? Not a problem. As long as you do it conciously and realize what this means for finishing those branches later on.

• Why does git-describe not work for me?
  When finishing release and hotfix branches, that branch's HEAD is first merged into master and then into develop. It is not the resulting new merge commit from master that is merged back into develop. This means that a linear path from the new develop branch to the new master commit is not created. Even worse, a linear path is created from the new develop branch to the previous master commit. Although unintended, this is simply an effect of using the current branching rules.

  When using git-describe in these cases, you can get very confusing and misleading results, since git-describe scans the current commits linear history for the most recent tag it finds, which will always be the previous tag.

  I will change this behaviour in the next version of the branching model explicitly and I will include this behavioural change in the first version of the Python rewrite.

  For more references to this problem, see:

  • Issue #49
  • These two discussions on the git-flow-users mailinglist.

• I'm getting errors when I use flags with git-flow!
  git-flow uses the shFlags library to provide platform independent flag parsing (using wichever low-level flag parsing libraries like getopt or getopts are available). However, shFlags does not work too well on a few platforms that haven't been tested originally. This results in errors like this:

  flags:WARN getopt: option invalide -- 'f' -- 'init' flags:FATAL unable to parse provided options with getopt
  

  The platforms that suffer these errors include:

  • Gentoo
  • Ubuntu
  • Redhat Enterprise Linux

  There are open issues related to this: #28 and #39. Unfortunately, there is no simple fix for it and all hope is placed on the Python rewrite of git-flow, see issue #33.

Please help out

This project is still under development. Feedback and suggestions are very welcome and I encourage you to use the Issues list on Github to provide that feedback.

Feel free to fork this repo and to commit your additions. For a list of all contributors, please see the AUTHORS file.

Any questions, tips, or general discussion can be posted to our Google group: http://groups.google.com/group/gitflow-users

License terms

git-flow is published under the liberal terms of the BSD License, see the LICENSE file. Although the BSD License does not require you to share any modifications you make to the source code, you are very much encouraged and invited to contribute back your modifications to the community, preferably in a Github fork, of course.

Typical usage:

For the best introduction to get started to git flow, please read Jeff Kreeftmeijer's blog post:

http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/

Initialization

To initialize a new repo with the basic branch structure, use:

	git flow init

This will then interactively prompt you with some questions on which branches you would like to use as development and production branches, and how you would like your prefixes be named. You may simply press Return on any of those questions to accept the (sane) default suggestions.

Creating feature/release/hotfix/support branches

• To list/start/finish feature branches, use:

    git flow feature
    git flow feature start <name> [<base>]
    git flow feature finish <name>
  

  For feature branches, the <base> arg must be a commit on develop.

• To list/start/finish release branches, use:

    git flow release
    git flow release start <release> [<base>]
    git flow release finish <release>
  

  For release branches, the <base> arg must be a commit on develop.

• To list/start/finish hotfix branches, use:

    git flow hotfix
    git flow hotfix start <release> [<base>]
    git flow hotfix finish <release>
  

  For hotfix branches, the <base> arg must be a commit on master.

• To list/start support branches, use:

    git flow support
    git flow support start <release> <base>
  

  For support branches, the <base> arg must be a commit on master.

Showing your appreciation

A few people already requested it, so now it's here: a Flattr button.

Of course, the best way to show your appreciation for the original blog post or the git-flow tool itself remains contributing to the community. If you'd like to show your appreciation in another way, however, consider Flattr'ing me: