A lightweight Git workflow designed to keep the main branch stable while allowing completed work to integrate through a dedicated dev branch. Simpler than Git Flow, more structured than GitHub Flow.
Three branch types. One clear flow. That's it.
Every branch has a clear purpose.
The stable branch. Contains production-ready or release-ready code. Changes only arrive here from dev. Never commit directly.
The integration branch. Collects completed feature work before release. Feature branches are created from here and PRs target here.
Short-lived branches for new features, bug fixes, docs, tests, refactoring, and maintenance. Deleted after merge.
Get up and running with Clean Flow in seven steps.
Make sure your local dev branch is up to date.
git checkout dev && git pull origin dev
Feature branches always start from dev.
git checkout -b feature/user-authentication
Keep commits focused and related to one logical change.
git add . && git commit -m "add user authentication"
Rebase against the latest dev before submitting.
git fetch origin && git rebase origin/dev
Push and open a pull request targeting dev.
git push -u origin feature/user-authentication
When approved, squash merge into dev. Multiple commits become one clean logical commit.
When dev is stable, merge dev into main using a merge commit.
git checkout main && git merge dev && git push origin main
Short, descriptive, and prefixed by purpose.
feature/user-authentication
fix/cart-total-rounding
docs/installation-guide
chore/update-dependencies
test/payment-service
refactor/api-client
Two simple rules for a clean history.
Keeps feature history compact. Removes noisy WIP commits. One logical commit per feature.
Preserves the boundary between integration and stable history. Makes promotion clear.
Clean Flow sits between GitHub Flow and Git Flow.
| GitHub Flow | Clean Flow | Git Flow | |
|---|---|---|---|
| Integration branch | None | dev | develop |
| Release branches | No | No | Yes |
| Hotfix branches | No | No | Yes |
| Feature target | main | dev | develop |
| Complexity | Low | Medium | High |
Teach your AI assistant Clean Flow in one copy-paste.
Add branch workflow instructions to your project.
mkdir -p .github/instructions
curl -o .github/instructions/copilot.instructions.md \
https://raw.githubusercontent.com/wgtechlabs/clean-flow/main/examples/copilot.instructions.md
For Codex, Claude, Cursor, Windsurf, and more.
curl -o AGENTS.md \
https://raw.githubusercontent.com/wgtechlabs/clean-flow/main/examples/AGENTS.md
Everything you need to remember.
main stabledev as the integration branchdevdevdevdev into main when stablemaindevmain and dev