git am: E-Mail-Patches sauber anwenden

1. Was git am von git apply unterscheidet

git apply nimmt eine Patch-Datei entgegen und überträgt ausschließlich die enthaltenen Zeilenänderungen in den Arbeitsbaum, ganz ohne einen Commit zu erzeugen. Es eignet sich damit gut, um schnell zu prüfen, ob ein Patch überhaupt sauber passt, oder um Änderungen probehalber lokal anzuwenden, ohne die Historie zu verändern.

git am geht einen entscheidenden Schritt weiter: Es erwartet eine Patch-Datei im Format, das git format-patch erzeugt, inklusive E-Mail-Header mit Autor, Datum und Betreffzeile, und erstellt daraus einen vollständigen, eigenständigen Commit. Damit bleibt beim Empfänger nicht nur der Codeunterschied erhalten, sondern die komplette Provenienz der Änderung, genau wie beim ursprünglichen Autor.

# Nur den Diff anwenden, ohne Commit
git apply 0001-fix-cache-invalidation.patch

# Vollständigen Commit inklusive Autor, Datum und Nachricht wiederherstellen
git am 0001-fix-cache-invalidation.patch

2. Aufbau eines Email-Patches, den git am erwartet

Eine Patch-Datei im von git am erwarteten Format beginnt mit klassischen E-Mail-Kopfzeilen wie From, Date und Subject, gefolgt von der eigentlichen Commit-Nachricht und schließlich dem Diff selbst im unified-diff-Format. Genau dieses Format erzeugt git format-patch automatisch aus jedem Commit, weshalb beide Befehle als natürliches Gegenstückpaar funktionieren.

Wichtig ist dabei die Betreffzeile: Sie folgt üblicherweise dem Muster [PATCH] gefolgt von der eigentlichen Commit-Betreffzeile, und git am nutzt genau diesen Teil, um die spätere Commit-Nachricht zu rekonstruieren. Fehlt dieses Format oder ist die Datei kein gültiger Patch, meldet git am sofort einen Fehler, statt stillschweigend eine unvollständige Änderung zu übernehmen.

# Anfang einer typischen, von git format-patch erzeugten Datei
From 3f2c1a9b1e4d6a7c8b9e0f1a2b3c4d5e6f7a8b9c Mon Sep 17 00:00:00 2001
From: Jane Developer <jane@example.com>
Date: Mon, 3 Aug 2026 10:15:00 +0200
Subject: [PATCH] Fix cache invalidation on product save

3. Einen einzelnen Patch anwenden

Der einfachste Fall ist ein einzelner Patch als lokale Datei: git am pfad/zum/patch liest die Datei, prüft, ob sie sauber auf den aktuellen Stand des Arbeitsbaums passt, und erstellt bei Erfolg direkt einen neuen Commit mit den ursprünglichen Metadaten. Der Arbeitsbaum muss dafür sauber sein, ausstehende, nicht committete Änderungen verhindern den Vorgang.

Wird statt eines Dateipfads ein Verzeichnis angegeben, wendet git am automatisch alle darin enthaltenen Patch-Dateien in alphabetischer Reihenfolge an, was sich gut mit der von git format-patch erzeugten Nummerierung wie 0001-, 0002- kombinieren lässt, um eine ganze Serie in korrekter Reihenfolge einzuspielen.

# Einen einzelnen Patch anwenden
git am 0001-fix-cache-invalidation.patch

# Alle Patch-Dateien eines Verzeichnisses in alphabetischer Reihenfolge anwenden
git am patches/

4. Ganze Patch-Serien aus einer mbox-Datei anwenden

Viele E-Mail-Programme und Mailinglisten-Archive erlauben den Export ganzer Threads als einzelne mbox-Datei, die mehrere E-Mails hintereinander in einem gemeinsamen Textformat enthält. git am erkennt dieses Format automatisch, teilt die Datei intern in einzelne Patches auf und wendet sie nacheinander an, ganz ohne dass die Patches vorher manuell in einzelne Dateien zerlegt werden müssen.

Das ist besonders praktisch bei Patch-Serien aus Projekten, die ausschließlich über Mailinglisten arbeiten: Der komplette Thread wird als eine mbox-Datei heruntergeladen, und ein einziger Aufruf von git am spielt die gesamte Serie in der ursprünglichen Reihenfolge ein.

# Eine ganze mbox-Datei mit mehreren Patches am Stück anwenden
git am gesamte-patch-serie.mbox

5. Konflikte während git am beheben

Passt ein Patch nicht sauber auf den aktuellen Stand des Arbeitsbaums, unterbricht git am den Vorgang beim betroffenen Patch und markiert die Konfliktstellen im Arbeitsbaum genau wie bei einem regulären Merge-Konflikt. Nach dem manuellen Auflösen der Konflikte werden die betroffenen Dateien mit git add markiert, und git am --continue setzt den Vorgang mit dem nächsten Patch der Serie fort.

