Usage

Refer well documented gitFlow Cheat Sheet for details.

Getting started

Read gitflow-avh wiki first.

GitFlow Commands

Initialization

# on a newly created git master branch, do:
git flow init -d

Remember:

You have to do this every time you clone a repo.

Features

Create a Feature Branch
If you are creating a new feature branch, do this:
```
git flow feature start <feature-name> [<base>]
```
If you are starting to work on an existing feature branch started by another developer, do this:
```
git flow feature track <feature-name>
```
Remember:
- For feature branches, the <base> arg must be develop branch commit sha-1. when omitted it defaults to the develop branch head.
- All new work (new features, non-emergency bug fixes) must be done in a new feature branch.
- Give your feature branches sensible names. If you’re working on a ticket, use the ticket number as the feature branch name (e.g. ticket-1234).

Publish The Feature Branch changes to remote

Publish a feature to the remote server so it can be used by other colleagues.

 git flow feature publish <feature-name>
 # or, if you already are into the feature/<feature-name> branch, just issue:
 git flow feature publish

Keep Up To Date
You’ll need to bring down completed features & hotfixes from other developers, and merge them into your feature branch regularly. (Once a day, first thing in the morning, is a good rule of thumb).
```
 # pull down master and develop branches
 git pull --all
 # merge develop into your feature branch
 git merge develop
 # Push your comits back to remote feature branch
 git push
```
Create PR to merge your feature branch into develop branch
From GitHub or BitBucket website, create a pull request to develop branch fromfeature/<feature-name>.
Ask a colleague to review your pull-request; don’t accept it yourself unless you have to. Once the pull request has been accepted, close your feature using the HubFlow tools:
```
 git flow feature finish <feature-name>
```

Releases

