internetguru / flow

Use Git Flow with ease – maintain branches, semantic versioning, releases, and changelog with a single command.

Internet Guru Flow

branch	status
master
dev

Advance in a branching model according to the current branch or a branch specified with an argument. For most existing branches, the default action is release. If a given branch does not exist, Flow creates it as a feature or a hotfix depending on the current branch or a keyword (feature/hotfix).

Additionally, Flow handles version incrementing and maintains a changelog. Before proceeding, it verifies the current repository for branching model compliance and offers to correct any detected imperfections.

• Installation
• Flow options
• Usage example
• Blog posts on Flow

Branching model automation

• Flow requires no arguments and derives a default action.
• Flow switches between branches accordingly and advises what to do next.
• Flow can create pull requests instead of releasing directly.
• Flow maintains separate production branches for major versions, such as prod-1.
• Flow supports parallel hotfixing, even for separate production branches.

Branching model validation

• Flow validates and automatically fixes project structures to conform to the branching model.
• Flow pulls and pushes all key branches and checks whether local branches are not behind.
• Flow handles semantic versioning across all key branches. Read more about version handling with Flow.
• Flow keeps track of a release history with the Keep a CHANGELOG convention. Read more about changelog handling with Flow.

Setup and configuration

• Flow can initiate a git branching repository in any folder with or without files.
• Flow can convert any existing git repository to a git branching model.
• Flow automatically adapts to existing branches, such as 'release' instead of the default 'staging'.

Installation

Download the latest release from GitHub. You can install as a single file (easiest), with compiled distribution package (useful for system-wide install) or from the source.

Requirements

• Bash, version 3.2 or later
• Git, version 1.8.0 or later
• GNU getopt
  • On macOS install with Homebrew (gnu-getopt) or with MacPorts (getopt)
• GNU sed
  • On macOS install with Homebrew gnu-sed
• GNU awk
  • On macOS install with Homebrew homebrew/dupes/grep

Single file script

1. Place flow.sh into your $PATH (e.g. ~/bin).
2. Make the script executable.

   chmod +x flow.sh

Compiled distribution package

1. Extract the archive.

   tar -xvzf flow-*-linux.tar.gz

2. run install script as root; this will proceed a system-wide installation into /usr/local.

   cd flow-*-linux
   sudo ./install

You can override installation paths using environment variables.

• BINPATH: where the script will be placed, /usr/local/bin by default.
• SHAREPATH: where support files will be placed, /usr/local/share by default.
• USRMANPATH: where manpage will be placed, $SHAREPATH/man/man1 by default.

This is how to install the script without root permissions.

BINPATH=~/bin SHAREPATH=~/.local/share ./install

Building from source

You will need the following dependencies:

• GNU Make
• rst2man (available in Docutils, e.g. apt-get install python-docutils or pip install docutils)

git clone https://github.com/internetguru/flow.git
cd flow
./configure && make && sudo compiled/install

You can specify following variables for make command which will affect default parameters of install script:

• PREFIX: Installation prefix, /usr/local by default.
• BINDIR: Location for flow script, $PREFIX/bin by default.

For example like this:

PREFIX=/usr make

See the man page for more information and examples.

Running unit tests

Testing the script requires a built 'flow' command and Bash Unit Testing Tool -- AKA the 'butt' command.

butt ~/flow/test/test.butt

Contributing

Pull requests are welcome. Don't hesitate to contribute.

Copyright

Copyright © 2016--2023 Internet Guru

This software is licensed under the CC BY-NC-SA license. There is NO WARRANTY, to the extent permitted by law. See the LICENSE file.

For commercial use, a nominal fee may be applicable based on the company size and the nature of their product. In many instances, this could result in no fees being charged at all. Please contact us at [email protected] for further information.

Please do not hesitate to reach out to us for inquiries related to seminars, workshops, training, integration, support, custom development, and additional services. We are more than happy to assist you.

Donation

If you find this script useful, please consider making a donation to support its developers. We appreciate any contributions, no matter how small. Donations help us to dedicate more time and resources to this project, including covering our infrastructure expenses.

PayPal Donation

Please note that we are not a tax-exempt organization and cannot provide tax deductions for your donation. However, for donations exceeding $500, we would like to acknowledge your contribution on project's page and in this file (including the man page).

