{{{bodyHtml}}}

Introduction

En brefIn short

SmartStack pilote GitFlow avec la commande /gitflow : chaque travail vit dans sa branche (feature, release ou hotfix), isolée dans son propre worktree. Chaque étape — création, commit, PR, merge, finalisation — passe par un CLI qui applique les règles de branches et les gardes EF Core. Seul le tag vX.Y.Z posé sur main par /gitflow finish part en production.

SmartStack drives GitFlow with the /gitflow command: each piece of work lives in its own branch (feature, release or hotfix), isolated in its own worktree. Every step — start, commit, PR, merge, finish — goes through a CLI that enforces the branch rules and the EF Core guards. Only the vX.Y.Z tag placed on main by /gitflow finish goes to production.

GitFlow est un modèle de branchement Git adapté aux cycles de release planifiés et aux équipes de plusieurs développeurs. Les CLI gèrent le versioning, les migrations EF Core et les gates avant production ; la revue et le merge vers main restent des étapes humaines.

GitFlow is a Git branching model suited to planned release cycles and multi-developer teams. The CLIs handle versioning, EF Core migrations and the pre-production gates; review and the merge into main remain human steps.

Quick Start

Les commandes du quotidien. Les flags -f, -r et -h créent toujours une branche du type correspondant.

Everyday commands. The -f, -r and -h flags always start a branch of the matching type.

ActionAction CommandeCommand
Démarrer une feature (depuis develop)Start a feature (from develop) /gitflow -f <nom><name>
Démarrer une release (depuis develop)Start a release (from develop) /gitflow -r <version>
Démarrer un hotfix (depuis main)Start a hotfix (from main) /gitflow -h <version>
Commiter (gardes EF Core)Commit (EF Core guards) /gitflow commit
Rattraper la branche de baseCatch up with the base branch /gitflow update
Ouvrir la Pull RequestOpen the Pull Request /gitflow pr
Merger la PR après revueMerge the PR after review /gitflow merge
Finaliser (tag, merge-back, nettoyage)Finish (tag, merge-back, cleanup) /gitflow finish
Voir l'état du dépôtShow the repository state /gitflow status · /gitflow -s
Mode auto : création → commit → PR, puis arrêt pour la revueAuto mode: start → commit → PR, then stop for review /gitflow -f <nom><name> -a

Le nom d'une release ou d'un hotfix est sa version SemVer : /gitflow -r 2.1.0 crée release/2.1.0, que finish taguera v2.1.0. Sans version, -r la demande — elle n'est jamais inventée. -a ne lance jamais merge ni finish.

A release or hotfix is named after its SemVer version: /gitflow -r 2.1.0 creates release/2.1.0, which finish will tag v2.1.0. Without a version, -r asks for it — it is never invented. -a never runs merge or finish.

/gitflow -f user-auth   # feature/user-auth ← develop
/gitflow commit          # 1..n
/gitflow pr              # PR → develop
                         # ‖ review ‖
/gitflow merge           # squash → develop
/gitflow finish          # branch + worktree removed

Concepts clés Key Concepts

Voir SemVer et la stratégie de mergeShow SemVer and the merge strategy

SemVer (Semantic Versioning)

Le versioning sémantique utilise le format MAJOR.MINOR.PATCH. Une release porte une version MINOR ou MAJOR, un hotfix une version PATCH ; après finish, develop passe à la version de développement suivante.

Semantic versioning uses the MAJOR.MINOR.PATCH format. A release carries a MINOR or MAJOR version, a hotfix a PATCH version; after finish, develop moves to the next development version.

Type Quand incrémenterWhen to increment ExempleExample
MAJOR Changements cassants, API incompatibleBreaking changes, incompatible API 1.0.0 → 2.0.0
MINOR Nouvelles fonctionnalités rétrocompatiblesNew backwards-compatible features 1.0.0 → 1.1.0
PATCH Corrections de bugs rétrocompatiblesBackwards-compatible bug fixes 1.0.0 → 1.0.1

Stratégie de merge

Merge Strategy

