~/gitmomentum (main) $ cat README.md

# Git Momentum

A Git workflow that keeps teams moving.

Lightweight yet precise and clean. Few rules, low overhead, a repository that stays readable over years — with controlled releases, hotfixes, and auditable history built in.

how-it-works read-the-spec

$ 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 stays append-only. update/* branches sprout and squash-merge back. testing, staging, and production are labels into main's history. A hotfix/* squash-merges into production and is back-merged into main.

three commitments

Main is append-only; deployment branches are labels on it. Commits on main never change. Each deployment branch is a pointer into main's history — its 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
production approval mechanism

read-the-spec

$ gitmomentum init

Get started

read the spec
set branch protection
- no force-push
- squash-merge into main and production
- fast-forward only on deployment branches
pick a commit message convention
pick a version tag pattern
wire deployment pipelines to push events
- with an approval gate on production

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. For production, the pipeline pauses for the approval step your team has configured.

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.

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.