Come installare Git LFS su WSL2 in Windows 11 e 10

Git LFS su WSL2: il punto non è “installarlo”, ma farlo lavorare nel filesystem giusto

Su WSL2 la parte che crea più confusione non è Git LFS in sé, ma il contesto in cui lo fai girare. Se il repository sta dentro il filesystem Linux della distro, l’installazione è lineare. Se invece lavori dentro /mnt/c o in una cartella condivisa con Windows, entrano in gioco prestazioni, permessi, line ending e in alcuni casi anche comportamenti diversi del filtro LFS. La regola pratica è semplice: installa Git LFS dentro la distro WSL2, usa il clone nel filesystem Linux quando puoi, e verifica subito che il filtro sia attivo prima di caricare file grossi in un progetto reale.

Questo vale sia su Windows 11 sia su Windows 10: la differenza vera la fa la distribuzione Linux usata in WSL2, non il Windows host. In genere le distro più comuni sono Ubuntu, Debian e openSUSE, ma il flusso è identico: aggiorni i pacchetti, installi git-lfs, abiliti l’integrazione con Git, poi fai un test con un file tracciato da LFS. Se salti la verifica iniziale, ti accorgi del problema troppo tardi, magari dopo aver pushato un oggetto pesante come un binario, un dump o un asset multimediale.

Prerequisiti sensati su WSL2

Prima di toccare Git LFS, controlla di essere davvero su WSL2 e non su WSL1. WSL2 usa un kernel Linux reale e ha un comportamento più coerente con gli strumenti di sviluppo. Verifica la versione dalla shell di Windows:

wsl -l -v

Nel risultato cerca la colonna VERSION: deve essere 2 per la distro che userai. Se non lo è, la migrazione si fa da PowerShell con un comando non distruttivo per i dati, ma con impatto sul comportamento della distro:

wsl --set-version <NomeDistro> 2

Se lavori in azienda o su una macchina condivisa, conviene anche sapere quale Git userai. Su WSL puoi usare il Git della distro Linux, che è la scelta più pulita per Git LFS, oppure un Git installato lato Windows richiamato da WSL. La seconda opzione funziona in diversi casi, ma introduce attriti inutili. Qui conviene tenere tutto lato Linux, così il filtro LFS, i path e gli hook restano nello stesso ambiente.

Installazione su Ubuntu, Debian e derivate

Su una distro basata su Debian il pacchetto è normalmente disponibile nei repository standard o in quelli della distribuzione stessa. Il flusso base è questo:

sudo apt update
sudo apt install git git-lfs

Dopo l’installazione, Git LFS va inizializzato per l’utente corrente. Questo passaggio crea l’integrazione con Git e prepara i filtri necessari:

git lfs install

Il comando scrive i riferimenti necessari nella configurazione utente di Git, di solito in ~/.gitconfig. Non serve fare hacking manuale a meno che tu non stia gestendo policy centralizzate o ambienti molto controllati. Se vuoi verificare cosa è stato registrato, usa:

git config --global --list | grep lfs

Un output tipico mostra qualcosa di simile a filter.lfs.process, filter.lfs.smudge e filter.lfs.clean. Se non compare nulla, il problema è quasi sempre uno tra: installazione incompleta, git-lfs assente nel PATH, oppure stai usando un Git diverso da quello che pensi.

Installazione su Fedora, RHEL, CentOS Stream e derivate

Su sistemi basati su RPM il nome del pacchetto e il repository possono cambiare, ma la logica resta la stessa. In molti casi basta:

sudo dnf install git git-lfs
# oppure
sudo yum install git git-lfs

Anche qui il passaggio successivo è l’inizializzazione. Non assumere che l’installazione del pacchetto basti da sola:

git lfs install

Se il pacchetto non si trova nei repository base, il problema non è Git LFS ma la policy dei repository della distro o della tua immagine WSL. In quel caso devi prima capire quale release stai usando con:

cat /etc/os-release

Da lì decidi se abilitare un repository aggiuntivo o se usare il pacchetto distribuito dal vendor della distro. Evita installazioni manuali sparse in /usr/local se non hai una ragione precisa: su WSL, come su Linux normale, la manutenzione futura conta più della scorciatoia iniziale.

Installazione rapida da repository GitHub: quando ha senso e quando no

Molti cercano direttamente una release binaria di Git LFS. È un’opzione utile se il pacchetto della distro è vecchio o mancante, ma non è la prima scelta su WSL2. Il motivo è banale: aggiungi un canale di aggiornamento extra da mantenere, e in un ambiente che già vive a metà tra Windows e Linux non è il caso di moltiplicare le fonti senza motivo.

