git archive

Eksportuje zawartość drzewa repozytorium do archiwum tar lub zip.

git archive pakuje zawartość drzewa repozytorium (commita, tagu, gałęzi albo pojedynczego katalogu) do jednego pliku tar lub zip. W odróżnieniu od zwykłego tar bierze tylko pliki śledzone przez Gita w danym momencie historii, więc bez katalogu .git, bez śmieci z roboczego katalogu i bez plików ignorowanych. To idealne narzędzie, gdy chcesz wysłać komuś „czystą” wersję projektu w stanie z konkretnego wydania albo zbudować paczkę do deployu, nie wlokąc za sobą całej historii repozytorium.

Składnia i najważniejsze opcje

Podstawowa forma to git archive [--format=] [-o ] [<ścieżka>...], gdzie to commit, tag albo gałąź.

  • --format= — format archiwum: tar (domyślny), zip, tar.gz, tgz.
  • -o , --output= — zapis do pliku zamiast na standardowe wyjście; format jest zgadywany z rozszerzenia, jeśli nie podasz --format.
  • --prefix=/ — dokleja katalog na początku każdej ścieżki w archiwum (np. żeby po rozpakowaniu wszystko wylądowało w jednym folderze).
  • --remote= — pobiera archiwum z zdalnego repozytorium zamiast lokalnego.
  • -l, --list — wypisuje dostępne formaty archiwów.
  • --add-file= — dorzuca do archiwum plik spoza repozytorium (np. wygenerowany numer wersji).
  • --worktree-attributes — uwzględnia reguły z .gitattributes z katalogu roboczego (przydatne przy export-ignore).
  • -0 … -9 — poziom kompresji dla formatów zip/tgz (-0 bez kompresji, -9 najmocniej).

Przykłady użycia

  • git archive -o release.zip HEAD — pakuje bieżący stan gałęzi do pliku ZIP.
  • git archive --format=tar.gz -o v1.2.tar.gz v1.2.0 — tworzy skompresowane archiwum z taga v1.2.0.
  • git archive --prefix=mojprojekt/ -o src.tar.gz HEAD — wszystkie pliki trafią do katalogu mojprojekt/ po rozpakowaniu, bez bałaganu w bieżącym folderze.
  • git archive HEAD src/ docs/ | tar -x -C /tmp/wypakowane — eksportuje tylko wybrane katalogi i od razu rozpakowuje je do innej lokalizacji.
  • git archive --remote=git@serwer:repo.git --format=zip -o paczka.zip main — ściąga archiwum gałęzi main prosto ze zdalnego repo, bez klonowania.

Częste błędy i pułapki

Najczęstsza wpadka to zapomniany — git archive nie zakłada domyślnie HEAD i zwróci błąd, więc musisz jawnie podać commit, tag albo gałąź. Druga rzecz: bez -o komenda wypluwa surowe archiwum na stdout, więc jeśli odpalisz ją goło w terminalu, zalejesz ekran krzaczkami — albo przekieruj do pliku, albo do tar/unzip przez potok.

Pamiętaj, że --remote działa tylko, gdy zdalny serwer ma włączony git-upload-archive — niektóre hostingi (np. domyślnie GitHub) tego blokują i dostaniesz odmowę. Warto też wiedzieć, że pliki oznaczone w .gitattributes jako export-ignore nie trafią do archiwum, co bywa zaskoczeniem przy testach i plikach CI. Komenda jest cross-platformowa i zachowuje się identycznie na Linuksie, macOS i Windowsie, bo to logika samego Gita, a nie systemowego tar.

Powiązane komendy: git bundle (przenoszenie całego repo z historią), git clone, git checkout, oraz systemowe tar i zip do rozpakowywania.