gitwe

Configurable Git branching-workflow engine.

gitwe is a modern, configurable Git branching workflow engine. Define your workflow once — base branches, topic types, merge rules, tagging, hooks — and gitwe generates a consistent CLI and library API around it.

Inspired by the original nvie/gitflow, gitflow-avh, and git-flow-next, but designed with extensibility and modern DX at its core.

Key Features

• Workflow-Agnostic – Ships with classic, github, and gitlab presets, but you can fully customize .gitwe/gitwe.yaml.
• Resumable Operations – gitwe finish pauses on conflicts; resolve and resume with --continue or abort with --abort.
• Hooks – Run custom scripts at lifecycle events (pre-start, post-finish, etc.).
• Versioning & Changelog – Automatic semantic version bumps and changelog generation.
• Clean Architecture – Domain, Application, Infrastructure layers strictly enforced.
• Multi-Format Output – Supports json, yaml, and table output formats.
• GitHub Action – Use gitwe seamlessly in CI/CD pipelines.

Quick Start

Installation

npm install -g gitwe-ts
# OR
npm install -g @idmdakhi/gitwe

Or run it without installing via npx:

npx gitwe --help

Initialize a Workflow

gitwe init --preset classic

Start a Feature Branch

gitwe start feature login-page

Finish and Push

gitwe finish feature/login-page --push

If conflicts arise, resolve them and run:

gitwe finish --continue

Documentation

Full documentation is available in the docs/ folder.

• Quickstart – Get started in 5 minutes.
• Installation – Install via npm, npx, or build from source.
• Commands Reference – All CLI commands, flags, and exit codes.
• Workflow Definition – Full schema for .gitwe/gitwe.yaml.
• Hooks Guide – Scripts and environment variables for automation.
• Troubleshooting – Common errors and solutions.
• Branching Models – Classic, GitHub Flow, GitLab Flow, and custom models.
• Merge Strategies – Merge, squash, rebase, cherry-pick, and rebase-merge.
• State Machine – The resumable finish operation (diagram).
• Architecture Overview – Clean Architecture and boundary enforcement.
• Migration Guide – From nvie/gitflow, AVH, and git-flow-next.

You can also browse the Wiki for a quick overview.

Contributing

We welcome contributions! Please read our Contributing Guide and Roadmap to get started.

Development Setup

git clone https://github.com/idmdakhi/gitwe.git
cd gitwe
npm install
npm run build
npm link

Run Tests

npm test          # Unit tests
npm run test:e2e  # End-to-end tests

License

MIT © idmdakhi