Se proprio devi farlo, la verifica minima è controllare che il binario risponda e che la versione sia coerente con quella attesa dal tuo stack Git:

git lfs version

Se il comando risponde con una versione valida, il livello base è a posto. Se invece ottieni command not found, il problema è di PATH o di installazione. Se ottieni una versione ma Git non vede i filtri, allora il problema è più in alto: Git e Git LFS non stanno usando la stessa configurazione utente o hai più installazioni sovrapposte.

Verifica che Git LFS sia davvero attivo

L’errore più comune è dare per scontato che git lfs install basti. In realtà il controllo giusto è doppio: prima verifichi la presenza del supporto, poi testi un file tracciato da LFS. Il primo controllo è questo:

git lfs env

Tra le righe in output cerca i filtri e i percorsi della configurazione. Se il comando gira ma non mostra parametri utili, stai probabilmente interrogando un’installazione incompleta o un ambiente Git non coerente con la tua sessione WSL.

Il secondo controllo è operativo. Nel repository prova a tracciare un’estensione tipica, per esempio file binari o immagini di grandi dimensioni:

git lfs track "*.psd"
git add .gitattributes
cat .gitattributes

Nel file .gitattributes deve comparire la regola LFS corrispondente. Questo file è il punto di verità: se non viene versionato, gli altri collaboratori non sapranno che quel pattern va gestito da LFS. In pratica, l’installazione locale è solo metà del lavoro; l’altra metà è rendere esplicita la policy nel repository.

Come evitare il classico errore di lavorare in /mnt/c

Su WSL2 puoi accedere ai dischi Windows tramite /mnt/c, ma per un repository con Git LFS non è la scelta migliore se vuoi stabilità e prestazioni. Il motivo è che il filesystem montato introduce overhead e a volte differenze nel comportamento di permessi, lock e watch di file. Con LFS, quando i file iniziano a crescere, questi dettagli si sentono subito.

La soluzione pratica è mantenere il repository nel filesystem Linux della distro, ad esempio in /home/utente/progetto. Se devi comunque lavorare su file condivisi con Windows, separa chiaramente il codice sorgente dai dati pesanti. Un pattern utile è questo: repository in Linux, asset di scambio in una cartella Windows solo quando serve, non il contrario.

Se vuoi verificare dove si trova davvero il repository, usa:

pwd
git rev-parse --show-toplevel

Se i path puntano sotto /mnt/c, non hai un problema di Git LFS ma di layout del progetto. Spostare il clone nel filesystem Linux è spesso la correzione più pulita e reversibile.

Configurazione utile per team e repository già esistenti

Se il repository esiste già e vuoi introdurre Git LFS senza rompere la storia, devi distinguere tra nuovi file e file già versionati. LFS gestisce bene i nuovi oggetti, ma migrare materiale già committato richiede più attenzione. Per il caso normale, basta dichiarare i pattern e committare .gitattributes. Per esempio:

git lfs track "*.zip"
git lfs track "*.mp4"
git add .gitattributes
git commit -m "Track large assets with Git LFS"

Se devi spostare file già presenti nella storia verso LFS, il tema cambia: serve una migrazione controllata, con comunicazione al team e, spesso, un piano di riscrittura della storia del repository. Qui non basta un comando veloce perché il blast radius include clone locali, fork e CI. In altre parole: non fare una migrazione storica se non hai validato il rischio e concordato il rollback.

Un controllo rapido per capire se un file è gestito da LFS è guardare il contenuto nel repository o interrogare Git:

git lfs ls-files

Se il file compare in elenco, è sotto controllo LFS. Se non compare, o il pattern non è stato tracciato, o stai guardando una copia non aggiornata del repository.

Integrazione con Git su WSL2 e Windows: cosa conviene davvero

Una domanda ricorrente è se convenga usare Git installato su Windows oppure dentro WSL2. Per Git LFS la risposta operativa è quasi sempre: dentro WSL2. Così eviti di mescolare toolchain diverse e riduci i casi in cui un comando lanciato dalla shell Linux usa in realtà componenti Windows, con effetti poco prevedibili sui path e sui permessi.

Se però il tuo flusso di lavoro passa anche da editor Windows, tieni separati i livelli: editing da Windows, esecuzione dei comandi Git da WSL2. È una distinzione semplice che evita molti problemi. Un esempio concreto: VS Code può aprire una cartella WSL e usare il terminale integrato della distro; in quel caso il repository resta nel mondo Linux anche se l’interfaccia gira su Windows.

