GitFlow Examples

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

See contributing examples.

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.