These examples are illustrating the usage of the supported GitFlow workflow
in GitVersion. To enable this workflow, the builtin template
GitFlow/v1 needs to be referenced in the
configuration as follows:
workflow: GitFlow/v1
calculation:
mode: ContinuousDelivery
Where
the continuous deployment mode for no branches,
the continuous delivery mode for
main, support and develop branches and
the manual deployment mode
for release, feature, hotfix and unknown branches are specified.
This configuration allows you to publish CI (Continuous Integration) builds
from main, support and develop branches to an artifact repository.
All other branches are manually published. Read more about this at
version increments.
The continuous delivery mode has been used for the main and the
support branch in this examples (specified as a fallback on the root
configuration layer) to illustrate how the version increments are applied.
In production context the continuous deployment mode might be a better
option when e.g. the release process is automated or the commits are tagged
by the pipeline automatically.
Feature Branches
Feature branches can be used in the GitFlow workflow to implement a
feature in an isolated environment. Feature branches will take the feature
branch name and use that as the pre-release label. Feature branches will be
created from a develop, release, main, support or hotfix branch.
Create feature branch from main
sequenceDiagram
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant feature as feature/foo
main->>feature: branch from main
activate feature
deactivate main
rect rgb(211, 211, 211)
Note over feature: 1.2.1-foo.1+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 1.2.1-foo.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>main: tag 1.2.1
rect rgb(211, 211, 211)
Note over main: 1.2.1
end
main->>feature: merge
deactivate main
rect rgb(211, 211, 211)
Note over feature: 1.2.2-foo.1+2
end
feature->>feature: Commit '+semver: minor'
rect rgb(211, 211, 211)
Note over feature: 1.3.0-foo.1+3
end
feature->>feature: tag 2.0.0-foo.1
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.2+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
feature->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.0.0-PullRequest2.5
end
destroy pull
main--xpull: delete branch
feature->>main: merge
Note over feature: Feature branches should
be deleted once merged
destroy feature
main--xfeature: delete branch
rect rgb(211, 211, 211)
Note over main: 2.0.0-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 2.0.0-6
end
main->>main: tag 2.0.0
rect rgb(211, 211, 211)
Note over main: 2.0.0
end
After the feature branch is merged, the version on main is 2.0.0-5.
This is due to main running in continuous delivery mode. If main was
configured to use continuous deployment the version would be 2.0.0.
Mainline version strategy comparison
The same feature branch history produces different versions when the
Mainline version strategy is
used. In particular, the final untagged commit on main becomes 2.0.1-1
rather than 2.0.0-6:
sequenceDiagram
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.0-1
end
create participant feature as feature/foo
main->>feature: branch from main
activate feature
deactivate main
rect rgb(211, 211, 211)
Note over feature: 1.2.1-foo.1+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 1.2.1-foo.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>feature: merge
deactivate main
rect rgb(211, 211, 211)
Note over feature: 1.2.2-foo.1+2
end
feature->>feature: Commit '+semver: minor'
rect rgb(211, 211, 211)
Note over feature: 1.3.0-foo.1+3
end
feature->>feature: tag 2.0.0-foo.1
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.2+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
feature->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.0.0-PullRequest2.5
end
destroy pull
main--xpull: delete branch
feature->>main: merge
Note over feature: Feature branches should
be deleted once merged
destroy feature
main--xfeature: delete branch
rect rgb(211, 211, 211)
Note over main: 2.0.0-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 2.0.1-1
end
The other Mainline integration scenarios use the same branch histories as the
examples below, so they are not repeated here. See
DocumentationSamplesForGitFlow.cs
for the complete executable scenarios and their expected versions.
Create feature branch from develop
sequenceDiagram
participant main
participant develop
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
main->>develop: branch from main
activate develop
deactivate main
rect rgb(211, 211, 211)
Note over develop: 1.3.0-alpha.0
end
create participant feature as feature/foo
develop->>feature: branch from develop
activate feature
deactivate develop
rect rgb(211, 211, 211)
Note over feature: 1.3.0-foo.1+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 1.3.0-foo.1+1
end
activate main
main->>main: Commit '+semver: minor'
rect rgb(211, 211, 211)
Note over main: 1.3.0-1
end
main->>main: tag 1.3.0
rect rgb(211, 211, 211)
Note over main: 1.3.0
end
main->>develop: merge
deactivate main
activate develop
rect rgb(211, 211, 211)
Note over develop: 1.4.0-alpha.1
end
develop->>feature: merge
deactivate develop
rect rgb(211, 211, 211)
Note over feature: 1.4.0-foo.1+3
end
feature->>feature: Commit '+semver: major'
rect rgb(211, 211, 211)
Note over feature: 2.0.0-foo.1+4
end
feature->>feature: tag 2.1.0-foo.1
rect rgb(211, 211, 211)
Note over feature: 2.1.0-foo.2+0
end
feature->>feature: commit
rect rgb(211, 211, 211)
Note over feature: 2.1.0-foo.2+1
end
create participant pull as pull/2/merge
develop->>pull: branch from develop
activate pull
feature->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.1.0-PullRequest2.6
end
destroy pull
develop--xpull: delete branch
feature->>develop: merge
Note over feature: Feature branches should
be deleted once merged
destroy feature
develop--xfeature: delete branch
rect rgb(211, 211, 211)
Note over develop: 2.1.0-alpha.6
end
activate develop
develop->>develop: commit
rect rgb(211, 211, 211)
Note over develop: 2.1.0-alpha.7
end
After the feature branch is merged, the version on develop is
1.3.0-alpha.3. This is due to develop running in continuous delivery
mode. If develop was configured to use manual deployment the version
would still be 1.3.0-alpha.1 and you would have to use pre-release tags
to increment the pre-release label alpha.1.
Hotfix Branches
Hotfix branches are used when you need to do a patch release in the
GitFlow workflow and are always created from main branch.
Create hotfix branch
sequenceDiagram
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant hotfix as hotfix/next
main->>hotfix: branch from main
activate hotfix
deactivate main
rect rgb(211, 211, 211)
Note over hotfix: 1.2.1-beta.1+0
end
hotfix->>hotfix: commit
rect rgb(211, 211, 211)
Note over hotfix: 1.2.1-beta.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>main: tag 1.2.1
rect rgb(211, 211, 211)
Note over main: 1.2.1
end
main->>hotfix: merge
deactivate main
rect rgb(211, 211, 211)
Note over hotfix: 1.2.2-beta.1+2
end
hotfix->>hotfix: Commit '+semver: minor'
rect rgb(211, 211, 211)
Note over hotfix: 1.3.0-beta.1+3
end
hotfix->>hotfix: tag 2.0.0-beta.1
rect rgb(211, 211, 211)
Note over hotfix: 2.0.0-beta.2+0
end
hotfix->>hotfix: commit
rect rgb(211, 211, 211)
Note over hotfix: 2.0.0-beta.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
hotfix->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.0.0-PullRequest2.5
end
destroy pull
main--xpull: delete branch
hotfix->>main: merge
Note over hotfix: Hotfix branches should
be deleted once merged
destroy hotfix
main--xhotfix: delete branch
rect rgb(211, 211, 211)
Note over main: 2.0.0-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 2.0.0-6
end
main->>main: tag 2.0.0
rect rgb(211, 211, 211)
Note over main: 2.0.0
end
Create hotfix branch with version number
sequenceDiagram
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant hotfix as hotfix/2.2.1
main->>hotfix: branch from main
activate hotfix
deactivate main
rect rgb(211, 211, 211)
Note over hotfix: 2.2.1-beta.1+0
end
hotfix->>hotfix: commit
rect rgb(211, 211, 211)
Note over hotfix: 2.2.1-beta.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>main: tag 2.2.1
rect rgb(211, 211, 211)
Note over main: 2.2.1
end
main->>hotfix: merge
deactivate main
rect rgb(211, 211, 211)
Note over hotfix: 2.2.2-beta.1+2
end
hotfix->>hotfix: Commit '+semver: major'
rect rgb(211, 211, 211)
Note over hotfix: 3.0.0-beta.1+3
end
hotfix->>hotfix: tag 3.0.1-beta.1
rect rgb(211, 211, 211)
Note over hotfix: 3.0.1-beta.2+0
end
hotfix->>hotfix: commit
rect rgb(211, 211, 211)
Note over hotfix: 3.0.1-beta.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
hotfix->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 3.0.1-PullRequest2.5
end
destroy pull
main--xpull: delete branch
hotfix->>main: merge
Note over hotfix: Hotfix branches should
be deleted once merged
destroy hotfix
main--xhotfix: delete branch
rect rgb(211, 211, 211)
Note over main: 3.0.1-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 3.0.1-6
end
main->>main: tag 3.0.1
rect rgb(211, 211, 211)
Note over main: 3.0.1
end
Release Branches
Release branches are used for major and minor releases to stabilize a RC
(Release Candidate) or to integrate features (in parallel) targeting different
iterations. Release branches are taken from main (or from develop) and will
be merged back afterwards. Finally the main branch is tagged with the
released version.
Release branches can be used in the GitFlow as well as GitHubFlow workflow.
Sometimes you want to start on a large feature which may take a while
to stabilize so you want to keep it off main.
In these scenarios you can either create a long lived
feature branch (if you do not know the version number this large feature will go
into, and it's non-breaking) otherwise you can create a release branch for the
next major version. You can then submit pull requests to the long lived feature
branch or the release branch.
Create release branch
sequenceDiagram
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant release as release/next
main->>release: branch from main
activate release
deactivate main
rect rgb(211, 211, 211)
Note over release: 1.3.0-beta.1+0
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 1.3.0-beta.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>main: tag 1.2.1
rect rgb(211, 211, 211)
Note over main: 1.2.1
end
main->>release: merge
deactivate main
rect rgb(211, 211, 211)
Note over release: 1.3.0-beta.1+2
end
release->>release: Commit '+semver: major'
rect rgb(211, 211, 211)
Note over release: 2.0.0-beta.1+3
end
release->>release: tag 2.0.1-beta.1
rect rgb(211, 211, 211)
Note over release: 2.0.1-beta.2+0
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 2.0.1-beta.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
release->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.0.1-PullRequest2.5
end
destroy pull
main--xpull: delete branch
release->>main: merge
Note over release: Release branches should
be deleted once merged
destroy release
main--xrelease: delete branch
rect rgb(211, 211, 211)
Note over main: 2.0.1-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 2.0.1-6
end
main->>main: tag 2.0.1
rect rgb(211, 211, 211)
Note over main: 2.0.1
end
Create release branch with version
sequenceDiagram
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant release as release/2.2.1
main->>release: branch from main
activate release
deactivate main
rect rgb(211, 211, 211)
Note over release: 2.2.1-beta.1+0
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 2.2.1-beta.1+1
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.2.1-1
end
main->>main: tag 2.2.1
rect rgb(211, 211, 211)
Note over main: 2.2.1
end
main->>release: merge
deactivate main
rect rgb(211, 211, 211)
Note over release: 2.3.0-beta.1+2
end
release->>release: Commit '+semver: major'
rect rgb(211, 211, 211)
Note over release: 3.0.0-beta.1+3
end
release->>release: tag 3.0.1-beta.1
rect rgb(211, 211, 211)
Note over release: 3.0.1-beta.2+0
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 3.0.1-beta.2+1
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
release->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 3.0.1-PullRequest2.5
end
destroy pull
main--xpull: delete branch
release->>main: merge
Note over release: Release branches should
be deleted once merged
destroy release
main--xrelease: delete branch
rect rgb(211, 211, 211)
Note over main: 3.0.1-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 3.0.1-6
end
main->>main: tag 3.0.1
rect rgb(211, 211, 211)
Note over main: 3.0.1
end
Develop Branch
sequenceDiagram
participant main
participant develop
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
main->>develop: branch from main
deactivate main
activate develop
rect rgb(211, 211, 211)
Note over develop: 1.3.0-alpha.0
end
develop->>develop: commit
rect rgb(211, 211, 211)
Note over develop: 1.3.0-alpha.1
end
create participant release as release/1.3.0
develop->>release: branch from develop
deactivate develop
activate release
rect rgb(211, 211, 211)
Note over release: 1.3.0-beta.1+1
end
release->>release: commit
rect rgb(211, 211, 211)
Note over release: 1.3.0-beta.1+2
end
activate develop
rect rgb(211, 211, 211)
Note over develop: 1.4.0-alpha.0
end
release->>develop: merge
rect rgb(211, 211, 211)
Note over develop: 1.4.0-alpha.2
end
activate main
release->>main: merge
Note over release: Release branches should
be deleted once merged
destroy release
main--xrelease: delete branch
main->>main: tag 1.3.0
rect rgb(211, 211, 211)
Note over main: 1.3.0
end
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 1.3.1-1
end
main->>main: tag 1.3.1
rect rgb(211, 211, 211)
Note over main: 1.3.1
end
main->>develop: merge
deactivate main
rect rgb(211, 211, 211)
Note over develop: 1.4.0-alpha.2
end
develop->>develop: Commit '+semver: major'
rect rgb(211, 211, 211)
Note over develop: 2.0.0-alpha.3
end
develop->>develop: tag 2.1.0-alpha.1
rect rgb(211, 211, 211)
Note over develop: 2.1.0-alpha.1
end
develop->>develop: commit
rect rgb(211, 211, 211)
Note over develop: 2.1.0-alpha.2
end
create participant pull as pull/2/merge
main->>pull: branch from main
activate pull
develop->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 2.1.0-PullRequest2.5
end
destroy pull
main--xpull: delete branch
develop->>main: merge
deactivate develop
rect rgb(211, 211, 211)
Note over main: 2.1.0-5
end
activate main
main->>main: commit
rect rgb(211, 211, 211)
Note over main: 2.1.0-6
end
main->>main: tag 2.1.0
rect rgb(211, 211, 211)
Note over main: 2.1.0
end
Support Branches
Support branches are not really covered in GitFlow, but are essential if you
need to maintain multiple major versions at the same time. You could use support
branches for supporting minor releases as well. If you are just supporting the
majors, then name your branch support/<major>.x (i.e support/1.x), to
support minors use support/<major>.<minor>.x or support/<major>.<minor>.0.
(i.e support/1.3.x or support/1.3.0)
sequenceDiagram
participant main
activate main
main->>main: tag 1.2.0
rect rgb(211, 211, 211)
Note over main: 1.2.0
end
create participant support as support/1.x
main->>support: branch from tag (1.2.0)
activate support
rect rgb(211, 211, 211)
Note over support: 1.2.0
end
support->>support: commit
rect rgb(211, 211, 211)
Note over support: 1.2.1-1
end
main->>main: Commit '+semver: major'
rect rgb(211, 211, 211)
Note over main: 2.0.0-1
end
main->>main: tag 2.0.0
rect rgb(211, 211, 211)
Note over main: 2.0.0
end
create participant hotfix as hotfix/1.2.2
support->>hotfix: branch from support/1.x
deactivate support
activate hotfix
rect rgb(211, 211, 211)
Note over hotfix: 1.2.2-beta.1+1
end
hotfix->>hotfix: commit
hotfix->>hotfix: commit
rect rgb(211, 211, 211)
Note over hotfix: 1.2.2-beta.1+3
end
hotfix->>hotfix: tag 1.2.3-beta.1
rect rgb(211, 211, 211)
Note over hotfix: 1.2.3-beta.2+0
end
hotfix->>hotfix: commit
rect rgb(211, 211, 211)
Note over hotfix: 1.2.3-beta.2+1
end
create participant pull as pull/2/merge
support->>pull: branch from support/1.x
activate pull
hotfix->>pull: merge
rect rgb(211, 211, 211)
Note over pull: 1.2.3-PullRequest2.5
end
destroy pull
support--xpull: delete branch
hotfix->>support: merge
Note over hotfix: Hotfix branches should
be deleted once merged
destroy hotfix
support--xhotfix: delete branch
rect rgb(211, 211, 211)
Note over support: 1.2.3-5
end
activate support
support->>support: tag 1.2.3
rect rgb(211, 211, 211)
Note over support: 1.2.3
end
rect rgb(211, 211, 211)
Note over main: 2.0.0
end
support->>main: merge
rect rgb(211, 211, 211)
Note over main: 2.0.1-6
end
main->>main: tag 2.0.1
rect rgb(211, 211, 211)
Note over main: 2.0.1
end
support->>support: commit
rect rgb(211, 211, 211)
Note over support: 1.2.4-1
end
support->>support: tag 1.2.4
rect rgb(211, 211, 211)
Note over support: 1.2.4
end
support->>main: merge
rect rgb(211, 211, 211)
Note over main: 2.0.2-2
end
main->>main: tag 2.0.2
rect rgb(211, 211, 211)
Note over main: 2.0.2
end
Depending on what you name your support branch, you may or may not need a
hotfix branch. Naming it support/1.x will automatically bump the patch,
if you name it support/1.3.0 then the version in branch name rule will
kick in and the patch will not automatically bump, meaning you have to
use hotfix branches.
To Contribute
Source
The diagrams are generated from DocumentationSamplesForGitFlow.cs. After
changing a scenario, run the GenerateMermaidSources Cake task, inspect the
updated Mermaid source, and run the ValidateMermaidDiagrams Cake task before
committing it.