Gitflow
External
- https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
- http://nvie.com/posts/a-successful-git-branching-model/
- https://jeffkreeftmeijer.com/git-flow/
- https://danielkummer.github.io/git-flow-cheatsheet/
- https://github.com/petervanderdoes/gitflow-avh/wiki/Installation
- http://weaintplastic.github.io/web-development-field-guide/Collaboration/Working_with_Git/Git_Workflow/The_Concept_of_Gitflow
- https://datasift.github.io/gitflow/IntroducingGitFlow.html
Internal
Overview
git-flow defines a branching model that is tightly coupled with the project release cycle. This model is suited for projects that have a scheduled release cycle.
git-flow comes with a well-defined set of branches, where each branch (or each branch type) has a specific role:
- The master branch stores the official release history. The master contains the abridged history of the project, unlike develop, which contains the complete history.
- The develop branch serves as integration branch for features. This branch contains the complete history of the project.
- Feature branches serve to develop features. Each feature should reside on its own branch. The feature branches branch off develop, not master. When a feature is complete, the corresponding feature branch is merged back into develop. Features should never interact directly with master.
- Release branches host release preparation development. Once develop contains enough features for a release, or the schedule release date is approaching, a new release branch is forked off develop. The creation of the release branch starts the release cycle: no new features can be added after this point, only bug fixes, documentation and other release-related content. Once the release work is finalized: 1) the release branch is merged into the master and tagged with a release number and 2) the release branch is merged back into develop. Merging the release branch back into develop is critical because important updates may have been added to the release branch during the release process and we want those into the main development state. Having a dedicated release branch facilitates communication regarding the specific release: "we're preparing version 7.7". After release and merging, the release branch should be deleted.
- Hotfix (or "maintenance") branches. See:
git-flow is a merge-based solution. It does not rebase feature branches.
git-flow is supported by a toolset that can be installed, and which provides specialized command line extensions.
Installation
Mac
brew install git-flow-avh
Operations
git-flow-Enabling a Repository
If you intend to use git-flow extension, it is mandatory to "git-flow-enable" the repository with the following command, otherwise the extension commands will complain and will refuse to work. Initialization creates the set of standard branches and branch prefixes required by the git-flow workflow.
git flow init
The command runs a questionnaire where you should select the default answers, with the exception of the "Version tag prefix", which should be "release":
Which branch should be used for bringing forth production releases? - develop Branch name for production releases: [] master Which branch should be used for integration of the "next release"? - develop Branch name for "next release" development: [develop] develop How to name your supporting branch prefixes? Feature branches? [feature/] Bugfix branches? [bugfix/] Release branches? [release/] Hotfix branches? [hotfix/] Support branches? [support/] Version tag prefix? [] release- Hooks and filters directory? [/Users/ovidiu/github/some-repository/.git/hooks]
Note that any newly created branch does not have any corresponding remote branch, so if you want to establish the relationship, apply Publish a Local Branch in a Remote Repository procedure.
Feature
Create a Feature Branch
git flow feature start <feature_branch_1>
Note that the repository must be "git-flow enabled" for this to work. See git-flow-enabling a repository.
The equivalent standard commands:
git checkout develop git checkout -b <feature_branch_1>
Note that this command does not push the newly created feature branch into the origin repository. If you wish to do so, follow:
and then:
In our case is:
git push origin feature/<feature_branch_1> git branch --set-upstream-to=origin/feature/<feature_branch_1> feature/<feature_branch_1>
Finish the Feature
Go to the develop branch and synchronize it with origin:
git checkout develop git pull
Then go back to the feature branch and merge develop into it, to preemptively resolve merge conflicts:
git checkout feature/<feature_branch_1> git merge develop
From any branch, including the feature branch being worked on (note that you can simply use "<feature_branch_1>", not "feature/<feature_branch_1>", git-flow knows what this is about:
git flow feature finish <feature_branch_1>
The command will checkout the develop branch and merge <feature_branch_1> into it, then will delete the feature branch. The equivalent base commands:
git checkout develop git merge <feature_branch_1>
Release
Start the Release Process (Making the Release Branch)
git flow release start 0.1.0
Manual commands:
?
Finish a Release
git checkout master git checkout merge release/0.1.0 git flow release finish ‘0.1.0’
Manual:
?
Hotfix
A hotfix or maintenance brach carries maintenance work for functionality that was released. The results of the maintenance work are used to patch production releases. Hotfix branches are based on master. These are the only branches that fork off directly from master. As soon the fix is complete, the hotfix branch should be merged both in master and develop, or the current release branch, if there’s one in progress, and master should be tagged with an update release number. Hotfix (maintenance) branches can be thought of as ad-hoc release branches that work directly with master.
Start a Hotfix
The repository must be "git-flow enabled" to be able to start a hotfix with git flow. See git-flow-enabling a repository.
Check the Hotfix Branch Root Commit
Logically, a hotfix branch should be rooted in the master branch commit that was released. Since theoretically it should be no activity on the master after release, that commit should be the HEAD of the branch. This can be checked with:
git checkout master git log
The HEAD commit should have a "release ..." log entry.
Start the Hotfix Branch
To start the hotfix, use the following command ("hotfix/" prefix does NOT need to specified, git-flow will append it):
git flow hotfix start <hotfix_branch_1>
Example:
git flow hotfix start update-creditlimit-fix
Note that this command does not push the newly created feature branch into the origin repository. If you wish to do so, follow:
and then:
Increment the Version
For a Gradle project, the version is conventionally maintained in gradle.properties. The version should be incremented at this stage. We get a dot version, since we're on a hotfix version, we should increment the patch component and temporarily (until we figure out what is broken) mark it SNAPSHOT
version=1.3.0
should become:
version=1.3.1-SNAPSHOT
Finish the Hotfix
Insure Tests Pass
Wrap up work, increment all dependencies, if necessary, and make sure all tests pass on the hotfix branch, locally and on the remote build server, if any.
Set the Dot Release Version
On the hotfix branch, remove the -SNAPSHOT postfix and set the correct dot release version:
version=1.3.1-SNAPSHOT
should become:
version=1.3.1
then:
git add . git commit -m "release $(grep '^version=' ./gradle.properties | sed -e 's/^.*=//')" git push
Finish the Hotfix Branch
The "hotfix/" prefix is not needed, git flow knows to prepend it automatically.
git flow hotfix finish '<hotfix_branch_1>'
Example:
git flow hotfix finish 'update-creditlimit-fix'
During the process, provide a message for the tag that will be generated for the hot fix merge. If the tag is not provided, the "finish" procedure will fail.
The finish procedure will automatically attempt to merge the hotfix branch into both "master" and "develop" and will locally delete the hotfix branch.
If there are conflicts, resolve them on both branches.