gitflow-helper

gitflow-helper

A single static binary that enforces the git-flow branching model with an interactive TUI for humans and a --json mode for AI agents. Detects your IDE (Cursor / VS Code Copilot) and generates pre-flight rules automatically.

Features

• 16 CLI commands covering the full gitflow lifecycle: status, pull, push, start, finish, sync, switch, backmerge, cleanup, health, doctor, log, undo, releasenotes, init, diagram
• Interactive TUI with dashboard, action menu, command palette, and help overlay
• JSON mode (--json) for seamless integration with AI agents (Cursor, Copilot, Claude Code, etc.)
• IDE detection — automatically generates .cursor/rules/, .github/copilot-instructions.md, or AGENTS.md
• Zero runtime dependencies — static binary, only needs git (no git-flow extensions required)
• Cross-platform — Linux x86_64, Windows x86_64, macOS universal (x86 + ARM)
• Embedded gitflow skill — gitflow setup installs or updates SKILL.md in .agents/skills/gitflow/ or ~/.agents/skills/gitflow/

Install

Homebrew (Formula)

gitflow-helper is distributed as a Homebrew Formula (CLI tool), not a Cask.

brew tap novaemx/tap
brew install gitflow-helper

The formula installs shell completions for bash, zsh, and fish automatically.

Debian / Ubuntu (APT)

The project ships a flat APT source file that installs the .deb packages directly from GitHub Releases.

Supported CPU architectures:

• amd64 for x86_64
• arm64 for aarch64

Check your Debian-family architecture with:

dpkg --print-architecture

Add the source and install:

sudo curl -fsSL https://github.com/novaemx/gitflow-helper/releases/latest/download/gitflow-helper.sources \
  -o /etc/apt/sources.list.d/gitflow-helper.sources
sudo apt update
sudo apt install gitflow-helper

Rocky Linux 9 (DNF / YUM)

Rocky Linux uses a DNF/YUM repository definition plus static repodata tracked in this repository.

Supported CPU architectures:

• x86_64
• aarch64

Check your RPM-family architecture with:

uname -m

Add the repository and install:

sudo curl -fsSL https://github.com/novaemx/gitflow-helper/releases/latest/download/gitflow-helper-rocky.repo \
  -o /etc/yum.repos.d/gitflow-helper.repo
sudo dnf makecache
sudo dnf install gitflow-helper

From GitHub Releases

Download the latest binary for your platform from the Releases page.

# macOS Apple Silicon (arm64)
curl -LO https://github.com/novaemx/gitflow-helper/releases/latest/download/gitflow-<version>-darwin-arm64.tar.gz
tar -xzf gitflow-<version>-darwin-arm64.tar.gz
sudo install -m 755 gitflow /usr/local/bin/gitflow

# Linux x86_64 (tarball fallback)
curl -LO https://github.com/novaemx/gitflow-helper/releases/latest/download/gitflow-<version>-linux-amd64.tar.gz
tar -xzf gitflow-<version>-linux-amd64.tar.gz
sudo install -m 755 gitflow /usr/local/bin/gitflow

# Linux arm64 / aarch64 (tarball fallback)
curl -LO https://github.com/novaemx/gitflow-helper/releases/latest/download/gitflow-<version>-linux-aarch64.tar.gz
tar -xzf gitflow-<version>-linux-aarch64.tar.gz
sudo install -m 755 gitflow /usr/local/bin/gitflow

# Windows x86_64
# Download gitflow-<version>-windows-amd64.zip and add gitflow.exe to PATH

If you prefer native Linux packages instead of tarballs, use the APT or DNF/YUM repo setup above.

From Source

go install github.com/novaemx/gitflow-helper/cmd/gitflow@latest

Build Locally

git clone https://github.com/novaemx/gitflow-helper.git
cd gitflow-helper
bash scripts/install-hooks.sh  # install git hooks (enforces gitflow policy)
make build          # current platform
make build-all      # all platforms
make universal      # macOS universal binary

Quick Start

# Initialize gitflow in your project
gitflow init

# Auto-detect your IDE and generate rules
gitflow setup

# Launch the interactive TUI
gitflow

Usage

Interactive TUI

Run gitflow without arguments to launch the full-screen dashboard:

• j/k or arrow keys to navigate
• Enter to execute an action
• / to open the command palette (type to filter)
• ? for help
• r to refresh
• q to quit

