File .gitignore: cosa escludere e come si scrive

Il .gitignore è uno di quei file che si copia da qualche parte all'inizio del progetto e non si guarda più. Peccato che sia l'unica cosa che separa un repository pulito da uno con dentro trecento megabyte di dipendenze, le impostazioni personali dell'editor e — nei casi peggiori — le credenziali di produzione. In questo articolo trovi come si scrive e cosa metterci.

Cosa fa

Il .gitignore è un file di testo che elenca i percorsi che Git deve ignorare: file e cartelle che non verranno tracciati né proposti per il commit.

Va posizionato nella radice del progetto e va versionato insieme al codice, perché serve a tutto il team.

Un punto fondamentale, che spiega metà dei problemi che si incontrano: il .gitignore funziona solo sui file non ancora tracciati. Se un file è già nel repository, aggiungerlo alle esclusioni non lo rimuove — Git continuerà a seguirne le modifiche. Ci torno più avanti, perché è la domanda più frequente.

La sintassi

Poche regole, e coprono tutto:

# Un commento

node_modules/          # una cartella (la barra finale la specifica)
*.log                  # tutti i file con questa estensione
build                  # file o cartella con questo nome, ovunque
/dist                  # solo nella radice del progetto
temp/*.txt             # i .txt dentro temp, non nelle sottocartelle
**/cache               # cartelle "cache" a qualsiasi profondità

!importante.log        # eccezione: NON ignorare questo

Gli elementi da conoscere:

• / finale → è una cartella
• / iniziale → solo a partire dalla radice, non ovunque
• * → qualsiasi sequenza, escluse le barre
• ** → attraversa le sottocartelle
• ! → riporta dentro qualcosa escluso da una regola precedente
• # → commento

Attenzione a un dettaglio sulle eccezioni: se hai escluso una cartella, non puoi riportare dentro un file al suo interno. Git non entra nemmeno nella cartella per guardare. Va escluso il contenuto, non la cartella:

config/*
!config/esempio.json

Cosa escludere sempre

Quattro categorie, in ordine di importanza.

1. I segreti

.env
.env.local
*.pem
*.key
credentials.json

È la categoria che conta più di tutte le altre messe insieme. Chiavi API, password, certificati, stringhe di connessione.

E vale la pena ripeterlo perché è il danno più grave che si possa fare: rimuovere un segreto in un commit successivo non lo cancella dalla storia. Resta leggibile da chiunque abbia accesso al repository. Se succede, l'unica azione che conta è revocare e rigenerare quella credenziale, non ripulire i file.

La pratica corretta è versionare un file di esempio senza valori reali:

.env
!.env.example

2. Le dipendenze installate

node_modules/
vendor/
.venv/
__pycache__/

Si reinstallano dall'elenco delle dipendenze, che invece va versionato insieme al file di blocco delle versioni. Metterle nel repository lo appesantisce enormemente senza alcun beneficio.

3. I file generati

dist/
build/
.next/
*.min.js
coverage/

Tutto ciò che si può rigenerare dal codice sorgente. Se è un risultato, non è una fonte.

4. I file di sistema e dell'editor

.DS_Store
Thumbs.db
.idea/
*.swp

Su questi vale una nota: le impostazioni personali del proprio editor non riguardano gli altri, e conviene escluderle globalmente invece che in ogni progetto:

git config --global core.excludesfile ~/.gitignore_global

Così non devi ricordartene ogni volta, e non imponi le tue preferenze ai repository altrui.

Piccola eccezione: alcune configurazioni dell'editor condivise — formattazione, estensioni consigliate — ha senso versionarle, perché uniformano il lavoro del team.

Cosa NON escludere

Errori che si vedono spesso:

I file di blocco delle dipendenze (package-lock.json, yarn.lock, poetry.lock). Vanno versionati: sono ciò che garantisce che tutti installino le stesse identiche versioni. Escluderli reintroduce il "sul mio computer funziona".

I file di configurazione del progetto — quelli condivisi, non i tuoi personali.

Le migrazioni del database. Fanno parte della storia del progetto.

Le cartelle vuote. Git non le traccia comunque: se ne serve una, si mette dentro un file segnaposto.

Il file è già nel repository: come rimediare

La situazione più frequente, e la soluzione non è ovvia.

Per un singolo file:

git rm --cached file.env

Il --cached è la parte importante: toglie il file dal tracciamento ma lo lascia sul tuo disco. Senza, lo cancelleresti davvero.

Per una cartella:

git rm -r --cached node_modules/

Per riapplicare le esclusioni a tutto il progetto:

git rm -r --cached .
git add .
git commit -m "applica le regole di gitignore"

Poi si commetta normalmente. Da quel momento il file smette di essere seguito.

Attenzione a due cose: questo lo rimuove dal presente, non dalla storia — se era un segreto, va comunque revocato. E su un progetto condiviso, avvisa il team prima — soprattutto chi ha rami di lavoro aperti: alla loro prossima sincronizzazione quei file spariranno dal loro repository (ma non dal disco).

Come partire bene

Non scrivere il .gitignore da zero. Esistono raccolte ufficiali di modelli per ogni linguaggio e ambiente: GitHub ne offre uno alla creazione del repository, e ci sono servizi che generano il file combinando linguaggio, sistema operativo ed editor.

Partire da un modello e togliere ciò che non serve è più veloce e molto meno soggetto a dimenticanze.

Verifica cosa stai per committare:

git status --ignored     # mostra anche ciò che viene ignorato
git check-ignore -v file # dice QUALE regola esclude un file

Il secondo comando è utilissimo quando un file "sparisce" e non capisci perché.

E l'abitudine che risolve tutto a monte: git diff --staged prima di ogni commit. Ti mostra esattamente cosa stai per salvare — vedi comandi Git essenziali.

In sintesi

Il .gitignore elenca ciò che Git deve ignorare, va nella radice del progetto e va versionato, perché serve a tutto il team.

Funziona solo sui file non ancora tracciati: se qualcosa è già nel repository, serve git rm --cached per smettere di seguirlo.

Le quattro categorie da escludere sempre: segreti (la più importante), dipendenze installate, file generati, file di sistema ed editor. Con l'accortezza di escludere le preferenze personali globalmente, non progetto per progetto.

E le cose che invece vanno versionate: i file di blocco delle dipendenze, le configurazioni condivise, le migrazioni.

La regola che vale più di tutte: se ci finisce un segreto, revocalo. Toglierlo dai file non lo toglie dalla storia — e il ragionamento completo su questo è in cos'è il version control.