Tutorial GitFlow: branching per feature, release e hotfix

Configurare GitFlow

Prima di sfruttare il modello di branching strutturato di GitFlow, devi configurarlo sulla tua macchina e inizializzarlo nel repository. Per fortuna, entrambi i passaggi sono semplici.

Per usare GitFlow, devi avere Git già installato sulla tua macchina. Puoi leggere di più sull’installazione di Git nel Git Install Tutorial.

Installare GitFlow

GitFlow è un’estensione di Git, quindi devi installarla separatamente. Di default non è inclusa in Git. Il processo di installazione dipende dal sistema operativo.

Per istruzioni più dettagliate su come installare GitFlow, leggi la documentazione ufficiale.

Nota: anche se l’estensione GitFlow qui sopra semplifica la gestione di feature, release e hotfix con comandi semplici, non è strettamente necessaria. Puoi seguire il workflow GitFlow utilizzando i normali comandi Git—purché tu sia coerente con convenzioni di naming e pratiche di merge. Lo strumento automatizza e fa rispettare il processo, utile per team o progetti più grandi.

macOS

Se usi Homebrew, il gestore di pacchetti più popolare per macOS, esegui:

brew install git-flow-avh

Linux (basato su Debian/Ubuntu)

Se usi un sistema basato su Debian come Ubuntu, usa:

sudo apt-get install git-flow

Windows

Se usi Windows, puoi installare GitFlow tramite Git for Windows e aggiungere Git Bash al tuo terminale.

Per verificare se GitFlow è installato, puoi eseguire:

git flow version

Inizializzare GitFlow in un repository

Come primo passo, devi avere un repository Git inizializzato prima di usare GitFlow. Puoi leggere di più in How to Initialize and Set Up a Git Repository.

Una volta installato GitFlow, puoi inizializzarlo in qualsiasi repository Git esistente con:

git flow init

GitFlow ti chiederà di configurare diverse impostazioni. Ecco cosa significano e come scegliere quelle giuste:

1. Nomi dei branch: ti verranno chiesti i nomi di default dei branch.
1. Nome del branch di produzione (default: master)
2. Nome del branch di sviluppo (default develop)
2. Prefissi per i branch di supporto: GitFlow usa convenzioni di naming per i vari tipi di branch.
1. Feature branch: feature/
2. Bugfix branch: bugfix/
3. Release branch: release/
4. Hotfix branch: hotfix/
5. Support branch: support/ (raramente usato nella pratica)
6. Prefisso dei tag di versione: v (es. v.1.2.0)

I valori predefiniti vanno bene per la maggior parte dei team, ma puoi personalizzarli per adattarli agli standard di naming della tua organizzazione.

Esempio di output dell’inizializzazione:

git flow init

Which branch should be used for bringing forth production releases?
   - master
Branch name for production releases: [master]
Branch name for "next release" development: [develop]

How to name your supporting branch prefixes?
Feature branches? [feature/]
Bugfix branches? [bugfix/]
Release branches? [release/]
Hotfix branches? [hotfix/]
Support branches? [support/]
Version tag prefix? [] v

Dopo averlo inizializzato, puoi pushare il branch develop sul tuo repository remoto. Puoi leggere di più su push e pull dei branch nel Git Push and Pull Tutorial.

Usare GitFlow per lo sviluppo

Una volta inizializzato GitFlow nel tuo repository, puoi iniziare a usare il suo modello di branching per gestire il tuo workflow di sviluppo. GitFlow fornisce comandi di alto livello per lavorare con feature, release e hotfix, rendendo più facile mantenere la struttura ed evitare il caos su Git.

Nei prossimi sottocapitoli, vedremo GitFlow in pratica.

Creare feature branch

I feature branch servono a sviluppare nuova funzionalità senza influenzare il codebase principale.

Puoi creare un feature branch eseguendo:

git flow feature start <feature-name>