CLI Commands

All commands support --json for machine-readable output.

Use --log to write troubleshooting output to .gitflow/logs/gitflow.log. Add --debug to include verbose debug details in the same file.

gitflow status                     # repo state dashboard
gitflow status --log               # write troubleshooting logs to .gitflow/logs/gitflow.log
gitflow status --log --debug       # include verbose debug details in the log file
gitflow pull                       # safe fetch + fast-forward merge
gitflow push                       # push current branch (target-aware)
gitflow push develop               # push current branch to target branch with validation
gitflow start feature my-feature   # start a feature branch
gitflow start bugfix fix-name      # start a bugfix branch
gitflow start release 1.2.0        # start a release
gitflow start hotfix 1.1.1         # start a hotfix
gitflow finish                     # finish current flow branch
gitflow sync                       # sync branch with parent
gitflow switch develop             # switch to a branch
gitflow backmerge                  # merge main into develop
gitflow cleanup                    # delete merged branches
gitflow health                     # full repo health audit
gitflow doctor                     # validate prerequisites
gitflow log -n 20                  # gitflow-aware commit log
gitflow undo                       # undo last operation (reflog)
gitflow releasenotes               # generate RELEASE_NOTES.md
gitflow diagram                    # print Mermaid branch topology diagram
gitflow diagram -o graph.mmd       # write Mermaid diagram to file
gitflow init                       # initialize git-flow
gitflow setup                      # detect IDE & generate rules
gitflow setup --ide cursor         # force Cursor rules only
gitflow setup --ide copilot        # force Copilot instructions only

JSON Mode (for AI Agents)

gitflow --json status
gitflow --json push feature/add-csv-export
gitflow --json start feature add-csv-export
gitflow --json finish

Exit codes: 0 success, 1 error, 2 conflict needing human intervention.

IDE Setup

Run gitflow setup once per project. It auto-detects your IDE and creates:

IDE	Generated files
Cursor	.cursor/rules/gitflow-preflight.mdc, .cursor/mcp.json, .agents/skills/gitflow/SKILL.md
VS Code + Copilot	.github/copilot-instructions.md, .vscode/mcp.json, .agents/skills/gitflow/SKILL.md
Claude Code / Windsurf / Cline	IDE-specific rule file, IDE MCP config, .agents/skills/gitflow/SKILL.md
Zed / Neovim / JetBrains / Unknown	IDE-specific files if applicable, AGENTS.md, ~/.agents/skills/gitflow/SKILL.md

Cursor / VS Code / Copilot + Claude Code companion install: when the primary IDE is Cursor, VS Code, or Copilot and Claude Code is detected in the same environment (env vars CLAUDE_* / ANTHROPIC_*, or parent process claude), gitflow setup also installs Claude Code artifacts as a companion: CLAUDE.md and .claude/mcp.json. The skill is shared (single install under .agents/skills/gitflow/SKILL.md). No flag is needed; the companion install is fully automatic. To bypass, unset the Claude env vars before running gitflow setup.

These files instruct the AI agent to run gitflow --json status before modifying any code, and the embedded skill is auto-updated if its content changes in newer gitflow binaries.

What AGENTS.md Is For

AGENTS.md is a repository-level instruction file for AI coding agents. It defines mandatory workflow rules (for example, gitflow pre-flight checks, branch routing, and safety constraints) that the agent should follow before making code changes.

gitflow setup generates AGENTS.md when an IDE/agent does not use a dedicated rules format as its primary instruction source, or when a generic fallback instruction file is needed.

IDEs/Agents That Use AGENTS.md

In this project, AGENTS.md is primarily used (or used as fallback) by these environments:

• Zed
• Neovim-based agent setups
• JetBrains-based agent setups
• Unknown or generic agent-compatible IDEs

For Cursor and VS Code Copilot, the primary files are .cursor/rules/gitflow-preflight.mdc and .github/copilot-instructions.md respectively, while AGENTS.md remains the compatibility fallback for other tools.

Copilot-Specific Notes

To ensure the embedded gitflow skill works in Copilot end-to-end:

1. Install gitflow binary and make sure it is in PATH.
2. Run gitflow setup --ide copilot in your repository root.
3. Verify these files exist:

• .github/copilot-instructions.md
• .vscode/mcp.json (contains "gitflow" server using gitflow serve)
• .agents/skills/gitflow/SKILL.md

