Git LFS

Quando effettui il checkout di un commit che contiene puntatori Git LFS, questi vengono sostituiti con file dalla cache locale di Git LFS o scaricati dall'archivio remoto di Git LFS.

Git LFS è perfetto: nella tua copia di lavoro vedrai solo il contenuto effettivo del tuo file. Ciò significa che puoi usare Git LFS senza modificare il tuo flusso di lavoro Git esistente; devi semplicemente eseguire git checkout, modificare, git add e git commit come di consueto. Le operazioni git clone e git pull saranno molto più veloci in quanto scaricherai solo le versioni di file di grandi dimensioni a cui fanno riferimento i commit di cui effettivamente esegui il checkout, piuttosto che tutte le versioni del file mai esistite.

Per usare Git LFS, avrai bisogno di un host compatibile con Git LFS come Bitbucket Cloud o Bitbucket Data Center. Gli utenti del repository dovranno avere installato il client a riga di comando Git LFS o un client con interfaccia grafica compatibile con Git LFS come Sourcetree. Curiosità: Steve Streeting, lo sviluppatore Atlassian che ha inventato Sourcetree, è anche uno dei principali contributori al progetto Git LFS, quindi Sourcetree e Git LFS lavorano piuttosto bene insieme.

1. Esistono tre semplici modi per installare Git LFS:

a. Installarlo usando il tuo gestore di pacchetti preferito. I pacchetti git-lfs sono disponibili per Homebrew, MacPorts, dnf e packagecloud; oppure

b. Scaricare e installare Git LFS dal sito web del progetto; oppure

c. Installare Sourcetree, un client Git GUI gratuito fornito in bundle con Git LFS.

2. Una volta che git-lfs si trova sul tuo percorso, esegui git lfs install per inizializzare Git LFS (puoi saltare questo passaggio se hai installato Sourcetree):

Dovrai eseguire git lfs install solo una volta. Una volta inizializzato per il tuo sistema, Git LFS si avvierà automaticamente quando cloni un repository contenente contenuti Git LFS.

Per creare un nuovo repository compatibile con Git LFS, dovrai eseguire git lfs install dopo aver creato il repository:

In questo modo installi uno speciale hook Git pre-push nel tuo repository che trasferirà i file Git LFS sul server quando esegui il comando git push.

Git LFS è abilitato automaticamente per tutti i repository Bitbucket Cloud. Per Bitbucket Data Center, dovrai abilitare Git LFS nelle impostazioni del tuo repository:

Una volta che Git LFS è inizializzato per il tuo repository, puoi specificare quali file monitorare usando git lfs track.

Una volta installato Git LFS, puoi clonare un repository Git LFS normalmente usando git clone. Al termine del processo di clonazione, Git controllerà il branch predefinito (di solito main) e tutti i file Git LFS necessari per completare la procedura di checkout verranno scaricati automaticamente per te. Ad esempio:

Ci sono quattro file PNG in questo repository monitorati da Git LFS. Quando si esegue git clone, i file Git LFS vengono scaricati uno alla volta quando i file puntatori vengono estratti dal tuo repository.

Se stai clonando un repository con un gran numero di file LFS, il comando git lfs clone esplicito offre prestazioni molto migliori:

Invece di scaricare i file Git LFS uno alla volta, il comando git lfs clone attende il completamento del checkout, quindi scarica tutti i file Git LFS richiesti come batch. L'operazione sfrutta i download parallelizzati e riduce drasticamente il numero di richieste e processi HTTP generati (il che è particolarmente importante per migliorare le prestazioni su Windows).

Proprio come la clonazione, puoi estrarre da un repository Git LFS usando un normale git pull. Tutti i file Git LFS necessari verranno scaricati come parte del processo di checkout automatico una volta completato l'estrazione:

Non sono necessari comandi espliciti per recuperare contenuti Git LFS. Tuttavia, se il checkout fallisce per un motivo imprevisto, puoi scaricare qualsiasi contenuto Git LFS mancante per il commit corrente con git lfs pull:

