Git Flow CLI Plus

Available @ GitHub Releases

A command-line tool providing high-level repository operations for Vincent Driessen's branching model, implemented on top of plain git. It is the CLI companion to gitflow4idea-plus (Git Flow Integration Plus for IntelliJ), sharing the same semantics and config layout.

Getting started

For the best introduction to get started with git flow, please read Jeff Kreeftmeijer's blog post:

http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/

Or have a look at this cheat sheet by Daniel Kummer.

Installation

Requires Go 1.21+.

# build from source
git clone https://github.com/RubinCarter/gitflow-cli-plus.git
cd gitflow-cli-plus
go build -o gitflow .

# or install directly
go install github.com/gitflow-cli-plus/gitflow-cli-plus@latest

The tool follows the AVH edition semantics, because the Vanilla Git Flow hasn't been maintained in years. It reads and writes the AVH-style git config keys (gitflow.branch.*, gitflow.prefix.*), and additionally recognizes repositories initialized by git-flow-next through a read-only compatibility layer.

Usage

gitflow init -d                    # initialize with defaults
gitflow feature start my-feature   # branch feature/my-feature off develop
# ... work, commit ...
gitflow feature finish my-feature  # --no-ff merge into develop, delete branch
gitflow feature publish my-feature # push to origin and set upstream
gitflow release start 1.0.0
gitflow release finish 1.0.0       # merge to master+develop, tag 1.0.0
gitflow hotfix start 1.0.1         # branch off master
gitflow hotfix finish 1.0.1        # merge to master+develop, tag 1.0.1
gitflow bugfix start nasty-bug     # AVH extension: branch off develop

• feature / bugfix: start, finish, publish, pull, track
• release: start, finish, publish, track
• hotfix: start, finish, publish
• Common start flags: -b/--base <ref>, -F/--fetch
• Common finish flags: -F/--fetch, -k/--keep, --keeplocal, --keepremote, -p/--push; release/hotfix finish additionally support -n/--notag and -m/--message (%name% is substituted)

Branch names are normalized the way git-flow AVH does: a name that already carries the command's own prefix is used as-is instead of stacking prefixes (gitflow feature start feature/x creates feature/x, not feature/feature/x). If init fails partway, the config it wrote is rolled back (with -f, pre-existing values are restored), so a plain retry works.

All git operations are executed via git subprocesses, so merge/tag/push semantics are identical to C git. Error cases (not a git repo, gitflow not initialized, branch already exists or missing, dirty working tree, missing origin) fail with a clear message and a non-zero exit code.

Testing

go test ./...

50 end-to-end tests build the real binary and exercise it against throwaway local git repositories (a local bare repo plays the role of origin, including cross-clone collaboration scenarios). No network or GitHub access is needed.

Caveats

While the tool is operational and contains all basic functions (init/feature/release/hotfix/bugfix), it may contain bugs. With your help I'll be able to find and zap them all.

Helping out

This project is under active development. If you encounter any bug or an issue, I encourage you to add them to the Issues list on GitHub. Feedback and suggestions are also very welcome.

License

This project is under the Apache 2.0 license.

Who and why

This project was derived from a functional analysis of gitflow4idea-plus, the IntelliJ git-flow integration (forked from OpherV/gitflow4idea), to make the same git-flow workflow available in the terminal as a single static binary. The full analysis is documented in RESEARCH.md, and standards compliance in AUDIT.md.