Release Git Flow

Release Git Flow

Use only the origin remote. Prepare releases from internal dev work as one squash commit on main, with an annotated version tag on that commit.

Preserve these invariants

• Keep internal development commits on dev and synchronize them with origin/dev.
• Keep release commits on main and synchronize them with origin/main.
• Represent each release on main as one squash commit.
• Create release tags only on main release commits.
• Push main and release tags only to origin.
• Never force-push, rewrite shared history, replace a tag, or resolve unexpected divergence without explicit user approval.

Inspect and refresh

Require a clean worktree. Preserve unrelated user changes. Run:

git status --short --branch
git remote get-url origin
git branch --all --verbose --no-abbrev
git log --oneline --decorate --graph -20 --all
git fetch origin dev main --tags

Stop if local dev or main has unexpected divergence from its corresponding origin branch. Do not silently merge, rebase, reset, or force-push.

Select the release

Obtain the version from the user; do not guess it. Prefer the existing vMAJOR.MINOR[.PATCH] tag style. Confirm that the version is absent locally and on origin:

RELEASE_VERSION=v1.6
git tag --list "$RELEASE_VERSION"
git ls-remote --tags origin "refs/tags/$RELEASE_VERSION" "refs/tags/$RELEASE_VERSION^{}"

Squashed release history may not share ancestry with internal development history. Compare patch equivalence and the net tree change instead of assuming origin/main is an ancestor of origin/dev:

git log --left-right --cherry-mark --oneline origin/main...origin/dev
git diff --stat origin/main..origin/dev
git diff --check origin/main..origin/dev

Identify the exact unreleased internal commits, order them oldest to newest, and obtain user confirmation when the intended set is ambiguous. Exclude commits whose patches are already represented on origin/main. Review the resulting files for secrets, internal-only material, generated files, and unintended changes.

Build a clean release source

Create a temporary source branch from origin/main, then cherry-pick only the confirmed commits in oldest-to-newest order:

git switch --create "release/$RELEASE_VERSION-source" origin/main
git cherry-pick COMMIT_1 COMMIT_2
git log --reverse --oneline origin/main..HEAD
git diff --stat origin/main..HEAD
git diff --check origin/main..HEAD

Replace the example commit names with the confirmed commit IDs. Stop on conflicts and inspect them rather than resolving automatically. Run tests appropriate to the selected changes.

Prepare main and its tag

Fast-forward local main from origin/main, squash the verified release source, and review the complete staged diff:

git switch main
git merge --ff-only origin/main
git merge --squash "release/$RELEASE_VERSION-source"
git diff --cached --stat
git diff --cached --check

Commit once and create an annotated tag:

git commit -m "Release $RELEASE_VERSION"
git tag -a "$RELEASE_VERSION" -m "Release $RELEASE_VERSION"
git show --stat --decorate --oneline HEAD
test "$(git rev-parse HEAD)" = "$(git rev-parse "$RELEASE_VERSION^{}")"

Stop here when the user asks only to prepare a release. State clearly that main and the tag are local.

Publish when requested

Ask for confirmation immediately before publishing and show the exact destination. Push the branch before its tag:

git push origin main
git push origin "$RELEASE_VERSION"

Do not force-push or use --tags. Verify the resulting remote branch and tag after publishing.

Report the outcome

State the selected internal commits, release commit, version tag, tests run, and whether anything was pushed. Call out unresolved divergence, conflicts, or validation gaps.