Une feature entre dans develop en squash (un commit par feature). Une release ou un hotfix entre dans main par un merge commit (--no-ff), comme le merge-back main → develop, pour préserver l'historique :

A feature enters develop as a squash (one commit per feature). A release or hotfix enters main through a merge commit (--no-ff), like the main → develop merge-back, to preserve history:

# --no-ff : merge commit
*   Merge branch 'release/2.1.0' into main
|\
| * fix: correct invoice rounding
| * chore: set version to 2.1.0
|/
*   Previous commit

# fast-forward : linear history (branch context lost)
* fix: correct invoice rounding
* chore: set version to 2.1.0
* Previous commit

Types de branches Branch Types

M
main / master
Production

Branche de production. Chaque tag représente une version déployée. Protégée contre les push directs.

Production branch. Each tag represents a deployed version. Protected from direct pushes.

Protected
D
develop
Intégration
Integration

Branche d'intégration. Reçoit les features terminées. Base des nouvelles features et des releases.

Integration branch. Receives completed features. Base for new features and releases.

Protected
F
feature/*
Nouvelles fonctionnalités
New features

Branches de développement. Créées depuis develop, intégrées dans develop en squash. Ne changent pas la version.

Development branches. Created from develop, squashed into develop. They do not change the version.

squash
R
release/*
Préparation de release
Release preparation

Préparation d'une nouvelle version. Créée depuis develop, mergée dans main puis ramenée dans develop (merge-back). Tag posé par finish.

Preparation of a new version. Created from develop, merged into main then brought back into develop (merge-back). Tag placed by finish.

+tag
H
hotfix/*
Corrections urgentes
Urgent fixes

Corrections critiques en production. Créée depuis main, mergée dans main puis ramenée dans develop (merge-back). Version PATCH.

Critical production fixes. Created from main, merged into main then brought back into develop (merge-back). PATCH version.

+patch
{{> deploy-flow hideEnvs=true}}

Le rôle de chaque environnement et les validations sont décrits sur la page Gestion du code et déploiement.

The role of each environment and the approvals are described on the Code management and deployment page.

Quand utiliser quelle commande ? When to use which command?

💡
Intégration par Pull Request
Integration through a Pull Request

Séquence complète : /gitflow pr → revue → /gitflow merge → /gitflow finish. merge applique la stratégie du type de branche (squash pour une feature, merge commit pour release et hotfix) ; finish pose le tag (release, hotfix), fait le merge-back main → develop et supprime la branche et son worktree.

Full sequence: /gitflow pr → review → /gitflow merge → /gitflow finish. merge applies the branch-type strategy (squash for a feature, merge commit for release and hotfix); finish tags (release, hotfix), merges back main → develop and removes the branch and its worktree.

🗑
Suppression des branches remote
Remote Branch Deletion

/gitflow finish supprime la branche en local et sur le remote. Pour les worktrees orphelins, utilisez /gitflow cleanup.

/gitflow finish deletes the branch locally and on the remote. For orphan worktrees, use /gitflow cleanup.

BesoinNeed CommandeCommand
Nouvelle fonctionnalitéNew feature /gitflow -f <nom><name> → commit → pr → merge → finish
Livrer en production (release)Ship to production (release) /gitflow -r <version> → commit → pr → merge → finish (tag + merge-back)(tag + merge-back)
Bug urgent en production (hotfix)Urgent production bug (hotfix) /gitflow -h <version> → commit → pr → merge → finish (tag + merge-back)(tag + merge-back)
UtilitairesUtilities /gitflow status · /gitflow update · /gitflow abort · /gitflow cleanup

Environnements et déploiement Environments and deployment

Chaque branche alimente un environnement précis : feature/* tourne sur le poste de dev ; develop alimente TEST (intégration continue) ; release/* passe en QUAL (recette métier) puis en PREPROD (répétition de la mise en production) ; main + tag vX.Y.Z part en PROD, après approbation de l'IT ; hotfix/* est vérifié en PREPROD puis livré en PROD via son merge dans main + tag, suivi du merge-back automatique vers develop. La promotion d'un environnement au suivant est toujours un merge, jamais un déploiement croisé.

Each branch feeds one specific environment: feature/* runs on the developer machine; develop feeds TEST (continuous integration); release/* goes to QUAL (business acceptance) then PREPROD (production rehearsal); main + a vX.Y.Z tag goes to PROD, after IT approval; hotfix/* is verified in PREPROD then delivered to PROD through its merge into main + tag, followed by the automatic merge-back into develop. Promotion from one environment to the next is always a merge, never a cross deployment.

⚠️
Les gates avant PROD
The gates before PROD

Toute PR vers main passe deux gates automatiques : la parité des migrations (aucune migration déjà en production ne peut disparaître de la branche — remède : /gitflow update) et le delta de seed Core (un changement de nav/RBAC seedé exige son script SQL de delta). S'y ajoute l'approbation manuelle du déploiement PROD dans le pipeline.

Every PR to main goes through two automatic gates: migration parity (no migration already in production may vanish from the branch — remedy: /gitflow update) and the Core seed delta (a seeded nav/RBAC change requires its SQL delta script). On top of that, the PROD deployment requires manual approval in the pipeline.

Le détail des environnements, des validations et des approbations se trouve sur la page Gestion du code et déploiement.

Environments, validations and approvals are detailed on the Code management and deployment page.

Architecture & structure Architecture & Structure

Voir les worktrees et la configurationShow worktrees and configuration

Structure des worktrees

Worktrees Structure

GitFlow isole chaque branche dans son propre dossier grâce aux git worktrees : on travaille sur plusieurs branches en parallèle, sans checkout. La racine porte le dépôt bare (.git/) et la configuration partagée ; 01-Main et 02-Develop sont permanents (main / develop si les dossiers ne sont pas numérotés).

GitFlow isolates each branch in its own directory with git worktrees: you work on several branches in parallel, without checkout. The root holds the bare repository (.git/) and the shared configuration; 01-Main and 02-Develop are permanent (main / develop when folders are not numbered).

my-project/
├── .git/                  # bare
├── .gitflow/
│   └── config.json
├── 01-Main/               # main
├── 02-Develop/            # develop
├── features/
│   ├── user-auth/         # feature/user-auth
│   └── payment-gateway/   # feature/payment-gateway
├── releases/
│   └── 1.2.0/             # release/1.2.0
└── hotfixes/
    └── 1.1.1/             # hotfix/1.1.1

Fichiers de configuration

Configuration Files

FichierFile DescriptionDescription
.gitflow/config.json Configuration principale : versioning, branches, EF Core, worktrees. À la RACINE du dépôt, partagée par tous les worktrees (l'ancien emplacement .claude/gitflow/ est migré automatiquement).Main configuration: versioning, branches, EF Core, worktrees. At the repository ROOT, shared across worktrees (the legacy .claude/gitflow/ location is migrated automatically).

Création automatique

Automatic Creation

/gitflow init <url> crée toute la structure en un appel, après confirmation du nom du projet et du nommage des dossiers ; il n'installe rien d'autre. Chaque -f, -r ou -h crée ensuite le worktree de sa branche, que /gitflow finish supprime. Pour travailler sans worktree, passez worktrees.enabled à false dans .gitflow/config.json : la branche est alors créée dans le dossier courant.

/gitflow init <url> creates the whole structure in one call, after the project name and folder naming are confirmed; it installs nothing else. Each -f, -r or -h then creates its branch's worktree, which /gitflow finish removes. To work without worktrees, set worktrees.enabled to false in .gitflow/config.json: the branch is then created in the current directory.

/gitflow init https://github.com/org/my-project.git
/gitflow -f user-auth
# → my-project/features/user-auth/

Bonnes pratiques Best Practices

Voir les 6 bonnes pratiquesShow the 6 best practices

✅ Nommage des branches Branch Naming

Feature : un nom descriptif en kebab-case. Release et hotfix : la version SemVer, qui devient le tag.

Feature: a descriptive kebab-case name. Release and hotfix: the SemVer version, which becomes the tag.

# OK
feature/user-authentication
feature/add-payment-gateway
release/2.1.0
hotfix/2.0.1

# KO
feature/auth
feature/MyNewFeature
release/new
hotfix/fix

✅ Commits atomiques Atomic Commits

Chaque commit représente un changement logique unique. Utilisez /gitflow commit pour des commits structurés.

Each commit represents a single logical change. Use /gitflow commit for structured commits.

# OK
feat(auth): add login form component
feat(auth): implement JWT token validation
fix(auth): handle expired token refresh

# KO
WIP: auth stuff

✅ Se mettre à jour avant la PR Catch Up Before the PR

/gitflow pr signale une feature en retard sur develop. Lancez /gitflow update : il merge la base dans votre branche et, en cas de conflit, abandonne proprement en laissant la branche intacte.

/gitflow pr flags a feature that lags behind develop. Run /gitflow update: it merges the base into your branch and, on conflict, aborts cleanly and leaves the branch intact.

✅ Ne jamais pousser sur main directement Never Push to Main Directly

Toute modification passe par une branche feature, release ou hotfix et sa PR. Les CLI refusent une PR ou un merge dont la cible contredit le type de branche (une feature ne cible jamais main).

Every change goes through a feature, release or hotfix branch and its PR. The CLIs refuse a PR or merge whose target contradicts the branch type (a feature never targets main).

🗑 Nettoyer régulièrement les worktrees Regularly Clean Up Worktrees

/gitflow finish supprime le worktree de la branche finalisée. Pour un audit complet, lancez /gitflow cleanup depuis main ou develop.

/gitflow finish removes the finished branch's worktree. For a full audit, run /gitflow cleanup from main or develop.

✅ Tester avant de merger Test Before Merging

Build et tests doivent être verts avant /gitflow pr. La revue reste une étape humaine : le mode -a s'arrête toujours à la PR.

Build and tests must be green before /gitflow pr. Review remains a human step: -a mode always stops at the PR.

⚠
Éviter les anti-patterns
Avoid Anti-patterns
❌ Ne jamais forcer un push sur main ou develop Never force push to main or develop
❌ Ne pas merger une feature non testée Don't merge an untested feature
❌ Ne pas laisser des branches ouvertes trop longtemps Don't leave branches open too long
❌ Ne pas ignorer les conflits de ModelSnapshot (EF Core) Don't ignore ModelSnapshot conflicts (EF Core)

Commandes GitFlow GitFlow Commands

SmartStack CLI fournit 12 commandes GitFlow (la 12e, generate-msg, est un CLI interne qui formate le message de commit). Les raccourcis -f, -r, -h, -s et -a sont décrits dans le Quick Start.

SmartStack CLI provides 12 GitFlow commands (the 12th, generate-msg, is an internal CLI that formats the commit message). The -f, -r, -h, -s and -a shorthands are described in the Quick Start.

/gitflow init Setup

Construit l'infrastructure Git en un appel : clone bare dans <racine>/.git, worktrees 01-Main et 02-Develop, dossiers features/, releases/, hotfixes/ et .gitflow/config.json. Le nom, l'emplacement et le nommage des dossiers (numérotés ou non) sont confirmés avant création. Ne scaffolde jamais l'application.

Builds the Git infrastructure in one call: bare clone into <root>/.git, 01-Main and 02-Develop worktrees, features/, releases/, hotfixes/ folders and .gitflow/config.json. Name, location and folder naming (numbered or not) are confirmed before creation. It never scaffolds the application.

/gitflow init <url>
/gitflow -f | -r | -h Branch

Crée la branche depuis sa base, dans son worktree, et la pousse. Pour une release ou un hotfix, le premier commit fixe la version dans les sources (chore: set version to X.Y.Z) ; des noms de migrations EF Core non conformes déclenchent un avertissement qui propose /efcore squash.

Creates the branch from its base, in its worktree, and pushes it. For a release or hotfix, the first commit sets the version in the sources (chore: set version to X.Y.Z); non-compliant EF Core migration names raise a warning suggesting /efcore squash.

/gitflow -f authentication
/gitflow -r 2.1.0
/gitflow -h 2.0.1
/gitflow commit Git

Commit contrôlé : vérifie que chaque migration EF Core est complète (migration, Designer, ModelSnapshot) — sinon les fichiers Migrations/ sont exclus du commit —, demande confirmation pour une opération destructive (DropTable, DropColumn, DeleteData) et génère un message si aucun n'est fourni. Ne pousse pas par défaut.

Guarded commit: checks that every EF Core migration is complete (migration, Designer, ModelSnapshot) — otherwise the Migrations/ files are excluded from the commit —, asks for confirmation on a destructive operation (DropTable, DropColumn, DeleteData) and generates a message when none is given. Does not push by default.

/gitflow commit
/gitflow sync Git

Synchronise la branche courante avec son homologue sur origin : fetch, pull si le remote est en avance, push si le local est en avance, en mettant de côté les modifications non commitées. Ne touche jamais à la branche de base — pour rattraper develop ou main, utilisez /gitflow update.

Synchronizes the current branch with its origin counterpart: fetch, pull when the remote is ahead, push when local is ahead, setting uncommitted changes aside. It never touches the base branch — to catch up with develop or main, use /gitflow update.

/gitflow sync
/gitflow update Git

Met à jour la branche courante depuis sa base : origin/develop pour une feature ou une release, origin/main pour un hotfix. Merge par défaut ; en cas de conflit, abandonne et laisse la branche intacte (conflits EF Core : /efcore rebase-snapshot). C'est le remède quand le gate de parité des migrations bloque une PR vers main.

Updates the current branch from its base: origin/develop for a feature or release, origin/main for a hotfix. Merge by default; on conflict it aborts and leaves the branch intact (EF Core conflicts: /efcore rebase-snapshot). It is the remedy when the migration-parity gate blocks a PR to main.

/gitflow update
/gitflow pr PR

Ouvre la Pull Request vers la cible imposée par le type de branche : develop pour une feature, main pour une release ou un hotfix. Pousse les commits en attente, refuse une feature qui porte plus d'une migration (→ /efcore squash) et, vers main, applique les gates de parité des migrations et de delta de seed Core. Une PR brouillon est possible sur demande.

Opens the Pull Request to the target imposed by the branch type: develop for a feature, main for a release or hotfix. Pushes pending commits, refuses a feature carrying more than one migration (→ /efcore squash) and, towards main, enforces the migration-parity and Core seed delta gates. A draft PR is available on request.

/gitflow pr
/gitflow merge Merge

Merge la PR de la branche courante chez le provider (GitHub ou Azure DevOps) : squash pour une feature, merge commit pour une release ou un hotfix. Refuse une PR dont la cible contredit le type de branche et réaligne develop local avant et après le merge. Une étape humaine, après la revue.

Merges the current branch's PR at the provider (GitHub or Azure DevOps): squash for a feature, merge commit for a release or hotfix. Refuses a PR whose target contradicts the branch type and realigns local develop before and after the merge. A human step, after review.

/gitflow merge
/gitflow finish Branch

Finalise une branche après le merge de sa PR. Feature : supprime le worktree et la branche (locale et remote). Release ou hotfix : pose en plus le tag vX.Y.Z sur origin/main, fait le merge-back main → develop et passe develop à la version de développement suivante. Si le merge n'est pas confirmé, rien de destructif n'est fait.

Finishes a branch after its PR is merged. Feature: removes the worktree and the branch (local and remote). Release or hotfix: additionally places the vX.Y.Z tag on origin/main, merges back main → develop and moves develop to the next development version. If the merge cannot be confirmed, nothing destructive is done.

/gitflow finish
/gitflow status Info

Tableau de bord avant toute action : branche courante et son type, avance et retard par rapport à develop et main, état du working tree (merge ou rebase en cours), tags, et actions suggérées par priorité.

Dashboard before any action: current branch and its type, ahead/behind counts against develop and main, working tree state (merge or rebase in progress), tags, and suggested actions by priority.

/gitflow status
/gitflow abort Rollback

Filet de sécurité : détecte l'opération Git en cours (rebase, merge ou cherry-pick) et l'annule pour revenir à un état stable. Ne s'exécute que sur demande explicite.

Safety net: detects the Git operation in progress (rebase, merge or cherry-pick) and aborts it to return to a stable state. Runs only when explicitly requested.

/gitflow abort
/gitflow cleanup Maintenance

Audite les worktrees accumulés : main et develop sont permanents, ceux dont la branche est déjà mergée dans main sont signalés et ne sont supprimés qu'en mode forcé, puis git worktree prune est lancé. À exécuter depuis main ou develop.

Audits accumulated worktrees: main and develop are permanent, those whose branch is already merged into main are reported and only deleted in forced mode, then git worktree prune runs. Run it from main or develop.

/gitflow cleanup

Dans quel cas ? Which situation, which command?

Le réflexe « je suis dans tel cas → je fais cela » :

The "I am in this situation → I do this" reflex:

Je suis dans ce cas…I am in this situation… …alors je fais…then I do
Je commence un nouveau développementI start a new development /gitflow -f mon-sujet (feature depuis develop, worktree isolé)(feature from develop, isolated worktree)
Je veux voir ma feature tournerI want to see my feature running je la lance sur mon poste de dev — le seul environnement d'une feature ; TEST viendra après le merge dans developI run it on my developer machine — a feature's only environment; TEST comes after the merge into develop
Ma feature est terminéeMy feature is done /gitflow pr → revuereview → /gitflow merge → /gitflow finish
Ma branche est en retard sur developMy branch lags behind develop /gitflow update
Ma PR vers main est bloquée par le gate des migrationsMy PR to main is blocked by the migration gate /gitflow update (en gardant les DEUX côtés) puis nouvelle tentative de(keeping BOTH sides) then retry /gitflow pr
Je veux livrer la version x.y en clientèleI want to ship version x.y to customers /gitflow -r x.y.0 → recette en QUAL puis répétition en PREPROD →→ acceptance in QUAL then rehearsal in PREPROD → /gitflow pr → merge → finish (tag = PROD, après approbation de l'IT)(tag = PROD, after IT approval)
Bug critique en PRODCritical bug in PROD /gitflow -h x.y.z (depuis main) → vérification en PREPROD → merge + tag → le merge-back ramène le fix dans develop(from main) → verify in PREPROD → merge + tag → the merge-back brings the fix into develop
Un merge ou un rebase a mal tournéA merge or rebase went wrong /gitflow abort
De vieilles branches ou worktrees traînentOld branches or worktrees are lying around /gitflow cleanup
Je ne sais plus où j'en suisI no longer know where I stand /gitflow status

Exemple complet Complete Example

Voir l'exemple complet, de l'init à la releaseShow the complete example, from init to release

Un cycle complet avec SmartStack CLI : une feature, puis la release qui la livre.

A full cycle with SmartStack CLI: one feature, then the release that ships it.

# 1. init (once)
/gitflow init <url>

# 2. state
/gitflow status

# 3. feature: feature/user-dashboard ← develop
/gitflow -f user-dashboard
/gitflow commit
/gitflow pr
# ‖ review + approval ‖
/gitflow merge
/gitflow finish

# 4. release: release/1.3.0 ← develop (QUAL, then PREPROD)
/gitflow -r 1.3.0
/gitflow commit
# PR → main: migration parity + Core seed delta gates
/gitflow pr
# ‖ review + approval ‖
/gitflow merge
# tag v1.3.0 + merge-back → develop + cleanup
/gitflow finish

# 5. maintenance (from main or develop)
/gitflow cleanup
💡
Astuce
Tip

/gitflow status liste les actions suggérées, par priorité, selon l'état actuel du dépôt.

/gitflow status lists suggested actions, by priority, based on the current repository state.