Git Flow hooks

This repository contains git hooks for git flow to help deploy releases and hotfixes in my go, nodejs repositories.

Here are some sample repositories for GitHub, BitBucket, and GitLab:

• gitflow-pr-sandbox on GitHub,
• gitflow-pr-sandbox on BitBucket,
• gitflow-pr-sandbox on GitLab,

Pre-Requisites

The hooks from this repository work with git-flow-next (brew install git-flow-next on macOS) or git flow AVH Edition, which is not maintained anymore. The original git-flow does not handle git hooks. Make sure to install one of these!

The version of the target repository is assumed to follow the semver specifications.

Installation

Linux

You can grab the latest binary package on the Downloads pages.

On Debian/Ubuntu distributions, you can use my package repository. First download the signing key:

curl -fsSL https://gildas.github.io/apt/gildas-archive-keyring.gpg | \
  sudo tee /usr/share/keyrings/gildas-archive-keyring.gpg >/dev/null

Add this source:

echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/gildas-archive-keyring.gpg] https://gildas.github.io/apt stable main" | sudo tee /etc/apt/sources.list.d/gildas.list
sudo apt update

Then install gitflow-hooks with:

sudo apt install gitflow-hooks

If you use Homebrew, you can install gitflow-hooks with:

brew install gildas/tap/gitflow-hooks

macOS

You can get gitflow-hooks from Homebrew with:

brew install gildas/tap/gitflow-hooks

You can also download the archive for your platform from the releases page and install it manually.

Windows

You can install gitflow-hooks with scoop:

scoop bucket add gildas https://github.com/gildas/scoop-bucket
scoop install gitflow-hooks

You can also download the archive for your platform from the releases page and install it manually.

Source code

You can also build and install the hook-it application with cargo from this project's folder:

cargo install --path .

Usage

The hooks are embedded in the binary, so hook-it is the only file to ship to users, and it runs from anywhere (Linux, macOS, and Windows). Point it at the target repository:

hook-it /path/to/repo

Use -v to display more information and --noop (or --dry-run) to see what would be done without modifying anything. Check all the options with hook-it --help.

hook-it checks that the repository is valid and has git-flow already; if not, it tries to initialize git-flow in the repository.

It also checks that your installed git-flow is git-flow-next or the AVH edition, and stops if it is not the case.

By default, hook-it looks for the kind of language used in the repository (Go, Salesforce, or Node.js) and copies the appropriate hooks. It searches in the root of the repository, then in the src/, backend/, and src/backend/ folders.

You can also tell hook-it where to look for the code with (it can be repeated):

hook-it --src source_folder /path/to/repo

To inject the hooks in all the repositories found in a folder, use --recursive, optionally with --exclude regular expressions:

hook-it --recursive --exclude archive ~/Projects

While editing the hooks, --hooks-dir hooks copies them from that folder instead of the embedded ones. Run cargo install --path . again to embed the new versions.

Configuration

By default, the hooks will prevent you from:

• committing anything to the master branch
• committing anything that has unresolved merge conflicts
• committing code that is not linted (Go with golangci-lint and staticcheck, Node.js and Salesforce LWC/Aura with the project's ESLint). Missing linters are skipped with a warning.
• force Pull Request usage

In case you do not want either of these features, you can turn them off with:

git config --bool gitflow.allow-master-commit true
git config --bool gitflow.allow-conflict-commit true
git config --bool gitflow.must-pass-lint false
git config --bool gitflow.use-pull-request false

The hooks will also:

• format the code with gofmt for Go changes, and with the project's Prettier for Node.js and Salesforce changes (skipped if Prettier is not installed)

Similarly, you can turn off the formatting feature with:

git config --bool gitflow.prettify false

You can also change the prefix used to tag the new release/hotfix (default is "v"):

git config gitflow.prefix.versiontag v

When using Pull Requests, if the origin is on GitHub, the scripts will rely on the Github's CLI (gh) and will fail if the tool is not present.

If the origin is on BitBucket, the scripts will rely on the Bitbucket's CLI (bb) and will fail if the tool is not present. You can configure which Bitbucket profile is used in your git config (git config bitbucket.cli.profile myprofile)

If the origin is on GitLab, the scripts will reply on the GitLab's CLI (glab) and will fail if the tool is not present.

The scripts will also bump the Helm Chart version if it is present. You can configure the location of the chart with:

git config gitflow.path.chart path/to/chart

The default location is: chart/

You can turn off the chart feature with:

git config --bool gitflow.bump-chart false

The scripts will also update the OCI annotations (version and created) in the Dockerfile if present.

You can turn off the Dockerfile feature with:

git config --bool gitflow.bump-dockerfile false

You can also change the default name and location of the Dockerfile:

git config gitflow.path.dockerfile path/to/Dockerfile

The scripts will also bump the Appveyor version if it is present.

You can turn off the Appveyor feature with:

git config --bool gitflow.bump-appveyor false

Usage in Target Repository

Once the hooks are initialized, everything can be done in the target repository folder.

Starting a new release can be done simply:

git flow release start xxx

Similarly, starting a hotfix can be done as follows:

git flow hotfix start xxx

Where xxx is the new version you are releasing/hotfixing, it is mandatory. If xxx is one of major, minor, patch, the scripts will bump the corresponding component of the current version (from the repository code) according to the semver recommandations.

For example, if the current version is 1.2.3:

• major will update the version to 2.0.0
• minor will update the version to 1.3.0
• patch will update the version to 1.2.4

The scripts will also commit the bumped files.

Depending on the language, the scripts will bump the following files:

• version.go in Go (or any file that contains the line: var VERSION = "1.2.3");
• package.json in Node.js;

If you use Pull Requests, you should publish the release once to create a Pull Request:

git flow release publish

As indicated in the command line result instruction, while merging the Pull Request, the approver should not delete the release branch.

When the release is ready, simply finish it:

git flow release finish

Note: The finish process will fail if there is no Pull Request (asuming you use the Pull Request usage feature) or the current Pull Request has not been properly merged.

Examples:

git flow release start 12.3.4

git flow release start major

You do not need to repeat the version when finishing the release/hotfix if you are on their branch.

As stated earlier, if the repository has a "chart" folder, the scripts will update the "appVersion" accordingly as well. They will also bump the chart version according to the same rules used for the application version.

TODO

The hooks should log their work and maybe display some nicer progress.

Maybe having some in-repository code that would allow the hooks to update to the current version of this repository.

Acknowledgments

Thanks to Peter van der Does and Jasper N. Brouwer for their git flow hooks examples (resp. petervanderdoes/gitflow-avh, jaspernbrouwer/git-flow-hooks) that inspired me.

Of course, we wouldn't have any git flow without Vincent Driessen and his inspiring blog post A successful Git branching model about 10 years ago...