If gitflow is not in PATH when setup runs, MCP config still gets generated, but command execution will fail until PATH is fixed.

Embedded Skill

gitflow setup now installs the gitflow skill from the binary itself.

• Project-local install for supported IDEs: .agents/skills/gitflow/SKILL.md
• User-level fallback for unsupported IDEs: ~/.agents/skills/gitflow/SKILL.md

If the embedded skill content changes in a newer binary, gitflow setup updates the installed SKILL.md automatically.

Configuration

Create a .gitflow/config.json in your project root for custom settings:

{
  "remote": "origin",
  "main_branch": "main",
  "develop_branch": "develop",
  "integration_mode": "local-merge",
  "version_file": "package.json",
  "version_pattern": "\"version\"\\s*:\\s*\"([^\"]+)\"",
  "tag_prefix": "v",
  "bump_command": "npm version {part} --no-git-tag-version",
  "ai_integration": {
    "enabled": true,
    "version": "0.5.28"
  }
}

If absent, the tool auto-detects common version files (package.json, pyproject.toml, Cargo.toml, etc.) and uses git tags for versioning.

Building

make build            # build for current platform
make build-all        # cross-compile linux/windows/macOS
make universal        # create macOS universal binary with lipo
make test             # run tests
make vet              # run go vet
make release-local    # build release artifacts locally (no publish — CI is the sole publisher)
make release-snapshot # goreleaser --snapshot, validates config without publishing
make install          # install to a user-writable dir (no sudo needed)

Testing & Coverage

Coverage profiles generated by the Makefile are written into the test/ directory.

• Run all tests and produce an aggregated coverage profile:

make cover
# writes `test/coverage.out`

• Run tests for a single package and produce a package-specific profile:

make cover-package PKG=./internal/commands
# writes `test/commands.cov`

Keep test/ out of releases and CI artifacts; these files are intended for local inspection and CI coverage steps.

Release Pipeline

GitHub Actions is the sole publisher. Local make targets only build artifacts into dist/; they never push to the GitHub Release. Pushing source to a release/* or hotfix/* branch and finishing the branch produces the v* tag, which triggers the workflow below.

Tag pushes (v*) trigger .github/workflows/release.yml, which performs the full release in three jobs:

1. test — runs go test ./... -race and enforces a per-package coverage gate of ≥ 60% (target 80%). Each package is checked independently; any package below the threshold fails the job with an ::error:: annotation naming the offending package.
2. release — runs GoReleaser (goreleaser release --clean) using the existing .goreleaser.yml. Produces 4 OS/arch targets (linux/amd64, linux/arm64, windows/amd64, darwin/arm64) + nfpms (.deb, .rpm, Arch) for both Linux architectures + checksums.txt. Smoke-tests the linux/amd64 binary. Extracts the ### TL;DR block from CHANGELOG.md and uses it as the GitHub Release body. Uploads everything to a new GitHub Release for the tag.
3. formula — bumps packaging/homebrew/gitflow.rb on main with the new version + URL + SHA256 (read from the just-published checksums.txt). When the HOMEBREW_TAP_GITHUB_TOKEN secret is configured on the repo, the same bump is mirrored to novaemx/homebrew-tap/Formula/gitflow.rb.

Build matrix

Platform	GOOS/GOARCH	Notes
Linux x86_64	linux/amd64	GOAMD64=v3 — AVX2 + FMA + BMI2, requires Haswell (2013)+
Linux ARM64	linux/arm64	Graviton, Apple-Silicon Linux, Raspberry Pi 4/5
Windows x86_64	windows/amd64	GOAMD64=v3 — same Haswell+ baseline as Linux
macOS Apple Silicon	darwin/arm64	Native Go 1.21+ codegen; macOS Intel discontinued

All builds use -trimpath, -buildid=none, -ldflags="-s -w", and -pgo=auto. PGO is a no-op until a default.pgo profile is committed to the main package directory; once present, it activates automatically with no config change (typical 5–14% speedup on hot paths).

Local validation (no publish)

# Lint the goreleaser config without producing artifacts
goreleaser check

# Build all 4 target archives into dist/ for inspection (no GitHub touch)
make release-snapshot

# Build a specific tag's artifacts into dist/ (no GitHub touch)
make release-local TAG=v0.6.8

License

MIT. See LICENSE.

Author

Luis Lozano