git format-patch

Generuje pliki patchy z commitów, gotowe do wysłania mailem.

git format-patch bierze wskazane commity i zamienia każdy z nich w osobny plik .patch — czyli tekstowy zapis zmian razem z autorem, datą, opisem i pełnym diffem, sformatowany tak, żeby dało się go wysłać mailem i zaaplikować po drugiej stronie przez git am. To podstawowe narzędzie workflowu „patche przez maila” (tak działa jądro Linuksa i wiele projektów open source), ale przydaje się też zwyczajnie do przenoszenia kilku commitów między repozytoriami bez pushowania na zdalny serwer.

Składnia i najważniejsze opcje

Podstawowa forma to git format-patch [-o ]. Zakres podajesz jako punkt odniesienia, np. origin/main albo HEAD~3.

  • -o — zapisuje patche do wskazanego katalogu zamiast do bieżącego.
  • --stdout — wypluwa wszystko na standardowe wyjście (wygodne do przekierowania do jednego pliku mbox).
  • - — bierze ostatnie n commitów, np. -3 zamiast liczenia zakresu.
  • --cover-letter — dorzuca pusty list przewodni (plik 0000) do opisania całej serii.
  • -v (--reroll-count) — oznacza serię jako kolejną wersję, np. [PATCH v2].
  • -s (--signoff) — dokleja linię Signed-off-by:, wymaganą w wielu projektach.
  • --subject-prefix — podmienia domyślne [PATCH] w temacie na własne.
  • --base — dopisuje informację o commicie bazowym, żeby odbiorca wiedział, na czym aplikować.

Przykłady użycia

  • git format-patch -1 HEAD — robi jeden patch z ostatniego commita.
  • git format-patch origin/main — generuje patche dla wszystkich commitów, które masz lokalnie ponad origin/main.
  • git format-patch -3 -o ~/patche — zapisuje trzy ostatnie commity jako osobne pliki w katalogu ~/patche.
  • git format-patch main..feature --cover-letter — cała seria z gałęzi feature plus list przewodni do opisu zmian.
  • git format-patch --stdout HEAD~5 > seria.mbox — pięć commitów w jednym pliku, gotowym do git am seria.mbox po drugiej stronie.

Częste błędy i pułapki

Najczęstsza wpadka to pomylenie zakresu: git format-patch HEAD~3 oznacza „trzy commity od HEAD~3 do HEAD”, a nie „commit HEAD~3″. Jak chcesz konkretnie ostatnie trzy, użyj -3. Pamiętaj też, że format-patch niczego nie wysyła — tylko tworzy pliki. Do wysyłki służy git send-email. Drugą stroną medalu jest aplikowanie: git apply nakłada same zmiany w plikach, ale nie tworzy commita ani nie zachowuje autora — do pełnego odtworzenia commita razem z metadanymi użyj git am. Uważaj na binarki: domyślnie patche je zawierają, ale niektóre serwery pocztowe psują takie maile, więc czasem zobaczysz --no-binary. format-patch działa tak samo na Linuksie, macOS i Windowsie — różnice bywają tylko w końcach linii, więc skonfiguruj core.autocrlf, zanim narobisz sobie konfliktów na pustym miejscu.

Powiązane komendy: git am, git apply, git send-email, git diff, git cherry-pick.