.gitignore

Panoramica

In una copia di lavoro, Git vede ogni file in uno dei tre stati: tracciato (già nel repository o nell'area di staging), non tracciato (nuovo e non ancora nell'area di staging), oppure ignorato (escluso deliberatamente). Questo capitolo spiega come far ignorare a Git determinati file tramite un file .gitignore: la sintassi dei pattern, dove possono risiedere le regole di ignore (per directory, per repository e globali), e come gestire i casi più complessi — ignorare un file già committato, forzare il commit di un file ignorato, fare lo stash di file ignorati e fare il debug del motivo per cui un file viene ignorato.

I file ignorati sono quelli che hai detto esplicitamente a Git di saltare. Non vengono mai aggiunti all'area di staging, mai committati, e non appaiono mai in git status come rumore non tracciato. I candidati tipici sono file generati dal sorgente piuttosto che scritti a mano:

• File creati in fase di esecuzione — log, file di lock (*.log, *.lock).
• Metadati del sistema operativo e dell'IDE — .DS_Store, Thumbs.db, .idea/, .vscode/.
• Output compilato e dipendenze — *.o, *.class, node_modules/, dist/.
• Segreti e configurazioni locali — .env, file di credenziali.

La regola empirica: se un file può essere rigenerato dal sorgente del repository, oppure è specifico della tua macchina, ignoralo.

Pattern di Git ignore

Le regole di ignore risiedono in un file di testo normale chiamato .gitignore. Non esiste un comando git ignore — il file viene creato e modificato a mano e committato come qualsiasi altro file. Ogni riga non vuota è un pattern confrontato con i percorsi dei file; un file viene ignorato quando corrisponde a un pattern.

Alcune regole si applicano al formato del file stesso:

• Una riga vuota non corrisponde a nulla e viene usata solo per leggibilità.
• Una riga che inizia con # è un commento. Per trovare un nome di file che inizia letteralmente con #, si usa il carattere di escape \#.
• Gli spazi finali vengono ignorati a meno che non siano preceduti da una barra rovesciata (\).
• I pattern sono confrontati in modo relativo alla posizione del file .gitignore.

I pattern stessi sono costruiti con questi simboli:

Ecco un piccolo .gitignore che mostra come si comporta debug?.log (il ? corrisponde esattamente a un carattere). Ignora debug0.log e debug1.log, ma non debug10.log, perché 10 è composto da due caratteri:

.gitignore patterns

debug?.log

# matches debug0.log, debug1.log, debug9.log
# does NOT match debug10.log (two characters)

File .gitignore condivisi nel repository

È possibile definire diversi file .gitignore in directory diverse all'interno del repository. Ogni pattern viene testato in modo relativo alla directory che contiene quel file. Tuttavia, il modo più semplice è definire un unico file .gitignore nella root del repository.

Poiché il file .gitignore viene tracciato nel repository, è versionato come gli altri file e viene condiviso con il team quando si effettua il push. Nel file .gitignore dovresti includere solo pattern utili agli altri utenti del repository.

Regole personali per Git ignore

I pattern di ignore personali per un singolo repository possono essere inseriti nel file speciale .git/info/exclude. La sua sintassi è identica a quella di .gitignore, ma poiché la directory .git non fa parte del contenuto del repository, queste regole non sono versionate e non vengono condivise quando si effettua il push o il clone. Usa questo file per backup dell'editor, file temporanei o qualsiasi cosa specifica del tuo flusso di lavoro che non dovrebbe essere imposta al resto del team.

Regole globali di Git ignore

È possibile definire la proprietà Git core.excludesFile per specificare pattern di ignore globali per tutti i repository nel sistema locale. Questo file deve essere creato manualmente. Puoi posizionare il file .gitignore globale nella tua directory home per trovarlo facilmente. Una volta creato il file, configura la sua posizione con il comando git config, in questo modo:

global gitignore rules

touch ~/.gitignore
git config --global core.excludesFile ~/.gitignore

Ignorare un file già committato

Aggiungere un pattern a .gitignore non impedisce a Git di tracciare un file già committato — le regole di ignore si applicano solo ai file non tracciati. Per iniziare a ignorare un tale file devi prima rimuoverlo dall'indice di Git. Usa git rm con l'opzione --cached: questo mette in staging la rimozione del file dal repository mantenendo intatta la copia sul disco come file ignorato. Poi committa la modifica.

.gitignore committed files

echo debug.log >> .gitignore
git rm --cached debug.log
#rm 'debug.log'
git commit -m "Start ignoring debug.log"

Se vuoi anche eliminare il file dalla tua directory di lavoro, ometti --cached (git rm debug.log). Usa git status successivamente per confermare che il file non appare più come tracciato o non tracciato.

Committare un file ignorato

Il file ignorato può essere committato nel repository combinando l'opzione -f (o --force) con git add. Tuttavia, scegli questo approccio quando hai un pattern generale, come *.log, ma vuoi committare un file specifico:

commiting ignored files

cat .gitignore
# *.log
git add -f debug.log
git commit -m "Force adding debug.log"

In caso contrario, il modo più semplice è impostare un'eccezione alla regola generale:

commit ignored files

echo '!debug.log' >> .gitignore

cat .gitignore
#*.log
#!debug.log

git add debug.log
git commit -m "Adding debug.log"

Fare lo stash di un file ignorato

Il comando git stash prende le modifiche non committate nell'area di staging e quelle non ancora in staging, le salva per dopo e riporta la copia di lavoro a uno stato pulito. Per impostazione predefinita effettua lo stash solo delle modifiche ai file tracciati — i file ignorati e non tracciati vengono lasciati al loro posto. Due opzioni ampliano questo ambito:

• git stash --include-untracked (o -u) include nello stash anche i file non tracciati.
• git stash --all (o -a) include nello stash sia i file non tracciati che quelli ignorati.

git stash --all

Debug dei file .gitignore

Con pattern complessi, o regole distribuite su più file .gitignore, può essere difficile capire quale regola sta nascondendo un file. Il comando git check-ignore con -v (o --verbose) riporta l'esatto pattern responsabile:

git check ignored files

git check-ignore -v debug.log
#.gitignore:3:*.log    debug.log

L'output ha quattro campi separati da due punti (e uno spazio prima del nome del file):

<file containing the pattern>:<line number of the pattern>:<pattern>    <file name>

Quindi .gitignore:3:*.log debug.log significa: la regola *.log alla riga 3 di .gitignore è ciò che causa l'ignore di debug.log. Se il comando non stampa nulla, il file non è ignorato da nessuna regola.

Capitoli correlati

• git rm — rimuovi file dal tracciamento, fondamentale per ignorare un file già committato.
• git add — aggiungi file all'area di staging, inclusa -f per forzare l'aggiunta di un file ignorato.
• git stash — salva le modifiche da parte; combinalo con --all per includere i file ignorati.
• git config — imposta core.excludesFile per un elenco di ignore globale.
• git clean — elimina i file non tracciati; abbinalo a -x per rimuovere anche quelli ignorati.

Pratica