git-branching
Select, document, and evolve a Git branching strategy for a repository. Use when comparing Gitflow, GitHub Flow, trunk-based development, feature branches, release branches, or concurrent version line
SKILL.mdcontext/skills/engineering/git-branching/SKILL.md
GitHubGit Branching
Intro
Choose a branching strategy from the repository's delivery cadence, supported versions, deployment environments, and release controls. Then write a small branch contract that makes integration and tagging authority unambiguous.
Overview
Select a strategy
Answer these questions before naming branches:
- Is
maincontinuously deployable, or is there a separate release gate? - Are older versions supported while new major work continues?
- Do environments promote the same commit through test and production?
- Can incomplete work be hidden with feature flags?
- Is the team able to keep shared branches continuously integrated?
Use the smallest model that meets those constraints.
| Strategy | Best fit | Long-lived branches | Release authority |
|---|---|---|---|
| Feature Branch Workflow | Shared integration branch, periodic releases | integration branch | integration or release branch |
| GitHub Flow | Frequent deployment and one supported production line | main |
main |
| Trunk-Based Development | Strong CI, feature flags, rapid integration | main; optional short release branch |
main or just-in-time release branch |
| Gitflow | Scheduled releases and formal stabilization | main, develop, temporary release branches |
release branch |
| GitLab Flow | Environment promotion or maintained stable lines | main, environment or stable branches |
production or stable branch |
| Version-line integration | Concurrent major lines or long-lived maintenance | one dev and release branch per line | designated line release branch |
Read strategy catalog before choosing a model with release branches, multiple environments, or concurrent version lines.
Write the branch contract
For each protected long-lived branch, record:
- purpose and allowed changes;
- source branches and merge direction;
- tag authority and release validation command;
- hotfix and backport path;
- required checks, review, force-push, and deletion policy.
Keep task branches short-lived and name them according to git-workflow.
Use merge commits for meaningful integration between long-lived branches;
use the repository's chosen merge method for task branches.
Apply the version-line integration model
Use this model when v0 maintenance and v1 development, or any two supported major lines, must progress independently:
line.x-dev -> line.x-release -> tag stable release -> main
next.x-dev -> next.x-pre-release -> tag alpha/beta/rc
-> next.x-release -> tag GA -> main
- Create
line.x-releasefrom the latest stable tag andline.x-devfrom that release branch. - Merge development into the release branch, validate there, and tag only
there. Merge the tagged stable release into
mainimmediately afterwards. - For prereleases, merge development into
next.x-pre-releaseand tag only on that branch. Createnext.x-releaseonly for general availability. - Hotfix from the latest stable tag, then merge to the release branch, tag,
merge to
main, and merge back to the development branch.
Gotchas
- Treating
mainas both active development and release authority. This makes concurrent version lines indistinguishable. State whethermainis trunk or published history before creating branches. - Copying Gitflow mechanically. Gitflow's
developand release branches add synchronization cost. Choose it only when scheduled stabilization or parallel release preparation needs that cost. - Tagging a development branch. A development head may not have passed integration checks. Tag only the contract's designated release branch.
- Using environment branches as feature integration branches. Environment branches promote tested commits; they are not a substitute for a developer integration target unless the contract explicitly says so.
- Forgetting the return path for hotfixes. A production fix that is not merged back into active development will recur in the next release.
- Protecting a branch without defining how automation merges it. Check required reviews, checks, merge queue, and allowed merge methods before making the branch the only release path.
Full reference
Required output
Deliver a branch contract in this form:
Strategy:
Reason for fit:
Protected branches:
Merge directions:
Tag authority:
Hotfix and backport policy:
Required checks and release commands:
Migration steps and rollback point:
Do not migrate a live repository by renaming, deleting, or force-updating branches until its existing tags, release consumers, and protection rules have been inspected.
Anti-patterns
- A branch per person or indefinitely open feature branch. Prefer a focused task branch and merge it promptly.
- A release branch for every routine deployment. If the product can release directly from a healthy trunk, extra release branches add delay.
- One undocumented catch-all branch. A branch without a stated authority eventually receives incompatible development, release, and hotfix changes.
Cross-references
- Strategy catalog
git-workflow— naming, commits, pull requests, and merge methodsrelease-semver— changelog, tags, publishing, and release verification