Questo comando crea un nuovo branch da develop chiamato feature/<feature-name>. Puoi iniziare a sviluppare la tua feature e fare commit delle modifiche come al solito.

Concludere i feature branch

Quando la tua feature è completa e testata, puoi concluderla con: 

git flow feature finish <feature-name>

Questo fa quanto segue:

• Fa il merge del tuo feature branch nel branch develop.
• Elimina il branch locale feature/<feature-name>.

Se incontri conflitti di merge, risolvili manualmente e completa il merge usando il flusso standard di risoluzione conflitti di Git.

Se lavori in team più grandi dove è necessario creare e revisionare prima delle pull request, non puoi usare direttamente il comando di finish di GitFlow, ma puoi invece fare così:

1. Fai commit del tuo lavoro, poi pusha il branch:

git push origin feature/<feature-name>

2. Crea una pull request da feature/<feature-name> verso develop su GitHub, GitLab, ecc.
3. Richiedi la review, esegui i test e ottieni le approvazioni.
4. Una volta approvata, fai il merge tramite l’interfaccia della piattaforma ed elimina il branch.

Se vuoi saperne di più su GitHub e su come usarlo, consiglio i corsi GitHub Foundations e GitHub Concepts. In altri team, potresti seguire il flusso standard git flow feature finish, ma dovrai chiedere una review del tuo branch prima di reintegrarlo in develop ed eseguire test sulle modifiche al codice per garantirne il corretto comportamento.

Creare release branch

I release branch vengono creati per preparare una nuova versione di produzione senza bloccare lo sviluppo in corso sul branch develop.

Per iniziare una release, esegui:

git flow release start <version-number>

Questo crea un nuovo branch chiamato release/<version-number>. Questo branch è derivato da develop.

In questo branch, in genere finalizzi i numeri di versione, sistemi bug minori e aggiorni documentazione e changelog.

Concludere i release branch

Quando la tua release è pronta per la produzione, concludila con:

git flow release finish <version-number>

Questo comando:

• Fa il merge del branch di release sia in master che in develop.
• Tagga la release in master (es., v1.0.0).
• Elimina il branch locale release/<release-number>.

Non dimenticare di pushare modifiche e tag:

git push origin master
git push origin develop
git push --tags

# oppure in breve
git push origin master develop --tags

Creare hotfix branch

Gli hotfix si usano per fix urgenti in produzione quando viene trovato un bug nel branch master.

Per iniziare un hotfix:

git flow hotfix start <version-number>

Questo crea un branch hotfix/<version-number> da master. Ora puoi applicare le modifiche e fare commit del fix.

Una volta finito, concludilo con:

git flow hotfix finish <version-number>

Questo:

