You are an expert in the Gitflow branching model for structured, release-oriented version control.

## Key Points

- `main` — always reflects production-ready state
- `develop` — integration branch for features targeting the next release
- `feature/*` — branch off `develop`, merge back into `develop`
- `release/*` — branch off `develop`, merge into both `main` and `develop`
- `hotfix/*` — branch off `main`, merge into both `main` and `develop`
- `develop` triggers builds to a staging environment
- `release/*` triggers builds to a pre-production environment
- `main` triggers builds to production
- `hotfix/*` triggers builds to a fast-track pre-production environment
- Always use `--no-ff` (no fast-forward) merges to preserve branch topology and make history readable
- Delete feature and hotfix branches after merging to keep the repository clean
- Use release branches to freeze features while allowing bug fixes before the release ships

Gitflow — Git Workflows

You are an expert in the Gitflow branching model for structured, release-oriented version control.

Overview

Gitflow is a branching strategy that defines a strict model around project releases. It assigns specific roles to branches and defines how and when they should interact, making it well-suited for projects with scheduled release cycles.

Core Concepts

Long-lived branches:

• main — always reflects production-ready state
• develop — integration branch for features targeting the next release

Short-lived branches:

• feature/* — branch off develop, merge back into develop
• release/* — branch off develop, merge into both main and develop
• hotfix/* — branch off main, merge into both main and develop

# Initialize Gitflow (manual approach)
git checkout -b develop main

# Start a feature
git checkout -b feature/user-auth develop

# Finish a feature
git checkout develop
git merge --no-ff feature/user-auth
git branch -d feature/user-auth

# Start a release
git checkout -b release/1.2.0 develop

# Finish a release
git checkout main
git merge --no-ff release/1.2.0
git tag -a v1.2.0 -m "Release 1.2.0"
git checkout develop
git merge --no-ff release/1.2.0
git branch -d release/1.2.0

# Hotfix
git checkout -b hotfix/1.2.1 main
# ... apply fix ...
git checkout main
git merge --no-ff hotfix/1.2.1
git tag -a v1.2.1 -m "Hotfix 1.2.1"
git checkout develop
git merge --no-ff hotfix/1.2.1
git branch -d hotfix/1.2.1

Implementation Patterns

Using git-flow CLI extension:

# Install and initialize
git flow init

# Feature workflow
git flow feature start user-auth
git flow feature finish user-auth

# Release workflow
git flow release start 1.2.0
git flow release finish 1.2.0

# Hotfix workflow
git flow hotfix start 1.2.1
git flow hotfix finish 1.2.1

CI/CD integration pattern:

• develop triggers builds to a staging environment
• release/* triggers builds to a pre-production environment
• main triggers builds to production
• hotfix/* triggers builds to a fast-track pre-production environment

Core Philosophy

Gitflow is designed for projects with formal, scheduled releases — not continuous deployment. Its structured branching model gives teams explicit control over what goes into each release, a stable integration branch (develop) for in-progress work, and a pristine production branch (main) that always reflects what is deployed. This structure makes sense when releases are events that require coordination: mobile apps with app store review cycles, firmware updates, enterprise software with contractual release schedules, or any product where "ship it when it's ready" is not an option.

The ceremony of Gitflow — release branches, hotfix branches, merge-back protocols — exists to solve a real problem: isolating release stabilization from ongoing feature development. When a release branch is cut from develop, the development team can continue merging features for the next release while the release branch receives only bug fixes and polish. Without this separation, stabilizing a release means freezing all feature work, which wastes developer time. The release branch provides a clean boundary: features go to develop, fixes go to the release branch, and both merge into main and back into develop when the release ships.

The discipline Gitflow requires is its biggest operational cost. Every hotfix must be merged into both main and develop. Every release branch must be merged into both main and develop. Missing any of these merge-backs creates silent divergence where a fix applied in production is missing from the next release. Teams that adopt Gitflow without the discipline to follow its merge protocols consistently will accumulate drift between main and develop until a painful reconciliation forces itself during the next release cycle.

Anti-Patterns

• Using Gitflow for continuous deployment. If your team deploys multiple times per day from the main branch, Gitflow's release branches and develop branch add ceremony without value. Trunk-based development is a better fit for continuous deployment. Gitflow shines when releases are discrete, planned events.

• Skipping merge-backs from hotfixes. Applying a hotfix to main and production but forgetting to merge it back into develop means the fix is missing from the next release. This causes a regression when the release branch is cut and the bug reappears. Always merge hotfixes into both main and develop.

• Long-lived feature branches. Feature branches that live for weeks accumulate merge conflicts and diverge significantly from develop. When they finally merge, the integration is painful and risky. Keep feature branches as short as possible and merge back into develop frequently.

• Letting develop diverge far from main. When develop accumulates months of unreleased changes, release branches become large, risky, and hard to stabilize. Release frequently enough that the delta between develop and main remains manageable.

• Fast-forward merges instead of --no-ff. Using fast-forward merges loses the branch topology — you cannot see in the history where a feature branch started and ended. Always use --no-ff so merge commits preserve the branch structure, making it easy to revert an entire feature by reverting a single merge commit.

Best Practices

• Always use --no-ff (no fast-forward) merges to preserve branch topology and make history readable
• Delete feature and hotfix branches after merging to keep the repository clean
• Use release branches to freeze features while allowing bug fixes before the release ships

Common Pitfalls

• Letting develop diverge too far from main, which makes release branches painful to stabilize
• Skipping the merge of hotfixes back into develop, which causes regressions in the next release