Se vuoi controllare quale Git stai usando, la verifica più diretta è questa:

which git
git --version
which git-lfs
git lfs version

Se i percorsi non stanno sotto la distro WSL, hai un mix di ambienti che prima o poi presenterà il conto. Meglio correggerlo subito che inseguire bug intermittenti.

Troubleshooting essenziale quando Git LFS non funziona

Quando qualcosa non torna, conviene ragionare per sintomi. Se git lfs non esiste, il problema è installazione o PATH. Se esiste ma i file non vengono convertiti, il problema è il filtro Git. Se il push fallisce, il problema può essere il server remoto, i limiti del provider o la configurazione del repository remoto.

Le verifiche minime da fare sono queste:

git lfs version
git lfs env
git status
git lfs ls-files

Se il problema è sul push, spesso trovi indizi nel messaggio di errore del remote. Alcuni server Git richiedono che LFS sia abilitato sul progetto o sul piano dell’account. Altri pongono limiti di quota o dimensione. In quel caso la correzione non è locale: devi agire sul servizio remoto o cambiare strategia di archiviazione dei file grandi.

Se invece la shell dice che i file sono tracciati ma il checkout non scarica gli oggetti, prova un fetch esplicito:

git lfs pull

Questo comando è utile quando vuoi distinguere tra problema di clone iniziale e problema di sincronizzazione successiva. Se git lfs pull fallisce con autenticazione o autorizzazione, il problema è quasi certamente nel remote o nelle credenziali, non nel client WSL2.

Una sequenza pulita da usare su una nuova macchina Windows 11 o 10

Se vuoi un percorso lineare e ripetibile, questa è la sequenza che uso di solito su WSL2:

1. Verifica che la distro sia in WSL2 con wsl -l -v.
2. Apri la shell della distro Linux.
3. Aggiorna i pacchetti con il gestore della distro.
4. Installa git e git-lfs.
5. Esegui git lfs install.
6. Controlla git lfs version e git lfs env.
7. Traccia un pattern con git lfs track e verifica .gitattributes.
8. Clona o sposta il repository nel filesystem Linux, non in /mnt/c.
9. Testa un file reale con git lfs ls-files e un push verso il remote.

Questa sequenza riduce i casi in cui la configurazione sembra funzionare ma poi fallisce al primo file grande. È un classico problema da ambiente ibrido: tutto sembra “quasi giusto”, finché non arriva il primo oggetto pesante o il primo team member con un setup diverso.

Dettaglio pratico: file di configurazione e punti da controllare

Se vuoi capire dove Git LFS ha scritto la configurazione, il riferimento principale è ~/.gitconfig. In genere non serve modificarlo a mano, ma è utile sapere dove guardare quando il comportamento non coincide con l’atteso. Cerca sezioni tipo:

[filter "lfs"]
	clean = git-lfs clean -- %f
	smudge = git-lfs smudge -- %f
	process = git-lfs filter-process

Se questa sezione non c’è, git lfs install non ha avuto effetto sull’utente corrente oppure stai leggendo il file sbagliato. Se c’è ma Git continua a ignorarla, allora il problema può essere una configurazione locale del repository, una variabile d’ambiente o un wrapper che altera il PATH.

Un controllo aggiuntivo utile è vedere se il repository ha estensioni o impostazioni particolari:

git config --local --list

Se il repository è stato preparato da altri, questa vista locale spesso rivela più della configurazione globale. È anche il modo più rapido per capire se LFS è stato configurato per il progetto ma non per la tua sessione WSL.

Conclusione operativa: la regola che evita metà dei problemi

Su WSL2 Git LFS si installa in pochi minuti, ma il punto vero è usare un ambiente coerente dall’inizio alla fine. Installa il pacchetto nella distro Linux, inizializza LFS, verifica i filtri, traccia i pattern nel repository e lavora nel filesystem Linux. Se fai così, Windows 11 e Windows 10 diventano solo il contenitore host, non una variabile che complica il flusso Git.

Il test finale non è “il comando non dà errori”, ma “un file grande viene tracciato, versionato e recuperato correttamente da un clone pulito”. Se questo funziona, la configurazione è solida. Se non funziona, non insistere con tentativi casuali: torna a verificare ambiente, path, remote e .gitattributes, perché lì di solito si nasconde il problema reale.