Thank you for your continued support!

Honored donors

• Czech Technical University in Prague
• WebExpo Conference in Prague
• DATAMOLE data mining and machine learning

Alternatives

• git-flow – The original Vincent Driessen's tools.
• git-flow (AVH Edition) – Maintained fork of the original tools.
  • See also cheatsheet
• HubFlow – Git Flow for GitHub by DataSift.
• gitflow4idea – Plugin for JetBrains IDEs.
• GitKraken – Cross-platform Git GUI with Git Flow operations.
• SourceTree – Git GUI for macOS and Windows with Git Flow support.
• GitFlow for Visual Studio

flow's Issues

omgf pull throws error 1

» gf pull                                                                         ~/gf
[   ok   ] Fetching --tags
[   ok   ] Fetching origin dev:dev
[   ok   ] Fetching origin master:master
omgf[error]: Generic error occurred (see REPORTING BUGS).

'make distclean' fails.

• Steps to Reproduce:
  Follow instructions on installation from the source

  ./configure
  make
  make dist
  

  ...

  make distclean
  

• Actual Result:

  rm: nelze odstranit *'omgf.sh'*: Adresář nebo soubor neexistuje
  Makefile:160: návod pro cíl „distclean“ selhal
  make: *** [distclean] Chyba 1
  

• Possible fix:
  Replace

  distclean:
        @ rm *.tar.gz
        @ rm $(PROGSINGLE)
  

  with

  distclean:
        @ rm *.tar.gz
        @ rm $(PROG)
  

  at the end of Makefile.

Omgf throws error for remote branch only

Default changelog entry

Omitting changelog entry results into no entry (feature) or a heading with no content (hotfix). Formally some entry is eminent.

• Suggested default feature entry:
  • Added: [branch-name]
• Suggested default hotfix entry:
  • Fixed: [branch-name]

Suggested solution: skipping an entry may result into a (configurable) default changelog entry.

Add configuration support through git-config

The following features can be configurable:

• branches naming (e.g. use master or develop instead of dev; stable instead of master)
• custom pull request URLs support, including GitLab #40
• custom prefixes for feature and hotfix branches, e.g. feature/ instead of feature-
• set default behaviour for parameters, e.g. --request
• set default environment variables
• set task to be run on particular events #52

This allows a common shared configuration to be commited into .gitconfig in the project and also set user's default preferences in ~/.gitconfig

Resolving conflict

Specify the process of resolving conflicts and how to continue in case of merging feature or hotfix.
See section ADVANCED EXAMPLES in manual

Ideas: some kind of omgf --continue etc.

Support tab completions

Built-in manpage

For example -h for short usage, --help will open pager with manpage.

This is quite useful for single-file distribution.

Add "branch xy is not up-to-date with remote" error

Do not allow gf on branches which are not up-to-date with remote.

Add support for GitLab merge request URLs

When using OMGF with GitLab and --request option, after finishing a branch OMGF yells at me:

unknown - remote server name not recognized

Please, add support for GitLab URLs. Either you can check for gitlab anywhere in remote URL or just make it a default fallback.
Alternatively, there could be an explicit configuration option for formatting PR URLs.

Allow release without release branch

Currently to perform release you need to do:

gf release
gf release

There could be a parameter to skip the release branch. However, this is a low priority and may conflict with #31

Trim branch prefix if matches with name

Command omgf feature-myfeature now creates branch name feature-feature-myfeature. It may be sufficient to trim the matching prefix and thus create branch name feature-myfeature instead.

Suggested solution: trivial.

Add push, pull kw

Push and pull all omgf branches (dev, release and master) and also tags on master.

gf pull:

• fetch all
• merge all local branches with origin

Add `make install`

Split README into multiple documents / wiki

omgf pull error

gf pull throws error when remote branch does not exists.

• Example:

dev » gf pull -v
[   ok   ] Fetching --tags
[   ok   ] Fetching origin dev:dev
[   ok   ] Fetching origin master:master
[  ....  ] Fetching origin release:release
omgf[error]: fatal: Couldn't find remote ref release
fatal: The remote end hung up unexpectedly
omgf[error]: Generic error occurred (see REPORTING BUGS).

• Proposal: skip non-existing branches.

Conform commits on master branch

