Git Momentum — A Git workflow that keeps teams moving

$ git log main --oneline # the everyday cost

The everyday cost of most Git workflows

a3f9c1d everyone commits differently — main reads like five diaries
8b22e4f merge commits in every direction, history unreadable a week later
c1e7a90 long-lived feature branches drift from main until merging is its own project
5d44b2e a changelog that's always out of date or someone's Friday chore
9e0a37b "what's on staging right now?" — answered in Slack, sometimes correctly

$ git diff workflow # what you get

What you get

developer freedom on working branches Commit however you want. The squash on merge turns whatever your branch looked like into one clean commit on main.
a history a human can read Near-linear. Every commit reviewed and described. git log main reads like a project diary.
always know what's deployed Each deployment branch's tip is what's live. No drift, no dashboard, no doubt.
no changelog maintenance The commit log on main is the changelog. Generate it on demand.
hotfixes that don't fork the project Straight to production, then back to main. Audit trail intact.

$ git momentum --explain

How it works

main is a clean, near-linear changelog of shipped changes. update/* branches sprout and squash-merge back as one commit each. testing, staging, and production are pointers into main's history. A hotfix/* squash-merges into production and is back-merged into main.

three commitments

Main reads like a changelog. Each update lands as one self-contained commit on main, in order — a clean, near-linear history that's actually readable. Deployment branches are just pointers into that history; each branch's tip is what's deployed.

Working branches stay short. Merge into main as soon as a change is ready to exist, not when it's ready to release. Feature flags handle the gap.

Versions, deployment state, and changelogs are derived, not stored. Tags give you versions. Branch pointers give you deployment state. Commit messages give you changelogs.

two flows

Standard change. branch from main → commit freely → PR → squash-merge → promote.

Hotfix. branch from production → PR → squash-merge into production → back-merge into main.

That's the whole model.

$ git momentum --compare

How it compares

vs. Git Flow

Same precision, fewer branches and rules.

No develop branch, no release branches.

vs. GitHub Flow

Same lightness, plus a defined release model.

Stages, hotfixes, versions, and changelogs all built in.

vs. Trunk-based

Same trunk-centric philosophy.

With explicit staged deployment, hotfixes, and feature flags.

$ gitmomentum init --interactive

What a team needs to decide

Git Momentum expects to be tailored. A team defines:

branch names and prefixes
commit message convention
version tag pattern
direct push policy — and for whom
PR review policy
deployment approval mechanism

Capture these decisions in a document that lives with the repository. See this project's own PROJECT.md for one example.

read-the-spec

$ gitmomentum init

Get started

read the spec
set branch protection
- no force-push
- squash-merge only for pull requests
- fast-forward only on deployment branches
pick a commit message convention
pick a version tag pattern
wire deployment pipelines to push events
- with approval gates

read-the-spec

$ man gitmomentum # frequently asked

FAQ

How do I deploy to a stage?

Three commands:

$ git checkout <stage>
$ git merge --ff-only <commit-or-main>
$ git push

The push triggers the deployment pipeline. --ff-only ensures you can't accidentally push a non-fast-forward. If the stage has an approval gate, the pipeline pauses for approval before deploying.

Should I open a pull request to promote to a deployment branch?

Only if your Git platform supports fast-forward-only merges in PRs. Most don't — their default "merge" creates a merge commit, which would break the fast-forward rule on deployment branches. Use the Git CLI above instead.

Doesn't squash-merging mean I have to rebase first?

No. Rebasing is never required in Git Momentum — not here, not anywhere. Merge main into your branch whenever you want to stay current; the squash on merge discards your branch's internal history anyway.

How do I ensure commit message quality?

Codify your convention so an AI coding agent enforces it on every commit. An AI skill — for example a Cursor skill — captures the rules in a form the agent reads and follows. See this project's own commit skill for one example.

What's the recommended way to do versioning?

Pick a tag pattern, define the bump rules, and let an AI coding agent apply them consistently. An AI skill — for example a Cursor skill — captures the rules in a form the agent reads and follows on every release. See this project's own version skill for one example.

Is Git Momentum hard to learn?

No — provided your team understands how Git and Git histories work. That's a baseline they should have anyway. Git Momentum is just a handful of conventions on top.

# Git Momentum