.gitignore, .gitattributes, fine riga, encoding

Un repository non deve contenere tutto ciò che appare nella cartella del progetto. Deve contenere ciò che serve a ricostruire, capire, testare e distribuire il progetto. Il resto è rumore, rischio o output generato.

.gitignore decide cosa Git deve ignorare. .gitattributes decide come Git deve trattare certi file: fine riga, diff, merge, linguaggio. Sono file piccoli, ma possono evitare giornate perse in diff inutili e conflitti artificiali.

Perché questa lezione conta

Committare file sbagliati crea danni reali:

1. segreti esposti;
2. repo pesante;
3. conflitti su file generati;
4. diff illeggibili;
5. problemi tra Windows, macOS e Linux;
6. build non riproducibili.

Un buon ignore non è una lista enorme copiata senza capire. È una scelta: quali file sono fonte, quali sono artefatti, quali sono locali, quali sono pericolosi.

Obiettivo operativo

Alla fine della lezione devi saper scrivere un .gitignore minimale per il tuo stack, capire perché un file già tracciato non viene ignorato e usare .gitattributes per normalizzare line ending e migliorare diff.

.gitignore

Esempio per progetto web:

# dipendenze installate
node_modules/

# build output
dist/
.astro/

# ambiente locale
.env
.env.*
!.env.example

# log e cache
*.log
.DS_Store

La riga !.env.example è una negazione: ignora .env, ma traccia un esempio senza segreti. È una pratica utile perché il team sa quali variabili servono senza esporre valori reali.

File già tracciati

.gitignore non rimuove file già entrati nel repository. Se hai committato dist/, aggiungere dist/ a .gitignore non basta.

Serve:

git rm -r --cached dist/
git commit -m "Rimuovi dist dal repository"

--cached rimuove dall’index e dalla storia futura, non dal disco. Il file resta locale, ma Git smette di tracciarlo.

Pattern utili

*.log           # tutti i log
logs/           # cartella logs
/dist/          # dist solo alla radice
temp*           # file/cartelle che iniziano per temp
!keep.log       # eccezione

Attenzione alle negazioni: per ri-includere un file dentro una cartella ignorata, può essere necessario ri-includere anche la cartella.

.gitattributes

Esempio semplice:

* text=auto
*.sh text eol=lf
*.bat text eol=crlf
*.png binary
*.jpg binary
package-lock.json merge=ours

text=auto chiede a Git di gestire file testuali in modo coerente. eol=lf impone LF per script shell, evitando problemi su Linux. I file binari vengono marcati come binari, così Git non prova a mostrare diff testuali inutili.

La regola merge=ours va usata con molta cautela: può nascondere conflitti reali. È utile solo per file rigenerabili dove la scelta è deliberata e documentata.

Fine riga

Il problema CRLF/LF appare spesso in team misti Windows/macOS/Linux. Senza regole, un file può risultare modificato anche se nessuno ha cambiato contenuto logico.

Configurazione consigliata nel repo:

* text=auto
*.js text eol=lf
*.ts text eol=lf
*.css text eol=lf
*.md text eol=lf

Meglio definire la policy nel repo che affidarsi alle configurazioni personali di ogni sviluppatore.

Segreti

.gitignore riduce il rischio, ma non è sicurezza completa. Se un segreto entra in un commit, consideralo compromesso. Anche se poi lo rimuovi, resta nella storia finché non la riscrivi e comunque potrebbe essere già stato copiato.

Regola pratica:

1. .env ignorato;
2. .env.example tracciato;
3. scanner segreti in pre-commit o CI;
4. rotazione immediata se un segreto viene committato.

Laboratorio guidato

Prendi un progetto reale. Esegui:

git status --ignored

Poi classifica i file non tracciati:

1. sorgente da committare;
2. generato da ignorare;
3. locale da ignorare;
4. sensibile da escludere e proteggere;
5. dubbio da discutere nel README.

Scrivi o correggi .gitignore e aggiungi .gitattributes minimale.

Output atteso

Un commit con:

1. .gitignore motivato;
2. .gitattributes per line ending;
3. eventuale .env.example;
4. rimozione da index dei file generati già tracciati.

Errori comuni

Copiare template enormi. Un ignore troppo grande può nascondere file che invece andrebbero versionati.

Ignorare dopo aver tracciato. Serve git rm --cached, non solo .gitignore.

Committare segreti e poi cancellarli. La cancellazione nel commit successivo non elimina il problema.

Non gestire fine riga nel repo. La coerenza deve viaggiare con il progetto.

Checklist di verifica

• so perché ogni voce del mio .gitignore esiste;
• .env è ignorato e .env.example è tracciato;
• so rimuovere dall’index un file già tracciato;
• .gitattributes gestisce almeno testo e binari principali;
• il repo non contiene artefatti generati inutili.

Collegamenti

• Modulo: Fondamenti e modello mentale — lezione 5 del corso.
• Nel modulo 2 userai questi file per evitare commit sporchi e diff rumorosi.