• Since last tag as merged hotfix or release
• Optionally ask to move them into proper branch

Merge stable hotfix to release iff exists

See http://nvie.com/posts/a-successful-git-branching-model/#hotfix-branches

OMGF doesn't work from subdirectory

I have a git flow project. When I attempt to run omgf from a subdirectory, I get this error:

omgf[error]: Git repository does not exist
omgf[error]: Git is not conform with OMGF model (see conform option).

Although standard Git operations work.

Add integration tests working with ‘remote’ upstream

Create origin repository locally (it probably needs to be bare). Then clone the repo to create a downstream repo for testing.

Improve --dry-run

Dry run only checks options and does not attempt to perform anything.

'-V' option does not show version number

• Steps to reproduce:
  Run

  omgf -V
  

• Actual result:

  * Create hotfix 'hotfix-XXXX' from 'v0.0.0'? [YES/No]
  

• Expected result:

  omgf 2.0.1
  

More detailed information about automatic versioning

Consider describing how and when is the version number changed.

insert changelog items correctly

Multiple items are inserted to the changelog in reverse order.

macOS / BSD compatibility

Apparently macOS ships with BSD getopt while OMGF uses some features of GNU getopt (especially long parameter names). This has multiple solutions:

• require macOS users to install GNU getopt via Brew or MacPorts
  • easiest for us since we plan to do Brew package anyway, however reduces portability on *BSD platforms
• parse options ourselves
• use some parsing library like opt-in, this snippet, getopts_long, or shFlags

See also Bash Hackers Wiki.

Increment minor version when release is created

It is useful in testing phase, when you need to use version number different from master branch.

Test merging hotfix with release branch

We should add a test to check if hotfix is merged correctly with the release branch.

Situation:

omgf release # create release
omgf hotfix # create hotfix
# ... some fix
omgf # merge hotfix (into master, dev, release)

Allow adding changelog items using $EDITOR

Current readline support is nice, but you cannot fix typos in lines you already added. Add configuration option #46 to use $EDITOR by default akin to Git's interactive rebase behavior.

-h not usable on macOS due to missing arguments in man

omgf -h failing on macOS, because of man has no options --nj --nh -l on macOS...

Version incrementation

Increment version just before proceed merge hotfix or release.
When version was manualy changed then keep it.

Homebrew formula

This has high priority for simpler distribution on macOS #41

Native packages distribution

• Homebrew #54
• Debian package – with APT repository
• Cygwin package?
• RPM pakckage or some other new stuff, like Flatpak or Snap
• BSD ports or whathever they use

Add requirements to README

Hooks support

For example Node packages have version in package.json. You may want to configure some command or hook to run when OMGF increments version.

You're not using OMGF_DEV everywhere to reference the development branch

https://github.com/InternetGuru/omgf/blob/fd9dc6ea6d2337c60585003c7316d262f8e82313/omgf#L423

omgf pull does not distinguish skip from ok

now it is ok in both cases

Broken usage

Command gf -h results into:

Usage: omgf [-cfhinrvVwy] [--color[=WHEN]] [KEYWORD] [NAME]
.TH
.TP 18
-c, --conform
Repair (initialize) project to be conform with **OMGF** model and proceed.
.TP 18
--color[=WHEN], --colour[=WHEN]
Use markers to highlight command status; WHEN is 'always', 'never', or
'auto'. Empty WHEN sets color to 'always'. Default color value is 'auto'.
.TP 18
-f, --force
Move (stash and pop) uncommitted changes.
.TP 18
-h, --help
Print help.
.TP 18
-i, --init
Same as conform, but do not proceed.
.TP 18
-n, --dry-run
Do not run commands; only parse user options.
.TP 18
-r, --request
Instead of merging prepare current branch for pull request and push it to
the origin.
.TP 18
-v, --verbose
Verbose mode.
.TP 18
-V, --version
Print version number.
.TP 18
-w, --what-now
Display what to do on current branch.
.TP 18
-y, --yes

  -c, --conform     Repair (initialize) project to be conform with **OMGF** model and
                    proceed.
  --color[=WHEN], --colour[=WHEN]
                    Use markers to highlight command status; WHEN is 'always', 'never', or
  -f, --force       Move (stash and pop) uncommitted changes.
  -h, --help        Print help.
  -i, --init        Same as conform, but do not proceed.
  -n, --dry-run     Do not run commands; only parse user options.
  -r, --request     Instead of merging prepare current branch for pull request and push it
                    to the origin.
  -v, --verbose     Verbose mode.
  -V, --version     Print version number.
  -w, --what-now    Display what to do on current branch.
  -y, --yes         Assume yes for all questions.

