Git LFS

Po wyewidencjonowaniu zatwierdzenia zawierającego wskaźniki Git LFS są one zastępowane plikami z lokalnej pamięci podręcznej Git LFS lub pobierane ze zdalnego magazynu Git LFS.

Git LFS zapewnia bezproblemową obsługę: w kopii roboczej zobaczysz tylko rzeczywistą zawartość pliku. Oznacza to, że możesz używać Git LFS bez zmiany istniejącego przepływu pracy Git. Po prostu wykonaj polecenie git checkout, zmodyfikuj plik, a następnie użyj poleceń git add i git commit. Operacje git clone i git pull będą znacznie szybsze, ponieważ pobierasz tylko wersje dużych plików, do których odwołują się commity, które faktycznie wyewidencjonujesz, a nie każdą wersję pliku, jaka kiedykolwiek istniała.

Aby korzystać z Git LFS, potrzebujesz hosta obsługującego tę funkcję, takiego jak Bitbucket Cloud lub Bitbucket Data Center. Użytkownicy repozytorium będą musieli mieć zainstalowanego klienta wiersza polecenia Git LFS lub klienta z graficznym interfejsem użytkownika obsługującego Git LFS, takiego jak Sourcetree. Ciekawostka: Steve Streeting, deweloper Atlassian, który stworzył Sourcetree, jest również głównym współautorem projektu Git LFS, więc Sourcetree i Git LFS bardzo dobrze ze sobą współpracują.

1. Istnieją trzy proste sposoby instalacji Git LFS:

a. Zainstaluj to narzędzie za pomocą ulubionego menedżera pakietów. Pakietygit-lfs są dostępne dla programów Homebrew, MacPorts, dnf i packagecloud.

b. Pobierz i zainstaluj Git LFS ze strony internetowej projektu.

c. Zainstaluj Sourcetree, darmowego klienta Git z graficznym interfejsem użytkownika, który jest dostarczany z Git LFS.

2. Przejdź do katalogu git-lfs i uruchom polecenie git lfs install, aby zainicjować Git LFS (możesz pominąć ten krok, jeśli zainstalowano Sourcetree):

Polecenie git lfs install należy uruchomić tylko raz. Po zainicjowaniu dla Twojego systemu Git LFS uruchomi się automatycznie po sklonowaniu repozytorium z zawartością Git LFS.

Aby utworzyć nowe repozytorium Git LFS, uruchom polecenie git lfs install po utworzeniu repozytorium:

Spowoduje to zainstalowanie specjalnego hooka Git do wstępnego wypychania w repozytorium, który będzie przesyłał pliki Git LFS na serwer podczas operacji git push.

Obsługa Git LFS jest automatycznie włączona dla wszystkich repozytoriów Bitbucket Cloud. W przypadku Bitbucket Data Center musisz włączyć Git LFS w ustawieniach repozytorium:

Po zainicjowaniu Git LFS dla repozytorium możesz określić, które pliki mają być śledzone, używając polecenia git lfs track.

Po zainstalowaniu Git LFS możesz sklonować repozytorium Git LFS jak zwykle za pomocą polecenia git clone. Pod koniec procesu klonowania Git sprawdzi domyślną gałąź (zwykle main), a wszystkie pliki Git LFS potrzebne do zakończenia procesu realizacji transakcji zostaną pobrane automatycznie. Przykład:

W tym repozytorium są 4 pliki PNG śledzone przez Git LFS. Podczas uruchamiania polecenia git clone pliki Git LFS są pobierane pojedynczo, ponieważ pliki wskaźnika są wyewidencjonowane z repozytorium.

Jeśli klonujesz repozytorium z dużą liczbą plików LFS, polecenie git lfs clone jest znacznie bardziej wydajne:

Zamiast pobierać pliki Git LFS pojedynczo, polecenie git lfs clone czeka na zakończenie operacji wyewidencjonowania, a następnie pobiera wsadowo wszystkie wymagane pliki Git LFS. Wykorzystuje w ten sposób równoległe pobieranie oraz radykalnie zmniejsza liczbę żądań HTTP i tworzonych procesów (co jest szczególnie ważne dla poprawy wydajności w systemie Windows).

Podobnie jak w przypadku klonowania, możesz wykonać operację ściągnięcia kodu z repozytorium Git LFS, używając polecenia git pull. Wszystkie potrzebne pliki Git LFS zostaną pobrane w ramach automatycznego procesu wyewidencjonowania po zakończeniu operacji ściągnięcia kodu:

Do pobrania zawartości Git LFS nie są potrzebne żadne specjalne polecenia. Jeśli jednak wyewidencjonowanie nie powiedzie się z nieoczekiwanego powodu, możesz pobrać brakującą zawartość Git LFS dla bieżącego commitu za pomocą polecenia git lfs pull:

Podobnie jak git lfs clone, polecenie git lfs pull pobiera pliki Git LFS wsadowo. Jeśli wiesz, że duża liczba plików zmieniła się od ostatniej operacji ściągnięcia kodu, możesz wyłączyć automatyczne pobieranie Git LFS podczas wyewidencjonowania, a następnie wsadowo pobrać zawartość Git LFS za pomocą polecenia git lfs pull. W tym celu możesz nadpisać konfigurację Git, używając opcji -c podczas wywoływania polecenia git pull:

Ponieważ wymaga to sporo pisania, warto utworzyć prosty alias Git , aby wykonać operację wsadowego ściągania kodu Git i Git LFS:

Znacznie poprawi to wydajność, gdy będzie trzeba pobrać dużą liczbę plików Git LFS (szczególnie w systemie Windows).

Po dodaniu nowego typu dużego pliku do repozytorium musisz poinformować Git LFS, że ma być śledzony, określając wzorzec za pomocą polecenia git lfs track:

Cudzysłowy wokół "*.ogg" są ważne. Pominięcie ich spowoduje rozszerzenie symbolu wieloznacznego przez powłokę, a poszczególne wpisy zostaną utworzone dla każdego pliku z rozszerzeniem .ogg w bieżącym katalogu:

Wzorce obsługiwane przez Git LFS są takie same jak te obsługiwane przez .gitignore. Na przykład:

Te wzorce są względne w stosunku do katalogu, w którym uruchomiono polecenie git lfs track. Aby wszystko uprościć, najlepiej jest uruchomić polecenie git lfs track w katalogu głównym repozytorium. Warto pamiętać, że negatywnych wzorców (obsługiwanych przez .gitignore) nie można używać w przypadku Git LFS.

Po uruchomieniu polecenia git lfs track zauważysz nowy plik o nazwie .gitattributes w katalogu, w którym uruchomiono polecenie. Plik .gitattributes jest mechanizmem Git do wiązania specjalnych zachowań z określonymi wzorcami plików. Git LFS automatycznie tworzy lub aktualizuje pliki .gitattributes, aby powiązać śledzone wzorce plików z filtrem Git LFS. Jednak będzie trzeba samodzielnie zatwierdzić wszelkie zmiany w pliku .gitattributes w repozytorium:

Aby ułatwić obsługę, najłatwiej jest przechowywać wszystkie wzorce Git LFS w jednym pliku .gitattributes, zawsze uruchamiając polecenie git lfs track z katalogu głównego repozytorium. Można jednak wyświetlić listę wszystkich wzorców, które są aktualnie śledzone przez Git LFS (i pliki .gitattributes zawierające ich definicje), przez wywołanie polecenia git lfs track bez argumentów:

Śledzenie określonego wzorca za pomocą Git LFS można zatrzymać, usuwając odpowiedni wiersz z pliku .gitattributes lub uruchamiając polecenie git lfs untrack:

Po uruchomieniu polecenia git lfs untrack trzeba samodzielnie zatwierdzić zmiany w pliku .gitattributes jeszcze raz.

Operacje zatwierdzania i ściągnięcia kodu można wykonywać w repozytorium zawierającym zawartość Git LFS. Jeśli dokonano zmian w plikach śledzonych przez Git LFS, podczas przesyłania zawartości Git LFS na serwer pojawią się dodatkowe dane wyjściowe polecenia git push:

Jeśli przesyłanie plików LFS z jakiegoś powodu nie powiedzie się, operacja wypychania zostanie przerwana i będzie można bezpiecznie spróbować ponownie. Podobnie jak w przypadku Git, zawartość w magazynie Git LFS jest adresowalna, czyli przechowywana przy użyciu klucza, który jest skrótem SHA-256 samej zawartości. Oznacza to, że ponowne przesyłanie plików Git LFS na serwer jest zawsze bezpieczne — nie można przypadkowo zastąpić zawartości pliku Git LFS niewłaściwą wersją.

Aby przenieść repozytorium Git LFS od jednego dostawcy usług hostingowych do innego, można użyć kombinacji poleceń git lfs fetch i git lfs push, podając parametr --all opcja.

Przykład przenoszenia wszystkich repozytoriów Git i Git LFS ze zdalnej lokalizacji o nazwie github do zdalnej lokalizacji o nazwie bitbucket 😉:

Git LFS zazwyczaj pobiera tylko pliki potrzebne w przypadku commitów, które są faktycznie wyewidencjonowane lokalnie. Za pomocą polecenia git lfs fetch --recent można jednak wymusić pobranie dodatkowej zawartości przez Git LFS dla innych ostatnio zmodyfikowanych gałęzi:

Jest to przydatne do wsadowego pobierania nowej zawartości Git LFS (np. gdy wychodzisz na lunch) lub jeśli planujesz przejrzeć pracę członków zespołu i nie będziesz mieć później możliwości pobrania zawartości z powodu ograniczonej łączności z Internetem. Możesz na przykład uruchomić polecenie git lfs fetch --recent przed wejściem na pokład samolotu.

Git LFS uważa każdą gałąź lub tag zawierający commity mające mniej niż 7 dni za najnowsze. Możesz skonfigurować liczbę dni uznawanych za najnowsze, ustawiając właściwość lfs.fetchrecentrefsdays:

Domyślnie polecenie git lfs fetch --recent pobierze tylko zawartość Git LFS commitu na końcu ostatniej gałęzi lub tagu.

Możesz jednak skonfigurować Git LFS do pobierania zawartości wcześniejszych commitów z ostatnich gałęzi i tagów, konfigurując właściwość lfs.fetchrecentcommitsdays:

Używaj tego ustawienia ostrożnie. Jeśli masz często zmieniające się gałęzie, może to spowodować pobranie ogromnej ilości danych. Może to być jednak przydatne, jeśli chcesz przejrzeć częściowe zmiany w gałęzi, wybrane commity w różnych gałęziach lub zmienić historię.

Jak opisywaliśmy w temacie Przenoszenie repozytorium Git LFS między hostami można pobrać całą zawartość repozytorium Git LFS przy użyciu polecenia git lfs fetch --all:

Pliki z lokalnej pamięci podręcznej Git LFS możesz usunąć za pomocą polecenia git lfs prune:

Spowoduje to usunięcie wszystkich lokalnych plików Git LFS, które są stare. Stary plik to dowolny plik, do którego nie odwołuje się:

• aktualnie wyewidencjonowany commit;
• commit, który nie został jeszcze wypchnięty (do lokalizacji źródłowej lub dowolnej ustawionej dla lfs.pruneremotetocheck);
• najnowszy commit.

Domyślny ostatni commit to dowolny commit utworzony w ciągu ostatnich 10 dni. Jest to obliczane przez dodanie:

• wartość właściwości lfs.fetchrecentrefsdays omówionej w sekcji Pobieranie dodatkowej historii Git LFS (która domyślnie wynosi 7) do
• wartości właściwości lfs.pruneoffsetdays (która domyślnie wynosi 3).

Przesunięcie oczyszczania można skonfigurować tak, aby zawartość Git LFS była przechowywana przez dłuższy czas:

W przeciwieństwie do wbudowanego systemu usuwania zbędnych elementów Git zawartość Git LFS nie jest przycinana automatycznie, więc regularne uruchamianie polecenia git lfs prune jest dobrym pomysłem, jeśli chcesz zmniejszyć rozmiar repozytorium lokalnego.

Aby sprawdzić, jaki wpływ będzie miała operacja oczyszczania, użyj polecenia git lfs prune --dry-run:

Obiekty Git LFS, które zostaną wyczyszczone, można sprawdzić przy użyciu polecenia git lfs prune --verbose --dry-run:

Długie łańcuchy szesnastkowe w danych wyjściowych trybu --verbose to skróty SHA-256 (znane również jako identyfikatory obiektów lub OID) obiektów Git LFS, które mają zostać usunięte. Aby dowiedzieć się więcej o obiektach, które zostaną usunięte, możesz użyć technik opisanych w sekcji Znajdowanie ścieżek lub commitów zawierających odwołania do obiektu Git LFS.

Jako dodatkową kontrolę bezpieczeństwa, możesz użyć opcji --verify-remote, aby sprawdzić, czy zdalny magazyn Git LFS zawiera kopię obiektów Git LFS przed ich usunięciem:

Sprawia to, że proces usuwania jest znacznie wolniejszy, ale daje pewność, że wszelkie oczyszczone obiekty można odzyskać z serwera. Opcję --verify-remote można włączyć na stałe dla systemu, konfigurując globalnie właściwość lfs.pruneverifyremotealways:

Możesz też włączyć zdalną weryfikację tylko dla repozytorium kontekstowego, pomijając opcję --global w powyższym poleceniu.

Klient wiersza poleceń Git LFS nie obsługuje czyszczenia plików na serwerze, więc sposób ich usunięcia zależy od dostawcy usług hostingowych.