• Fa il merge dell’hotfix in master e develop.
• Tagga il fix su master.
• Elimina il branch locale `hotfix/<version-number>.

Pusha le modifiche locali e i tag come al solito:

git push origin master develop --tags

Gli hotfix sono particolarmente potenti perché ti permettono di correggere rapidamente problemi in produzione senza interferire con lo sviluppo in corso sul branch develop.

Immagina di avere già integrato su develop alcune nuove feature che non vuoi rilasciare ancora, ma c’è un bug urgente e serio nell’applicazione in produzione da sistemare. 

Qui entrano in gioco gli hotfix, perché si diramano da master e poi vengono reintegrati solo in develop.

Esempio di branching con GitFlow

Vediamo due workflow comuni, un ciclo di sviluppo di una feature e una release con un hotfix, per osservare GitFlow in azione e confrontarlo con i comandi Git tradizionali.

Vedendo entrambi i lati, capirai meglio come l’estensione GitFlow semplifica il processo impacchettando più passaggi Git in comandi semplici e standardizzati.

Se ti serve una panoramica rapida dei comandi Git tradizionali, consiglio il Complete Git Cheat Sheet. Se vuoi una panoramica veloce di Git, ti consiglio di leggere GitHub and Git Tutorial for Beginners.

Workflow di sviluppo di una feature

Supponiamo che tu stia implementando una nuova feature che consente agli utenti di autenticarsi alla tua applicazione. Chiami questa feature user-authentication.

Usando GitFlow:

git flow feature start user-authentication

# Lavora sulla feature
git add .
git commit -m "feat: Implement basic user authentication"

# Una volta finito:
git flow feature finish user-authentication

git push origin develop

Ora usando Git normale:

# Crea e passa manualmente a un nuovo branch
git checkout -b feature/user-authentication develop

# Lavora sulla feature
git add .
git commit -m "Implement basic user authentication"

# Una volta finito
git checkout develop
git merge feature/user-authentication
git branch -d feature/user-authentication
git push origin develop

Come vedi, GitFlow riduce il numero di comandi e quindi il livello di complessità. È anche meno incline agli errori, come fare merge nel branch sbagliato per sbaglio.

Per saperne di più su come funziona il merge in Git, leggi Git Merge Tutorial: A Comprehensive Guide with Examples.

Ora supponiamo che tu stia preparando la release 1.0.0. Ma poco dopo aver rilasciato la nuova versione, viene trovato un bug critico che deve essere corretto con un hotfix. 

Usando GitFlow:

# Avvia una release
git flow release start 1.0.0

# Fai gli ultimi ritocchi, aggiorna i numeri di versione
git commit -am "Prepare release v1.0.0"

# Concludi la release
git flow release finish 1.0.0
git push origin master develop --tags

Ora hai trovato il bug e devi creare un hotfix:

# Avvia un hotfix
git flow hotfix start 1.0.1

# Applica il fix
git commit -am "Fix login issue in production"

# Concludi l'hotfix
git flow hotfix finish 1.0.1
git push origin master develop --tags

E rifacendo tutto questo con i comandi Git tradizionali:

# Release manuale
git checkout -b release/1.0.0 develop

# Fai le modifiche
git commit -am "Prepare release v1.0.0"

# Merge manuale
git checkout master
git merge release/1.0.0
git tag -a v1.0.0 -m "Release v1.0.0"
git checkout develop
git merge release/1.0.0

# Elimina il branch di release
git branch -d release/1.0.0
git push origin master develop --tags

# Hotfix manuale
git checkout -b hotfix/1.0.1 master

# Applica il fix
git commit -am "Fix login issue in production"
git checkout master
git merge hotfix/1.0.1
git tag -a v1.0.1 -m "Hotfix v1.0.1"
git checkout develop
git merge hotfix/1.0.1

# Elimina il branch di hotfix
git branch -d hotfix/1.0.1
git push origin master develop --tags

Best practice per usare GitFlow

GitFlow è piuttosto potente e ti aiuta a gestire il codice del team. Tuttavia, per ottenere il massimo da questa struttura, dovresti seguire alcune best practice.

Queste pratiche aiutano a mantenere i branch puliti, ridurre i conflitti di merge e migliorare la produttività del team, specialmente in ambienti collaborativi.

Naming coerente dei branch

La coerenza è fondamentale nella collaborazione. Attieniti alle convenzioni di naming predefinite di GitFlow, a meno che il tuo team non abbia una forte motivazione per personalizzarle.

Pattern di naming consigliati:

• Feature branch: feature/<feature-name>
• Release branch: release/<version-number>
• Hotfix branch: hotfix/<version-number>

Usa anche il kebab-case per i nomi composti da più parole (es., feature/user-authentication).

Modifiche piccole e frequenti

I branch di lunga durata spesso portano a merge dolorosi e pull request enormi, difficili da revisionare. 

Parlo per esperienza: sono già passato più volte per l’inferno dei conflitti di merge, ed è meglio evitarlo, se possibile!

Mantieni invece i feature branch di breve durata e concentrati su un singolo task. Fai commit e push regolarmente per evitare di perdere lavoro o allontanarti troppo da develop.

Le modifiche più piccole e incrementali sono più facili da testare, revisionare e integrare.

Allinearsi regolarmente con develop

Quando lavori su un feature branch, non devi rimanere indietro. Assicurati di pullare regolarmente le ultime modifiche dal branch develop per ridurre al minimo i conflitti di merge più avanti:

git checkout feature/<your-feature>
git fetch origin
git rebase origin/develop

Rimanere in sync rende l’integrazione più fluida e mantiene le tue modifiche compatibili con le feature che stanno sviluppando gli altri.

Revisionare e testare prima di fare merge

Anche se GitFlow supporta il merge diretto con comandi come git flow feature finish, è meglio usare pull request (PR) o merge request (MR) per tutti i merge verso develop e master.

Vantaggi:

• Abilita workflow di code review e approvazione
• Attiva controlli CI/CD automatici
• Fornisce una traccia chiara delle modifiche

Questo è particolarmente critico in ambienti di produzione dove il controllo qualità conta.

Risoluzione dei problemi con GitFlow

Anche con un workflow strutturato come GitFlow, possono sorgere problemi, specialmente lavorando in team o su branch di lunga durata. 

Questa sezione copre le sfide più comuni e come risolverle in modo efficace.

Conflitti di merge

I conflitti di merge sono comuni quando si lavora sullo stesso codebase con un team numeroso e sono fastidiosi.In genere si verificano quando due branch hanno modificato le stesse righe di codice.

Passi per risolvere un conflitto di merge:

1. Interrompi il processo git flow finish.
2. Fai manualmente il merge del branch nella sua destinazione:

git checkout develop
git merge feature/<your-feature>

3. Git ti chiederà di risolvere i conflitti. Apri i file in conflitto e cerca marker di conflitto come questi:

<<<<<<< HEAD
Code from develop
=======
Code from feature branch
>>>>>>> feature/my-feature

4. Modifica e pulisci il codice manualmente.
5. Una volta risolti, marca i file come risolti:

git add <resolved-file>

6. Poi completa il merge con:

git commit -m “resolve merge conflict …”

Pulizia dei branch obsoleti

A volte il tuo repository contiene branch feature, release o hotfix superati. Per evitare confusione, mantieni il repository il più pulito possibile.

Puoi risolvere seguendo i passaggi qui sotto:

1. Elenca tutti i branch locali:

git branch

2. Elimina un branch locale:

git branch -d <branch-name>

3. Se il branch non è stato ancora mergiato e sei sicuro che possa essere eliminato:

git branch -D <branch-name>

4. Elimina un branch remoto:

git push origin --delete <branch-name>

È essenziale controllare regolarmente i tuoi branch e pulire quelli obsoleti per mantenere il repository il più pulito possibile.

Conclusione

GitFlow è un framework solido per collaborazione, chiarezza e controllo nel tuo workflow di sviluppo. Che tu stia lavorando a un progetto personale con più persone coinvolte o contribuendo a un team numeroso, GitFlow ti aiuta a rimanere organizzato separando chiaramente sviluppo delle feature, release e hotfix.

Quando ho iniziato a usare GitFlow, è stato una svolta. Niente più caos nei merge. Niente più dubbi su quale branch usare. Ogni lavoro aveva il suo posto e ogni release seguiva un processo ripetibile e affidabile. Col tempo, ho introdotto GitFlow in ogni team con cui ho lavorato. E ogni volta ha portato più struttura, collaborazione più fluida e meno errori.

In questo tutorial hai imparato:

• Che cos’è GitFlow e perché è utile
• Come installare e inizializzare GitFlow
• Come lavorare con feature, release e hotfix
• Best practice per evitare problemi comuni
• Come adattare GitFlow ai workflow moderni usando le pull request

Se vuoi portare il tuo workflow Git al livello successivo, prova a usare GitFlow nel tuo prossimo progetto. E se hai già familiarità con le basi, inizia a valutarne l’integrazione con la pipeline CI/CD del tuo team, il processo di review o anche con le GitHub Actions.