/usr/local/bin/gf: line 123: syntax error near unexpected token `;'

on first run (master and dev branch):

$ gf
/usr/local/bin/gf: line 123: syntax error near unexpected token `;'
/usr/local/bin/gf: line 123: `        ;&'

note: current dir was initialized neither for git nor omgf

$ bash --version
GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin15)
Copyright (C) 2007 Free Software Foundation, Inc.

configure script should check for make command

Links in manpage not working

Links in manpage are not expanded to Title: URL, only underlined.

Refactor Makefile

• separate tasks for files with explicit dependencies
• move usage file into the final script
• remove DESTDIR

For example:

dist: usage.txt manpage.1
  #...
distsingle: usage.txt
  #...
usage.txt:
  #...
manpage.1
  #...

Check existing branches

• delete merged branches
• verify origin (release must come from dev etc.)

Redundant version update commits

Merging hotfix into master updates version from master to support paralel hotfixing. After that the version number is being incremented. Committing both operations seems to be redundant. Moreover the result might not change the version at all (see example).

1. create hotfix from version 1.0.0
2. do some commits…
3. request a hotfix merge
   1. check version (1.0.0 - not different, no commit)
   2. increment version to 1.0.1 and commit
4. do some more commits…
5. request a hotfix merge
   1. check version (1.0.0 - different) and commit
   2. increment version to 1.0.1 and commit

Suggested solution: just omit the first commit after checking the version.

Test multiple Git versions on Travis

Display "nothing to merge" if release is empty

Current output of merging empty release into dev

{ test } release » omgf
* Merge 'release' branch into 'dev'? [YES/No] yes
[   ok   ] Merging 'release' into branch 'dev'

Proposed output

{ test } release » omgf
omgf[error]: Nothing to merge - 'dev' is up-to-date with 'release'
omgf[error]: Generic error occurred (see REPORTING BUGS).

Duplicit version heading in changelog

Requesting hotfix merge more than once results in more headings with the same version number.

1. create hotfix
2. do some commits…
3. request a hotfix merge
   1. add version heading into changelog
4. do some more commits…
5. request a hotfix merge
   1. add version heading into changelog

Suggested solution: check for existing version heading before adding a new one.

Stash after confirming an action

Stash happens prior to confirmation, it should be other way around.

Add separate changelog keyword

This will execute CLI for adding entries to changelog.

Consider adding default aliases like omgf ch or omgf c.

omgf not working on macOS HighSierra

When I run omgf --what-now, omgf displays this error:

➜  git-flow-example git:(master) ✗ omgf --what-now
omgf[error]: OMGF requires Bash version 3.2 or later (you have no Bash installed)
omgf[error]: Generic error occurred (see REPORTING BUGS).

I tried preinstalled Bash (3.2.57):

➜  git-flow-example git:(master) ✗ bash --version
GNU bash, version 3.2.57(1)-release (x86_64-apple-darwin17)
Copyright (C) 2007 Free Software Foundation, Inc.

I tried upgrade via homebrew to Bash (4.4.23):

➜  git-flow-example git:(master) ✗ bash --version
GNU bash, verze 4.4.23(1)-release (x86_64-apple-darwin17.5.0)
Copyright (C) 2016 Free Software Foundation, Inc.
Licence GPLv3+: GNU GPL verze 3 nebo novější <http://gnu.org/licenses/gpl.html>

Toto je svobodné programové vybavení: máte právo jej měnit a šířit.
VEŠKERÉ ZÁRUKY chybí, jak jen zákon dovoluje.

I have installed all required dependencies. Even when I comment out requirements checking code, I got omgf[error]: Generic error occurred (see REPORTING BUGS).

Standard branch naming

omgf uses dev instead of develop and release instead of release-* for individual minor releases, compared to the original article.

I understand that handling individual releases is a demanding feature, but renaming develop, seems like purposeless confusion, I suggest renaming to avoid inconsistency.