W Bitbucket Cloud możesz przeglądać i usuwać pliki Git LFS za pomocą opcji [Repository Settings > Git LFS]:

Należy pamiętać, że każdy plik Git LFS jest indeksowany przy użyciu skrótu SHA-256 OID. Ścieżki odwołujące się do poszczególnych plików nie są widoczne w interfejsie użytkownika. Wynika to z tego, że w wielu różnych commitach może być wiele różnych ścieżek, które mogą odnosić się do danego obiektu, więc ich szukanie byłoby bardzo powolne.

Aby ustalić, co faktycznie zawiera dany plik Git LFS, masz trzy opcje:

• Spójrz na obraz podglądu pliku i typ pliku w lewej kolumnie interfejsu użytkownika Bitbucket Git LFS.
• Pobierz plik za pomocą odnośnika znajdującego się w prawej kolumnie interfejsu użytkownika Bitbucket Git LFS. Wyszukaj commity odwołujące się do OID SHA-256 obiektu Git LFS, jak omówiono w następnej sekcji.

Jeśli masz identyfikator OID SHA-256 Git LFS, możesz ustalić, które commity się do niego odwołują, używając polecenia git log --all -p -S :

To wywołanie polecenia git log generuje poprawkę (-p) z commitów w każdej gałęzi (--all), która dodaje lub usuwa wiersz (-S) zawierający określony ciąg (OID SHA-256 Git LFS).

Łatka pokazuje commit i ścieżkę do obiektu LFS, a także użytkownika, który go dodał, i czas zatwierdzenia. Możesz po prostu wyewidencjonować commit, a Git LFS w razie potrzeby pobierze plik i umieści go w kopii roboczej.

Jeśli podejrzewasz, że dany obiekt Git LFS znajduje się w bieżącym wskaźniku HEAD lub w określonej gałęzi, możesz użyć polecenia git grep, aby znaleźć ścieżkę pliku, która się do niego odwołuje:

Wskaźnik HEAD lub rozszerzenie Power-Up można zastąpić dowolnym odwołaniem, commitem lub drzewem zawierającym obiekt Git LFS.

W niektórych sytuacjach może być konieczne pobranie tylko podzbioru dostępnej zawartości Git LFS dla konkretnego commitu. Na przykład podczas konfigurowania kompilacji ciągłej integracji do uruchamiania testów jednostkowych może być potrzebny tylko kod źródłowy, więc warto wykluczyć duże pliki, które nie są konieczne do kompilacji kodu.

Wzorzec lub podkatalog można wykluczyć przy użyciu polecenia git lfs fetch -X (lub --exclude):

Alternatywnie możesz dołączyć tylko określony wzorzec lub podkatalog. Na przykład inżynier dźwięku może pobrać tylko pliki ogg i wav, używając polecenia git lfs fetch -I (lub —include):

Jeśli połączysz uwzględnienia i wykluczenia, pobierane będą tylko pliki, które pasują do wzorca dołączania i nie pasują do wzorca wykluczenia. Na przykład aby pobrać wszystko z katalogu Assets oprócz plików gif, użyj takiego polecenia:

Wyklucza i uwzględnia obsługę tych samych wzorców co git lfs track i .gitignore. Możesz określić te wzorce jako stałe dla konkretnego repozytorium, ustawiając właściwości lfs.fetchinclude i lfs.fetchexclude:

Ustawienia te można również zastosować do każdego repozytorium w systemie, dodając opcję --global.

Niestety nie ma łatwego sposobu na rozwiązanie konfliktów związanych ze scalaniem plików binarnych. Dzięki blokowaniu plików Git LFS możesz zablokować pliki według rozszerzenia lub nazwy pliku i zapobiegać nadpisywaniu plików binarnych podczas scalania.

Aby skorzystać z funkcji blokowania plików LFS, musisz najpierw wskazać usłudze Git, jaki typ plików można zablokować. W poniższym przykładzie flaga „--lockable” jest dołączana do polecenia „git lfs track”, które przechowuje pliki PSD w LFS i oznacza je jako blokowane.

Następnie dodaj następujące elementy do pliku.gitattributes:

Przygotowując się do wprowadzenia zmian w pliku LFS, użyjesz polecenia lock, aby zarejestrować plik jako zablokowany na serwerze Git.

Gdy nie potrzebujesz już blokady plików, możesz ją usunąć za pomocą polecenia unlock w Git LFS.

Blokady plików Git LFS mogą być nadpisywane, podobnie jak git push, przy użyciu flagi --force. Nie należy używać flagi --force, nie mając pewności co do podejmowanych działań.