Lässt sich ein einzelner Patch nicht sinnvoll auflösen, etwa weil er inzwischen durch eine andere Änderung vollständig überholt ist, überspringt git am --skip genau diesen einen Patch und fährt mit dem nächsten fort. Soll der gesamte Vorgang stattdessen rückgängig gemacht werden, stellt git am --abort den ursprünglichen Zustand vor dem ersten angewendeten Patch der Serie vollständig wieder her.

# Konflikt manuell auflösen, dann fortsetzen
git add pfad/zur/konfliktdatei.php
git am --continue

# Diesen einen Patch überspringen und mit dem nächsten weitermachen
git am --skip

# Gesamten Vorgang abbrechen und Ausgangszustand wiederherstellen
git am --abort

6. Drei-Wege-Merge als Fallback mit --3way

Standardmäßig versucht git am, einen Patch rein textuell anhand der im Patch enthaltenen Zeilenkontexte anzuwenden. Das scheitert häufiger, als man erwarten würde, sobald sich der umgebende Code seit der Patch-Erstellung leicht verändert hat, selbst wenn die eigentliche Änderung inhaltlich weiterhin problemlos passen würde.

Die Option --3way aktiviert stattdessen einen echten Drei-Wege-Merge, bei dem Git zusätzlich die im Patch referenzierte Basisversion der Datei heranzieht, sofern diese im lokalen Repository vorhanden ist. Dadurch lassen sich deutlich mehr Patches automatisch anwenden, selbst wenn sich der Kontext ringsum bereits leicht verschoben hat, während echte inhaltliche Konflikte weiterhin klar als solche markiert werden.

# Drei-Wege-Merge aktivieren, deutlich robuster bei leicht verschobenem Kontext
git am --3way 0001-fix-cache-invalidation.patch

7. Signoff und Metadaten beim Anwenden ergänzen

In vielen Open-Source-Projekten, insbesondere im Kernel-Umfeld, verlangt der Beitragsprozess eine Signed-off-by-Zeile in jeder Commit-Nachricht als formale Bestätigung, dass der Beitrag unter der Projektlizenz eingereicht werden darf. Wer einen fremden Patch mit git am anwendet und dabei selbst als weiterer Signoff auftreten möchte, kann die Option --signoff nutzen, die automatisch eine zusätzliche Signed-off-by-Zeile mit den lokal konfigurierten Nutzerdaten anhängt.

Das ist vor allem relevant, wenn Patches über einen zusätzlichen Zwischenschritt weitergereicht werden, etwa wenn ein Maintainer einen Patch aus einer Mailingliste übernimmt und mit eigenem Signoff an das Projekt weiterleitet, ohne dabei den ursprünglichen Autor oder dessen Commit-Nachricht zu verändern.

# Zusätzliche Signed-off-by-Zeile beim Anwenden anhängen
git am --signoff 0001-fix-cache-invalidation.patch

8. Patches aus dem Mail-Client extrahieren und vorbereiten

Für den Empfang eines einzelnen Patches per E-Mail genügt es meist, die Nachricht im Rohformat als .eml- oder Textdatei zu speichern und direkt an git am zu übergeben, sofern der Mail-Client die Nachricht nicht zusätzlich als HTML umformatiert und dadurch die Zeilenumbrüche des Diffs zerstört hat. Genau dieses Risiko ist der Hauptgrund, warum viele Projekte für den Patch-Versand explizit reine Text-E-Mail-Clients oder git send-email empfehlen.

Werden mehrere zusammengehörige Patches als separate E-Mails empfangen, lassen sie sich entweder einzeln nacheinander speichern und mit git am anwenden, oder gemeinsam als ein Thread in eine einzige mbox-Datei exportieren, was bei größeren Serien meist der deutlich schnellere Weg ist.

9. Praxiskontext: Wann git am dem Pull-Request-Workflow vorzuziehen ist

Für Projekte mit einem zentralen Forge wie GitLab oder GitHub bleibt der klassische Pull-Request-Workflow meist die pragmatischere Wahl, weil er Inline-Kommentare, ein Web-Interface und eine automatische CI-Integration mitbringt, die git am von Haus aus nicht bietet. Der patch-basierte Workflow entfaltet seine Stärken vor allem dort, wo genau diese zentrale Infrastruktur fehlt oder bewusst vermieden wird.

Für dezentrale Projekte, Offline-Beiträge oder Umgebungen, in denen ein einzelner Maintainer Patches aus verschiedensten Quellen zusammenführt, bleibt git am jedoch das robusteste Werkzeug, weil es Autor, Zeitpunkt und Commit-Nachricht der ursprünglichen Änderung verlässlich erhält, unabhängig davon, über welchen Kanal der Patch tatsächlich übertragen wurde.

10. Zusammenfassung

11. FAQ: git am