GitBreeze, or git-breeze, is a Git hook that will scan your current branch name looking for something it recognizes as a Breeze story number. If it finds one, it will automagically add it, in the special format, to your commit message. It will also move any m: command to the end of the commit so it reads better in the Breeze story comment.


1) Install the git-breeze binary

You need to get the git-breeze binary onto your system.

bash $ gem install git_breeze

2) Initialize the hook

Then you need to initialize the git hook into each local Git repository where you want to use it.

# from inside a local Git repository
# for example: /path/to/repo/
$ git breeze init

This will put the prepare-commit-msg hook in the /path/to/repo/.git/hooks directory and make it executable.

NOTE: The hook needs to be initialized just once for each repository in which you will use it.


With the hook initialized in a repository, create branches being sure to include the Breeze story number in the branch name.

$ git checkout -b a_useful_and_helpful_name_8675309

When you commit, Git will fire the hook which will find the story number in the branch name and prepare your commit message so that it includes the story number in the special Breeze syntax.

# on branch named `best_feature_ever-8675309`
$ git commit

Will result in a commit message something like:

 -- Applies to story #8675309
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch best_feature_ever-8675309
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
# new file:   feature.rb

You should then add a useful and responsible commit message. ❤

Passing commit messages via command line

If you pass a commit message on the command line the hook will still add the story number, preceded by an empty line, to the end of your message, as well as any m: comand you might use.

# on branch named `best_feature_ever-8675309`
$ git commit -m'Look at this rad code, yo! m:done'

Results in this commit message:

Look at this rad code, yo!

 -- Applies to story #8675309 m:done

However, if you include the story number in the Breeze format within your commit message, the hook will do nothing.

# on branch named `best_feature_ever-8675309`
$ git commit -m'#8675309 Look at this rad code, yo!'

Results in this commit message:

#8675309 Look at this rad code, yo!

Valid branch names

GitBreeze allows you to include the story number any where in the branch name, optionally prefixing it with a hash (#). Examples:

  • best_feature_ever_#8675309
  • best-feature-ever-8675309
  • 8675309_best_feature_ever
  • #8675309-best-feature-ever
  • your_name/8675309_best_feature_ever
  • your_name/#8675309_best_feature_ever

Tested with:

  • Command line (-m and with editor -- does not move m:commands)
  • Brackets Git
  • SourceTree


  1. Fork it
  2. Create your feature branch (git checkout -b my_new_feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my_new_feature)
  5. Create new Pull Request