Come git lfs clone, git lfs pull scarica i tuoi file Git LFS in batch. Se sai che un gran numero di file è cambiato dall'ultima volta che hai estratto, potresti voler disabilitare il download automatico di Git LFS durante il checkout, quindi scaricare in batch i tuoi contenuti Git LFS con un git lfs pull esplicito. Questo può essere fatto sovrascrivendo la tua configurazione Git con l'opzione -c quando richiami git pull:

Dato che è piuttosto difficile digitare tutto, potresti voler creare un semplice alias Git per eseguire un pull Git e Git LFS in batch per te:

Ciò migliorerà notevolmente le prestazioni quando è necessario scaricare un gran numero di file Git LFS (di nuovo, soprattutto su Windows).

Quando aggiungi un nuovo tipo di file di grandi dimensioni al tuo repository, devi dire a Git LFS di tracciarlo specificando uno schema usando il comando git lfs track:

Nota che le virgolette intorno a "*.ogg" sono importanti. Se le ometti, il carattere jolly verrà espanso dalla tua shell e verranno create singole voci per ogni file.ogg nella tua cartella attuale:

I modelli supportati da Git LFS sono gli stessi di quelli supportati da .gitignore, ad esempio:

Questi schemi sono relativi alla directory in cui hai eseguito il comando git lfs track. Per semplificare le cose, è meglio eseguire git lfs track dalla radice del tuo repository. Nota che Git LFS non supporta modelli negativi, mentre .gitignore sì.

Dopo aver eseguito git lfs track, noterai un nuovo file chiamato .gitattributes nella directory da cui hai eseguito il comando. .gitattributes è un meccanismo Git per associare comportamenti speciali a determinati modelli di file. Git LFS crea o aggiorna automaticamente file .gitattributes per associare i modelli di file tracciati al filtro Git LFS. Tuttavia, dovrai apportare tu stesso qualsiasi modifica ai file .gitattributes nel tuo repository:

Per facilità di manutenzione, è più semplice mantenere tutti i pattern Git LFS in un unico file .gitattributes eseguendo sempre git lfs track dalla radice del tuo repository. Tuttavia, puoi visualizzare un elenco di tutti i pattern attualmente tracciati da Git, LFS (e i file .gitattributes in cui sono definiti) richiamando git lfs track senza argomenti:

Puoi smettere di tracciare un particolare pattern con Git LFS semplicemente rimuovendo la riga appropriata dai tuoi file .gitattributes o eseguendo il comando git lfs untrack:

Dopo aver eseguito git lfs untrack, dovrai nuovamente confermare le modifiche in .gitattributes da te.

Puoi eseguire il commit e il push normalmente verso un repository che contiene contenuti Git LFS. Se hai apportato modifiche ai file tracciati da Git LFS, vedrai un output aggiuntivo da git push man mano che il contenuto di Git LFS viene trasferito sul server:

Se il trasferimento dei file LFS fallisce per qualche motivo, il push verrà interrotto e potrai riprovare senza problemi. Come Git, lo storage Git LFS è indirizzabile ai contenuti: il contenuto è archiviato su una chiave che è un hash SHA-256 del contenuto stesso. Ciò significa che è sempre sicuro riprovare a trasferire file Git LFS sul server; non puoi sovrascrivere accidentalmente il contenuto di un file Git LFS con la versione sbagliata.

Per migrare un repository Git LFS da un provider di hosting a un altro, puoi usare una combinazione di git lfs fetch e git lfs push con --all option specificata.

For example, to move all Git and Git LFS repository from a remote named github to a remote named bitbucket 😉 :

Git LFS in genere scarica solo i file necessari per i commit effettivamente effettuati localmente. Tuttavia, puoi forzare Git LFS a scaricare contenuti extra per altri branch modificati di recente usando git lfs fetch --recent:

Ciò è utile per scaricare in batch nuovi contenuti Git LFS mentre sei fuori a pranzo o se hai intenzione di esaminare il lavoro dei tuoi compagni di squadra e non potrai scaricare contenuti in seguito a causa della connettività Internet limitata. Ad esempio, potresti voler eseguire git lfs fetch --recent prima di imbarcarti su un aereo!

Git LFS considera recente qualsiasi branch o tag contenente un commit più recente di sette giorni. Puoi configurare il numero di giorni considerati recenti impostando la proprietà lfs.fetchrecentrefsdays:

Per impostazione predefinita, git lfs fetch --recent scaricherà i contenuti Git LFS per il commit solo all'inizio di un branch o tag recente.

Tuttavia, puoi configurare Git LFS per scaricare contenuti per i commit precedenti su branch e tag recenti configurando la proprietà lfs.fetchrecentcommitsdays:

Usa questa impostazione con attenzione: se hai branch in rapido movimento, ciò può comportare il download di un'enorme quantità di dati. Tuttavia può essere utile se devi rivedere le modifiche interstiziali in un branch, trovare commit specifici tra branch o riscrivere la cronologia.

Come discusso in Spostamento di un repository Git LFS tra host, puoi anche scegliere di recuperare tutti i contenuti Git LFS per il tuo repository con git lfs fetch --all:

Puoi eliminare file dalla tua cache Git LFS locale con il comando git lfs prune:

Questo eliminerà tutti i file Git LFS locali considerati vecchi. Un file vecchio è qualsiasi file a cui non fanno riferimento:

• la conferma attualmente sottoposta a check-out
• un commit che non è ancora stato inviato (all'origine, o qualsiasi cosa su cui lfs.pruneremotetocheck sia impostato)
• un commit recente

Per impostazione predefinita, un commit recente è qualsiasi commit creato negli ultimi dieci giorni. Questo viene calcolato aggiungendo:

• il valore della proprietà lfs.fetchrecentrefsdays descritta in Recupero della cronologia aggiuntiva di Git LFS (che per impostazione predefinita è sette); a
• il valore della proprietà lfs.pruneoffsetdays (che per impostazione predefinita è tre)

Puoi configurare l'offset prune per conservare i contenuti Git LFS per un periodo più lungo:

A differenza della garbage collection integrata di Git, il contenuto di Git LFS non viene eliminato automaticamente, quindi eseguire git lfs prune su base regolare è una buona idea per ridurre le dimensioni del repository locale.

Puoi testare l'effetto che avrà un'operazione prune con git lfs prune --dry-run:

E scegliere esattamente quali oggetti Git LFS verranno eliminati con git lfs prune --verbose --dry-run:

Le stringhe esadecimali lunghe emesse dalla modalità --verbose sono hash SHA-256 (noti anche come ID oggetto o OID) degli oggetti Git LFS da eliminare. Puoi usare le tecniche descritte in Individuazione di percorsi o commit che fanno riferimento a un oggetto Git LFS per saperne di più sugli oggetti che verranno eliminati.

Come controllo di sicurezza aggiuntivo, puoi usare l'opzione --verify-remote per verificare se il repository remoto Git LFS ha una copia dei tuoi oggetti Git LFS prima che vengano eliminati:

Questo rallenta notevolmente il processo prune, ma ti permette di sapere che tutti gli oggetti saranno recuperabili dal server. Puoi abilitare l'opzione --verify-remote in modo permanente per il tuo sistema configurando la proprietà lfs.pruneverifyremotealways a livello globale:

Oppure puoi abilitare la verifica remota solo per il repository contestuale omettendo l'opzione --global dal comando precedente.

Il client a riga di comando Git LFS non supporta la rimozione di file dal server, quindi il modo in cui li elimini dipende dal tuo provider di hosting.

In Bitbucket Cloud, puoi visualizzare ed eliminare i file Git LFS tramite Impostazioni del repository > Git LFS:

Nota che ogni file Git LFS è indicizzato dal relativo OID SHA-256; i percorsi che fanno riferimento a ciascun file non sono visibili tramite l'interfaccia utente. Questo perché potrebbero esserci molti percorsi diversi in molti commit diversi che possono riferirsi a un determinato oggetto, quindi cercarli sarebbe un processo molto lento.

Per determinare cosa contiene effettivamente un determinato file Git LFS, hai tre opzioni:

• guardare l'immagine di anteprima e il tipo di file nella colonna sinistra dell'interfaccia utente Git LFS di Bitbucket
• scaricare il file utilizzando il link nella colonna destra dell'interfaccia utente Bitbucket Git LFS: cerca i commit che fanno riferimento all'OID SHA-256 dell'oggetto Git LFS, come discusso nella sezione successiva

Se hai un OID SHA-256 Git LFS, puoi determinare a quali commit fa riferimento con git log --all -p -S< OID>:

Questa operazione git log genera una patch (-p) dai commit su qualsiasi branch (--all) che aggiunge o rimuove una riga (-S) contenente la stringa specificata (un OID Git LFS SHA-256).

La patch mostra il commit e il percorso dell'oggetto LFS, nonché chi l'ha aggiunto e quando è stato eseguito. Puoi semplicemente eseguire il checkout del commit e Git LFS scaricherà il file se necessario e lo inserirà nella tua copia di lavoro.

Se sospetti che un particolare oggetto Git LFS sia nel tuo HEAD attuale o in un particolare branch, puoi usare git grep per trovare il percorso del file di riferimento:

Puoi sostituire HEAD o power-up con qualsiasi riferimento, commit o albero che contenga l'oggetto Git LFS.

In alcune situazioni potresti voler scaricare solo un sottoinsieme dei contenuti Git LFS disponibili per un particolare commit. Ad esempio, quando configuri una build CI per eseguire test unitari, potresti aver bisogno solo del tuo codice sorgente, quindi potresti voler escludere i file pesanti che non sono necessari per eseguire la build del codice.

Puoi escludere uno schema o una sottocartella usando git lfs fetch -X (o --exclude):

In alternativa, potresti voler includere solo uno schema o una sottocartella particolare. Ad esempio, un tecnico del suono potrebbe recuperare solo file ogg e wav con git lfs fetch -I (o --include):

Se combini inclusioni ed esclusioni, verranno recuperati solo i file che corrispondono a uno schema di inclusione e non corrispondono a uno schema di esclusione. Ad esempio, puoi recuperare tutto nella tua directory Risorse tranne le gif con:

Esclusioni e inclusioni supportano gli stessi schemi di git lfs track e .gitignore. Puoi rendere permanenti questi schemi per un particolare repository impostando le proprietà di configurazione lfs.fetchinclude e lfs.fetchexclude:

Queste impostazioni possono essere applicate anche a tutti i repository del tuo sistema aggiungendo l'opzione --global.

Sfortunatamente, non esiste un modo semplice per risolvere i conflitti di merge binario. Con il blocco dei file Git LFS, puoi bloccare i file per estensione o per nome e impedire che i file binari vengano sovrascritti durante un merge.

Per sfruttare la funzione di blocco dei file di LFS, devi prima dire a Git quali tipi di file sono bloccabili. Nell'esempio seguente, il flag "--lockable" viene aggiunto al comando "git lfs track" che memorizza entrambi i file PSD in LFS e li contrassegna come bloccabili.

Quindi aggiungi quanto segue al tuo file.gitattributes:

Quando ti prepari ad apportare modifiche a un file LFS, utilizzerai il comando lock per registrare il file come bloccato sul tuo server Git.

Quando non ti serve più il blocco del file, puoi rimuoverlo usando il comando di sblocco di Git LFS.

I blocchi dei file Git LFS possono essere sovrascritti, in modo simile a git push, usando un flag --force. Non utilizzare il flag --force a meno che tu non sia assolutamente sicuro di come procedere.