Manage Work with Git Flow

---
name: "mastering-git-flow"
description: "Choose and operate a practical Git Flow workflow for features, releases, and hotfixes while protecting shared branches and keeping history reviewable."
---

# Manage Work with Git Flow

Use this skill when a repository follows Git Flow or when a team needs a branching and release procedure with `main`, `develop`, feature, release, and hotfix branches.

## Confirm suitability

Git Flow fits versioned releases and parallel release stabilization. For continuous deployment with short-lived branches, recommend a simpler trunk-based workflow instead of adding ceremony.

## Branch roles

- `main`: production history and release tags.
- `develop`: integration branch for the next release.
- `feature/<name>`: short-lived work branched from `develop`.
- `release/<version>`: stabilization branched from `develop`.
- `hotfix/<name>`: urgent production repair branched from `main`.

Respect different names defined by the repository.

## Feature workflow

1. Update local knowledge of the remote and confirm the working tree state.
2. Branch from the current `develop`.
3. Keep commits focused and use the repository's commit convention.
4. Reconcile with `develop` according to team policy and resolve conflicts carefully.
5. Run required validation before opening or merging the review.
6. Merge through the repository's protected-branch process, then remove the completed feature branch when authorized.

## Release workflow

1. Create `release/<version>` from `develop` when the release scope is frozen.
2. Allow only release fixes, metadata, documentation, and version changes.
3. Validate the release candidate.
4. Merge into `main`, create the release tag, and merge the same fixes back into `develop`.

## Hotfix workflow

1. Branch from the production commit on `main`.
2. Make the smallest safe fix and add regression coverage.
3. Validate, merge into `main`, and tag the patch release.
4. Merge the fix back into `develop` and any active release branch that needs it.

## Safety rules

- Never discard local changes or rewrite shared history without explicit authorization.
- Do not force-push protected branches.
- Inspect the exact branch and commit targets before merging, tagging, or deleting.
- Surface conflicts and release uncertainty instead of guessing.
- Report the final branch, validation status, and follow-up merges still required.