Start a release
When you have enough completed features, create a release branch:
```
 git pull --all
 git flow release start <version-number> [<base>]
 # optionally publish release
 git flow release publish
 # commit any release related changes and push for CI to trigger actions
```
Once you’ve created the release branch,
- Create Changelog. Preferable automate this task in CI environment triggered on every push to release/* branch
- Build the code in the release branch, deploy it into test environments, find bugs.
- Fix the bugs directly inside the release branch.
- deploy -> test -> fix -> redeploy -> retest cycle continues until you’re happy that the release is good enough to release to customers.
Finish up a release
When you’re ready to tag the release and merge it back into master and develop branches, do this:
```
 git flow release finish <version-number>
 # Don't forget to push your tags, run
 git push --all
 git push origin --tags
```
This closes the release branch and creates a tag called <version-number> against the master branch.
Remember:
- For release branches, the <base> arg must be develop branch commit sha-1. when omitted it defaults to the develop branch head.
- Release branches are given version numbers for name. For example: git flow release start 0.1.0
- Don't forget to push your tags after finishing the release

Hotfixes

Creating Hotfix branch
A hotfix is a special kind of release. Unlike features and releases (which are branched from develop), hotfixes are branched from corresponding tag on the master branch. Use hotfix when you want to make and release an urgent change to your latest released code, and you don’t want the changes currently in develop to ship yet.
```
 git pull --all
 git flow hotfix start <version-number> [<base>]
 # to create a hotfix off of an older tag
 git flow hotfix start 0.1.1 [0.1.0]
```
Once you’ve created the hotfix branch,
- Create Changelog. Preferable automate this task in CI environment triggered on every push to hotfix/* branch
- Build the code in the hotfix branch, deploy it into test environments, find bugs.
- Fix the bugs directly inside the hotfix branch.
- deploy -> test -> fix -> redeploy -> retest cycle continues until you’re happy that the release is good enough to release to customers.
Finishing Hotfix
When you’re ready to tag the hotfix and merge it back into master and develop branches, do this:
```
 git flow hotfix finish <version-number>
 # Don't forget to push your tags with
 git push --all
 git push origin --tags
```
This closes the hotfix branch and creates a tag called <version-number> against the master branch.
Remember:
- For hotfix branches, the <base> arg must be master branch, when omitted it defaults to the master branch.
- You can use git flow hotfix start <version-number> <older-tag> to create a hotfix off of an older tag.
- However, if you look back at Vincent’s original diagram, notice how changes happen in time order.
  When you finish this kind of hotfix, it gets merged back into the latest master branch; it does not get merged into just after the tag that you branched off. This can cause problems, such as master ending up with the wrong version number, which you will have to spot and fix by hand for now.

Reference

PreviousInstallation NextConcepts

Last updated 4 years ago

Getting started

Read gitflow-avh wiki first.

GitFlow Commands

Initialization

# on a newly created git master branch, do:
git flow init -d

Remember:

You have to do this every time you clone a repo.

Features

Create a Feature Branch

If you are creating a new feature branch, do this:

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

If you are starting to work on an existing feature branch started by another developer, do this:

git flow feature track <feature-name>

Remember:

For feature branches, the <base> arg must be develop branch commit sha-1. when omitted it defaults to the develop branch head.
All new work (new features, non-emergency bug fixes) must be done in a new feature branch.
Give your feature branches sensible names. If you’re working on a ticket, use the ticket number as the feature branch name (e.g. ticket-1234).

Publish The Feature Branch changes to remote

Publish a feature to the remote server so it can be used by other colleagues.

 git flow feature publish <feature-name>
 # or, if you already are into the feature/<feature-name> branch, just issue:
 git flow feature publish

Keep Up To Date

You’ll need to bring down completed features & hotfixes from other developers, and merge them into your feature branch regularly. (Once a day, first thing in the morning, is a good rule of thumb).

 # pull down master and develop branches
 git pull --all
 # merge develop into your feature branch
 git merge develop
 # Push your comits back to remote feature branch
 git push

Create PR to merge your feature branch into develop branch

From GitHub or BitBucket website, create a pull request to develop branch fromfeature/<feature-name>.

Ask a colleague to review your pull-request; don’t accept it yourself unless you have to. Once the pull request has been accepted, close your feature using the HubFlow tools:

 git flow feature finish <feature-name>

Releases

Start a release

When you have enough completed features, create a release branch:

 git pull --all
 git flow release start <version-number> [<base>]
 # optionally publish release
 git flow release publish
 # commit any release related changes and push for CI to trigger actions

Once you’ve created the release branch,

Create Changelog. Preferable automate this task in CI environment triggered on every push to release/* branch
Build the code in the release branch, deploy it into test environments, find bugs.
Fix the bugs directly inside the release branch.
deploy -> test -> fix -> redeploy -> retest cycle continues until you’re happy that the release is good enough to release to customers.

Finish up a release

When you’re ready to tag the release and merge it back into master and develop branches, do this:

 git flow release finish <version-number>
 # Don't forget to push your tags, run
 git push --all
 git push origin --tags

This closes the release branch and creates a tag called <version-number> against the master branch.

Remember:

For release branches, the <base> arg must be develop branch commit sha-1. when omitted it defaults to the develop branch head.
Release branches are given version numbers for name. For example: git flow release start 0.1.0
Don't forget to push your tags after finishing the release

Hotfixes

Creating Hotfix branch

A hotfix is a special kind of release. Unlike features and releases (which are branched from develop), hotfixes are branched from corresponding tag on the master branch. Use hotfix when you want to make and release an urgent change to your latest released code, and you don’t want the changes currently in develop to ship yet.

 git pull --all
 git flow hotfix start <version-number> [<base>]
 # to create a hotfix off of an older tag
 git flow hotfix start 0.1.1 [0.1.0]

Once you’ve created the hotfix branch,

Create Changelog. Preferable automate this task in CI environment triggered on every push to hotfix/* branch
Build the code in the hotfix branch, deploy it into test environments, find bugs.
Fix the bugs directly inside the hotfix branch.
deploy -> test -> fix -> redeploy -> retest cycle continues until you’re happy that the release is good enough to release to customers.

Finishing Hotfix

When you’re ready to tag the hotfix and merge it back into master and develop branches, do this:

 git flow hotfix finish <version-number>
 # Don't forget to push your tags with
 git push --all
 git push origin --tags

This closes the hotfix branch and creates a tag called <version-number> against the master branch.

Remember:

For hotfix branches, the <base> arg must be master branch, when omitted it defaults to the master branch.
You can use git flow hotfix start <version-number> <older-tag> to create a hotfix off of an older tag.
However, if you look back at Vincent’s original diagram, notice how changes happen in time order.
When you finish this kind of hotfix, it gets merged back into the latest master branch; it does not get merged into just after the tag that you branched off. This can cause problems, such as master ending up with the wrong version number, which you will have to spot and fix by hand for now.