Dieses Tutorial setzt voraus, dass Sie bereits recht vertraut mit der Verwendung von Git zur Verwaltung von Quellcode sind. Die Git-Workflow-Schritte werden weitgehend unerklärt bleiben.

Dieses Tutorial zielt darauf ab, die folgenden Dokumente zusammenzufassen, aber der Leser kann zusätzlichen Kontext nützlich finden

Wenn Sie nicht weiterkommen, können Sie an den folgenden Stellen Hilfe suchen.

Git wird an mehreren Orten gespiegelt. Klonen Sie das Repository von einem dieser Orte; https://git-scm.de/downloads schlägt vor, dass einer der besten Orte zum Klonen der Spiegel auf GitHub ist.

Um Git aus dem Quellcode zu kompilieren, müssen Sie eine Reihe von Abhängigkeiten auf Ihrem System installiert haben. Einen Hinweis darauf, was benötigt wird, finden Sie in der Datei INSTALL, wobei Sie besonders auf den Abschnitt über die Abhängigkeiten von Git von externen Programmen und Bibliotheken achten sollten. Dieses Dokument erwähnt eine Möglichkeit, unser frisch kompiliertes Git zu "testen", ohne es zu installieren. Das ist die Methode, die wir in diesem Tutorial verwenden werden.

Stellen Sie sicher, dass Ihre Umgebung alles Notwendige hat, indem Sie Ihren brandneuen Git-Klon aus dem obigen Schritt kompilieren

In diesem Tutorial fügen wir einen neuen Befehl hinzu, git psuh, kurz für „Pony Saying ‘Um, Hello’” – eine Funktion, die trotz hoher Aufrufhäufigkeit im typischen täglichen Workflow der Benutzer unvollendet geblieben ist.

(Wir haben in diesem Bereich einige andere Bemühungen mit der Implementierung beliebter Befehle wie sl gesehen.)

Beginnen wir damit, einen Entwicklungszweig für unsere Änderungen zu erstellen. Gemäß Documentation/SubmittingPatches ist es in Ordnung, Ihre Arbeit auf master zu basieren, da es sich um einen brandneuen Befehl handelt, der ein neues Feature ist. Für zukünftige Fehlerbehebungen usw. sollten Sie jedoch dieses Dokument prüfen und sich auf den entsprechenden Zweig stützen.

Für die Zwecke dieses Dokuments werden wir unsere gesamte Arbeit auf dem master-Zweig des Upstream-Projekts basieren. Erstellen Sie den psuh-Zweig, den Sie für die Entwicklung verwenden werden, wie folgt:

Wir werden hier eine Reihe von Commits vornehmen, um zu demonstrieren, wie ein Thema mit mehreren Patches gleichzeitig zur Überprüfung gesendet wird.

Viele der Unterbefehle werden als Built-ins geschrieben, was bedeutet, dass sie in C implementiert und in die Haupt- git-Ausführungsdatei kompiliert werden. Die Implementierung des sehr einfachen psuh-Befehls als Built-in wird die Struktur der Codebasis, die interne API und den Prozess der Zusammenarbeit mit den Gutachtern und dem Maintainer zur Integration dieser Änderung in das System demonstrieren.

Built-in-Unterbefehle werden typischerweise in einer Funktion namens „cmd_“ gefolgt vom Namen des Unterbefehls implementiert, in einer Quelldatei, die nach dem Unterbefehl benannt ist und sich in builtin/ befindet. Es ist daher sinnvoll, Ihren Befehl in builtin/psuh.c zu implementieren. Erstellen Sie diese Datei und schreiben Sie darin den Einstiegspunkt für Ihren Befehl in einer Funktion, die dem Stil und der Signatur entspricht

Ein paar Dinge zu beachten

Wir müssen auch die Deklaration von psuh hinzufügen; öffnen Sie builtin.h, finden Sie die Deklaration für cmd_pull und fügen Sie eine neue Zeile für psuh unmittelbar davor hinzu, um die Deklarationen alphabetisch zu sortieren

Stellen Sie sicher, dass Sie "builtin.h" in Ihre psuh.c einbinden. Sie müssen auch "gettext.h" einbinden, um Funktionen für die Ausgabe von Text zu verwenden.

Fügen Sie nun einige zufällige `printf`-Ausgaben zur Funktion cmd_psuh hinzu. Dies ist ein guter Ausgangspunkt, da wir nun Build-Regeln hinzufügen und den Befehl registrieren können.

Versuchen wir, es zu bauen. Öffnen Sie Makefile, suchen Sie, wo builtin/pull.o zu BUILTIN_OBJS hinzugefügt wird, und fügen Sie builtin/psuh.o auf die gleiche Weise daneben in alphabetischer Reihenfolge hinzu. Sobald Sie dies getan haben, wechseln Sie zum Stammverzeichnis und kompilieren Sie einfach mit make. Fügen Sie auch die Variable DEVELOPER=1 hinzu, um einige zusätzliche Warnungen zu aktivieren

Großartig, jetzt baut Ihr neuer Befehl eigenständig. Aber niemand ruft ihn auf. Ändern wir das.

Die Liste der Befehle befindet sich in git.c. Wir können einen neuen Befehl registrieren, indem wir eine cmd_struct zum Array commands[] hinzufügen. struct cmd_struct nimmt einen String mit dem Befehlsnamen, einen Funktionszeiger auf die Befehlsimplementierung und ein Setup-Optionsflag entgegen. Vorerst behalten wir die Nachahmung von push bei. Suchen Sie die Zeile, in der cmd_push registriert wird, kopieren Sie sie und ändern Sie sie für cmd_psuh, wobei Sie die neue Zeile in alphabetischer Reihenfolge einfügen (unmittelbar vor cmd_pull).

Die Optionen sind in builtin.h unter "Hinzufügen eines neuen Built-ins" dokumentiert. Da wir später einige Daten über den aktuellen Arbeitsbereich des Benutzers ausgeben möchten, benötigen wir ein Git-Verzeichnis, also wählen Sie RUN_SETUP als einzige Option.

Kompilieren Sie erneut. Sie sollten eine saubere Kompilierung sehen, also lassen Sie uns ihn testen, um zu sehen, ob er funktioniert. Es gibt eine ausführbare Datei, die Sie zum Testen verwenden können, im Verzeichnis bin-wrappers.

Schauen Sie sich das an! Sie haben einen Befehl! Gute Arbeit! Kommentieren wir das ein.

git status zeigt geänderte Makefile, builtin.h und git.c sowie nicht verfolgte builtin/psuh.c und git-psuh an. Nehmen wir uns zuerst die ausführbare Datei vor, die ignoriert werden sollte. Öffnen Sie .gitignore in Ihrem Editor, suchen Sie /git-pull und fügen Sie einen Eintrag für Ihren neuen Befehl in alphabetischer Reihenfolge hinzu

Wenn Sie erneut git status überprüfen, sollte angezeigt werden, dass git-psuh aus der Liste der nicht verfolgten Dateien entfernt wurde und .gitignore zur geänderten Liste hinzugefügt wurde. Jetzt können wir es stagen und committen

Ihr Editor wird angezeigt, um eine Commit-Nachricht zu schreiben. Beginnen Sie den Commit mit einer Betreffzeile von maximal 50 Spalten, die den Namen der Komponente, an der Sie arbeiten, enthält, gefolgt von einer Leerzeile (immer erforderlich) und dann dem Hauptteil Ihrer Commit-Nachricht, der den Großteil des Kontexts liefern sollte. Denken Sie daran, explizit zu sein und das "Warum" Ihrer Änderung anzugeben, besonders wenn es aus Ihrem Diff nicht leicht ersichtlich ist. Entfernen Sie beim Bearbeiten Ihrer Commit-Nachricht nicht den Signed-off-by-Trailer, der oben von -s hinzugefügt wurde.

Gehen Sie hin und inspizieren Sie Ihren neuen Commit mit git show. "psuh:" zeigt an, dass Sie hauptsächlich den Befehl psuh geändert haben. Die Betreffzeile gibt den Lesern eine Vorstellung davon, was Sie geändert haben. Die Sign-off-Zeile (-s) zeigt an, dass Sie dem Developer’s Certificate of Origin 1.1 zustimmen (siehe den Abschnitt [[dco]] in Documentation/SubmittingPatches).

Für den Rest des Tutorials wird der Einfachheit halber nur die Betreffzeile aufgeführt. Vollständig ausgearbeitete Beispiel-Commit-Nachrichten sind jedoch in der Referenzimplementierung verfügbar, die am Anfang dieses Dokuments verlinkt ist.

Es ist wahrscheinlich nützlich, zumindest etwas zu tun, außer eine Zeichenkette auszugeben. Beginnen wir damit, uns alles anzusehen, was wir bekommen.

Ändern Sie Ihre Implementierung von cmd_psuh so, dass die übergebenen Argumente ausgegeben werden, wobei die vorhandenen printf()-Aufrufe beibehalten werden; da die Argumente nun verwendet werden, entfernen Sie das UNUSED-Makro von ihnen

Bauen und ausprobieren. Wie Sie vielleicht erwarten, gibt es so ziemlich alles, was wir auf der Kommandozeile eingeben, einschließlich des Namens unseres Befehls. (Wenn prefix bei Ihnen leer ist, versuchen Sie cd Documentation/ && ../bin-wrappers/git psuh). Das ist nicht sehr hilfreich. Welche anderen Kontexte können wir also erhalten?

Fügen Sie eine Zeile hinzu, um "config.h" und "repository.h" einzubinden. Fügen Sie dann die folgenden Teile in den Funktionskörper ein: Funktionskörper

repo_config() ruft die Konfiguration aus den von Git bekannten Konfigurationsdateien ab und wendet Standard-Prioritätsregeln an. repo_config_get_string_tmp() sucht nach einem bestimmten Schlüssel ("user.name") und gibt Ihnen den Wert. Es gibt eine Reihe von Funktionen für die Einzelkey-Suche wie diese; Sie können sie alle (und weitere Informationen zur Verwendung von repo_config()) in Documentation/technical/api-config.adoc einsehen.

Sie sollten sehen, dass der ausgegebene Name mit dem übereinstimmt, den Sie sehen, wenn Sie Folgendes ausführen

Großartig! Jetzt wissen wir, wie man Werte in der Git-Konfiguration prüft. Committen wir dies auch, damit wir unseren Fortschritt nicht verlieren.

Dennoch wäre es schön zu wissen, wie der Arbeitskontext des Benutzers aussieht. Sehen wir mal, ob wir den Namen des aktuellen Zweigs des Benutzers ausgeben können. Wir können die Implementierung von git status nachahmen; der Drucker befindet sich in wt-status.c und wir können sehen, dass der Zweig in einer struct wt_status gehalten wird.

wt_status_print() wird von cmd_status() in builtin/commit.c aufgerufen. Wenn wir uns diese Implementierung ansehen, sehen wir, dass die Statuskonfiguration wie folgt gefüllt wird:

Wenn wir jedoch tiefer graben, können wir feststellen, dass status_init_config() einen Aufruf an repo_config() kapselt. Lassen Sie uns den Code ändern, den wir im vorherigen Commit geschrieben haben.

Stellen Sie sicher, dass Sie die Header-Datei einbinden, um die Verwendung von struct wt_status zu ermöglichen

Ändern Sie dann Ihre Implementierung von cmd_psuh, um Ihre struct wt_status zu deklarieren, sie vorzubereiten und ihre Inhalte auszugeben

Führen Sie es erneut aus. Schauen Sie sich das an – hier ist der (ausführliche) Name Ihres aktuellen Zweigs!

Lassen Sie uns das auch committen.

Sehen wir nun, ob wir einige Informationen über einen bestimmten Commit erhalten können.

Glücklicherweise gibt es hier einige Helfer für uns. commit.h hat eine Funktion namens lookup_commit_reference_by_name, der wir einfach einen fest codierten String übergeben können; pretty.h hat einen äußerst praktischen Aufruf pp_commit_easy(), der kein vollständiges Formatobjekt benötigt.

Fügen Sie die folgenden Includes hinzu

Fügen Sie dann die folgenden Zeilen in Ihre Implementierung von cmd_psuh() in der Nähe der Deklarationen bzw. der Logik ein.

Die struct strbuf bietet einige Sicherheitsgurte für Ihr grundlegendes char*, eines davon ist ein Längenmember zur Vermeidung von Pufferüberläufen. Es muss schön mit STRBUF_INIT initialisiert werden. Behalten Sie es im Hinterkopf, wenn Sie char* übergeben müssen.

lookup_commit_reference_by_name löst den Namen auf, den Sie ihm übergeben, sodass Sie mit dem Wert dort spielen und sehen können, welche Art von Dingen Sie sich ausdenken können.

pp_commit_easy ist eine praktische Wrapper-Funktion in pretty.h, die einen einzelnen Format-Enum-Kürzel anstelle einer vollständigen Format-Struktur entgegennimmt. Sie formatiert dann den Commit entsprechend diesem Kürzel. Diese ähneln den Formaten, die mit --pretty=FOO in vielen Git-Befehlen verfügbar sind.

Kompilieren und ausführen, und wenn Sie denselben Namen wie im Beispiel verwenden, sollten Sie die Betreffzeile des letzten Commits in origin/master sehen, den Sie kennen. Nett! Committen wir das auch.

Großartig! Sie haben einen fantastischen neuen Befehl, den Sie der Community zur Verfügung stellen möchten. Aber warten Sie einen Moment – das ist nicht sehr benutzerfreundlich. Führen Sie Folgendes aus

Ihr neuer Befehl ist undokumentiert! Lassen Sie uns das beheben.

Werfen Sie einen Blick auf Documentation/git-*.adoc. Dies sind die Manpages für die Unterbefehle, die Git kennt. Sie können diese öffnen und sich mit dem Format vertraut machen, aber dann erstellen Sie eine neue Datei Documentation/git-psuh.adoc. Wie die meisten Dokumentationen im Git-Projekt werden Hilfeseiten mit AsciiDoc geschrieben (siehe CodingGuidelines, Abschnitt "Writing Documentation"). Verwenden Sie die folgende Vorlage, um Ihre eigene Manpage auszufüllen

Die wichtigsten Teile, die man hier beachten sollte, sind die Dateikopfzeile, unterstrichen durch =, der ABSCHNITT NAME und die SYNOPSIS, die normalerweise die Grammatik enthalten würde, wenn Ihr Befehl Argumente entgegennimmt. Versuchen Sie, etablierte Manpage-Kopfzeilen zu verwenden, damit Ihre Dokumentation mit anderen Git- und UNIX-Manpages konsistent ist. Das erleichtert Ihrem Benutzer das Leben, der zu dem Abschnitt springen kann, von dem er weiß, dass er die benötigten Informationen enthält.

Nachdem Sie Ihre Manpage geschrieben haben, müssen Sie sie explizit kompilieren. Wir konvertieren Ihr AsciiDoc in troff, das für Manpages lesbar ist, wie folgt:

oder

Obwohl dies nicht so befriedigend ist wie die Ausführung von git help, können Sie zumindest überprüfen, ob Ihre Hilfeseite korrekt aussieht.

Sie können auch überprüfen, ob die Dokumentationsabdeckung gut ist (d. h. ob das Projekt erkennt, dass Ihr Befehl implementiert und dokumentiert wurde), indem Sie make check-docs vom Stammverzeichnis aus ausführen.

Fahren Sie fort und committen Sie Ihre neue Dokumentationsänderung.

Versuchen Sie, ./bin-wrappers/git psuh -h auszuführen. Ihr Befehl sollte am Ende abstürzen. Das liegt daran, dass -h ein Sonderfall ist, den Ihr Befehl durch die Anzeige der Nutzung behandeln sollte.

Werfen Sie einen Blick auf Documentation/technical/api-parse-options.adoc. Dies ist ein praktisches Werkzeug zum Extrahieren der benötigten Optionen und nimmt eine Nutzungszeichenkette entgegen.

Um es zu verwenden, müssen wir ein NULL-terminiertes Array von Nutzungszeichenketten und ein Array builtin_psuh_options vorbereiten.

Fügen Sie eine Zeile hinzu, um "parse-options.h" einzubinden.

Auf globaler Ebene fügen Sie Ihr Array von Nutzungszeichenketten hinzu

Fügen Sie dann innerhalb Ihrer Implementierung von cmd_psuh() Ihre option-Struktur hinzu und initialisieren Sie sie. Unsere ist ziemlich einfach, aber Sie können bei Bedarf mehr hinzufügen, um parse_options() genauer zu erkunden

Fügen Sie schließlich vor dem Ausgeben Ihrer Argumente und des Präfixes den Aufruf von parse-options() hinzu

Dieser Aufruf ändert Ihren argv-Parameter. Er entfernt die in options angegebenen Optionen aus argv und die von den options-Einträgen referenzierten Speicherorte werden aktualisiert. Stellen Sie sicher, dass Sie Ihr argc durch das Ergebnis von parse_options() ersetzen, sonst werden Sie verwirrt sein, wenn Sie versuchen, argv später zu parsen.

Es ist erwähnenswert, das spezielle Argument --. Wie Sie vielleicht wissen, verwenden viele Unix-Befehle --, um das Ende der benannten Parameter anzuzeigen. Alle Parameter nach -- werden lediglich als positionelle Argumente interpretiert. (Dies kann nützlich sein, wenn Sie etwas als Parameter übergeben möchten, das normalerweise als Flag interpretiert würde.) parse_options() beendet das Parsen, wenn es auf -- trifft, und gibt Ihnen den Rest der Optionen unverändert zurück.

Nun, da Sie einen Nutzungs-Hinweis haben, können Sie Git beibringen, wie er in der allgemeinen Befehlsliste angezeigt wird, die von git help git oder git help -a angezeigt wird und aus command-list.txt generiert wird. Suchen Sie die Zeile für git-pull, um Ihre Zeile git-psuh darüber in alphabetischer Reihenfolge einzufügen. Nun können wir einige Attribute über den Befehl hinzufügen, die beeinflussen, wo er in den oben genannten Hilfebefehlen erscheint. Die Oberseite von command-list.txt enthält einige Informationen darüber, was jedes Attribut bedeutet; in diesen Hilfeseiten werden die Befehle entsprechend diesen Attributen sortiert. git psuh ist benutzerorientiert, also "porcelain" – wir kennzeichnen es also als "mainporcelain". Für "mainporcelain"-Befehle zeigen die Kommentare am Anfang von command-list.txt an, dass wir optional auch ein Attribut aus einer anderen Liste hinzufügen können; da git psuh einige Informationen über den Arbeitsbereich des Benutzers anzeigt, aber nichts modifiziert, kennzeichnen wir es als "info". Achten Sie darauf, Ihre Attribute im gleichen Stil wie den Rest von command-list.txt beizubehalten, indem Sie Leerzeichen zum Ausrichten und Trennen verwenden

Bauen Sie erneut. Wenn Sie nun mit -h ausführen, sollten Sie Ihre Nutzung angezeigt bekommen und Ihr Befehl sollte beendet werden, bevor etwas anderes Interessantes passiert. Großartig!

Fahren Sie fort und committen Sie auch diesen.

Die Tests in Git befinden sich in t/ und werden mit einer 4-stelligen Dezimalzahl nach dem Schema benannt, das im Abschnitt "Naming Tests" von t/README gezeigt wird.

Da dies ein Spielzeugbefehl ist, nennen wir den Test t9999. Da jedoch viele Familien-/Unterbefehlskombinationen voll sind, scheint die beste Praxis zu sein, einen Befehl zu finden, der dem von Ihnen hinzugefügten nahe genug kommt, und seinen Namensraum zu teilen.

Erstellen Sie eine neue Datei t/t9999-psuh-tutorial.sh. Beginnen Sie mit der Kopfzeile wie folgt (siehe "Writing Tests" und "Source test-lib.sh" in t/README)

Tests werden in einem test_expect_success eingerahmt, um TAP-formatierte Ergebnisse auszugeben. Stellen wir sicher, dass git psuh nicht schlecht abbricht und irgendwo das richtige Tier erwähnt

Zeigen Sie an, dass Sie alles ausgeführt haben, was Sie wollten, indem Sie Folgendes am Ende Ihres Skripts hinzufügen

Stellen Sie sicher, dass Sie Ihr Testskript ausführbar machen

Sie können überprüfen, ob Sie Ihr neues Testskript erfolgreich erstellt haben, indem Sie make -C t test-lint ausführen, was auf Dinge wie eindeutige Testnummern, ausführbares Bit usw. prüft.

Versuchen wir, es lokal auszuführen

Sie können die gesamte Testsuite ausführen und sicherstellen, dass git-psuh nichts kaputt gemacht hat

Fahren Sie fort und committen Sie auch diese Änderung.

Zusätzlich zu einer E-Mail pro Patch erwartet die Git-Community auch, dass Ihre Patches mit einem Cover Letter geliefert werden. Dies ist eine wichtige Komponente der Änderungsübermittlung, da sie der Community aus einer High-Level-Perspektive erklärt, was Sie tun möchten und warum, auf eine Weise, die offensichtlicher ist, als nur Ihre Patches anzusehen.

Der Titel Ihres Cover Letters sollte etwas sein, das den Zweck Ihres gesamten Topic-Branches prägnant zusammenfasst. Er ist oft im Imperativ, genau wie die Titel unserer Commit-Nachrichten. So werden wir unsere Serie betiteln

Fügen Sie den psuh-Befehl hinzu ---

Der Körper des Cover Letters wird verwendet, um den Gutachtern zusätzlichen Kontext zu geben. Stellen Sie sicher, dass Sie alles erklären, was Ihre Patches nicht von sich aus klarstellen, aber denken Sie daran, dass der Cover Letter nicht in der Commit-Historie aufgezeichnet wird. Alles, was für zukünftige Leser der Repository-Historie nützlich sein könnte, sollte auch in Ihren Commit-Nachrichten stehen.

Hier ist ein Beispiel-Körper für psuh

An diesem Punkt weicht das Tutorial ab, um zwei verschiedene Methoden zur Formatierung Ihres Patchsets und zur Überprüfung vorzustellen.

Die erste Methode, die behandelt wird, ist GitGitGadget, das für diejenigen nützlich ist, die bereits mit dem gängigen Pull-Request-Workflow von GitHub vertraut sind. Diese Methode erfordert ein GitHub-Konto.

Die zweite Methode, die behandelt wird, ist git send-email, die etwas feinere Kontrolle über die zu sendenden E-Mails ermöglicht. Diese Methode erfordert eine Einrichtung, die je nach System variieren kann und in diesem Tutorial nicht behandelt wird.

Unabhängig davon, welche Methode Sie wählen, wird Ihre Interaktion mit den Gutachtern dieselbe sein; der Überprüfungsprozess wird nach den Abschnitten über GitGitGadget und git send-email behandelt.

Bevor Sie Ihren Patch zur Überprüfung über GitGitGadget senden können, müssen Sie das Git-Projekt forken und Ihre Änderungen hochladen. Zuerst – stellen Sie sicher, dass Sie ein GitHub-Konto haben.

Gehen Sie zum GitHub-Spiegel und suchen Sie nach dem Fork-Button. Platzieren Sie Ihren Fork, wo immer Sie es für angemessen halten, und erstellen Sie ihn.

Um Ihren Branch auf Ihre eigene Fork hochzuladen, müssen Sie die neue Fork als Remote hinzufügen. Sie können git remote -v verwenden, um die bereits hinzugefügten Remotes anzuzeigen. Von der Seite Ihrer neuen Fork auf GitHub können Sie auf "Clone or download" klicken, um die URL zu erhalten. Dann müssen Sie den folgenden Befehl ausführen, wobei Sie Ihre eigene URL und den Remote-Namen durch die angegebenen Beispiele ersetzen

oder um die HTTPS-URL zu verwenden

Führen Sie git remote -v erneut aus, und Sie sollten das neue Remote sehen. Verwenden Sie git fetch remotename (wobei remotename durch den tatsächlichen Namen Ihres Remotes ersetzt wird), um sich auf das Pushen vorzubereiten.

Überprüfen Sie anschließend, ob Sie die gesamte Entwicklung in einem neuen Branch durchgeführt haben, indem Sie git branch ausführen. Wenn nicht, ist jetzt ein guter Zeitpunkt, um Ihre neuen Commits in einen eigenen Branch zu verschieben.

Wie bereits kurz zu Beginn dieses Dokuments erwähnt, basiert unsere Arbeit auf master. Aktualisieren Sie daher wie unten gezeigt, oder mit Ihrem bevorzugten Workflow.

Schließlich sind Sie bereit, Ihren neuen Themen-Branch zu pushen! (Aufgrund unserer Branch- und Befehlsnamen-Auswahl sollten Sie beim Eingeben des folgenden Befehls vorsichtig sein.)

Sie sollten nun in der Lage sein, Ihren neu erstellten Branch auf GitHub zu überprüfen.

Damit Ihr Code getestet und für die Überprüfung formatiert wird, müssen Sie zunächst einen Pull Request gegen entweder gitgitgadget/git oder git/git öffnen. Navigieren Sie zu https://github.com/gitgitgadget/git oder https://github.com/git/git und öffnen Sie einen PR entweder mit der Schaltfläche "New pull request" oder der praktischen Schaltfläche "Compare & pull request", die mit dem Namen Ihres neu gepushten Branches angezeigt werden kann.

Die Unterschiede zwischen der Verwendung von gitgitgadget/git und git/git als Basis finden Sie [hier](https://gitgitgadget.github.io/#should-i-use-gitgitgadget-on-gitgitgadgets-git-fork-or-on-gits-github-mirror).

Überprüfen Sie den Titel und die Beschreibung des PRs, da diese von GitGitGadget als Betreff bzw. Hauptteil des Anschreibens für Ihre Änderung verwendet werden. Lesen Sie "Das Anschreiben" oben für Ratschläge zur Benennung Ihrer Einreichung und zum Inhalt der Beschreibung.

Wenn Sie zufrieden sind, reichen Sie Ihren Pull Request ein.

Wenn Sie GitGitGadget zum ersten Mal verwenden (was wahrscheinlich ist, da Sie dieses Tutorial verwenden), benötigt jemand Ihre Erlaubnis, um das Tool zu nutzen. Wie im GitGitGadget-Dokumentation erwähnt, müssen Sie nur jemanden, der es bereits verwendet, dazu bringen, Ihren PR mit /allow <username> zu kommentieren. GitGitGadget führt Ihre PRs auch ohne Erlaubnis automatisch durch die CI aus, aber Sie können Ihre Änderungen erst mit /submit einreichen, wenn Ihnen jemand die Nutzung des Tools erlaubt hat.

Wenn die CI fehlschlägt, können Sie Ihre Änderungen mit git rebase -i aktualisieren und Ihren Branch erneut pushen.

Tatsächlich sollten Sie Änderungen auf diese Weise fortsetzen, bis Ihr Patch in next aufgenommen wird.

Jetzt, da Ihre CI erfolgreich durchläuft und Ihnen jemand die Erlaubnis erteilt hat, GitGitGadget mit dem Befehl /allow zu nutzen, ist das Versenden zur Überprüfung so einfach wie das Kommentieren Ihres PRs mit /submit.

Springen Sie zu Antworten auf Überprüfungen, um Informationen darüber zu erhalten, wie Sie auf Überprüfungs-Kommentare reagieren, die Sie auf der Mailingliste erhalten.

Sobald Sie Ihren Branch nach allen Überprüfungs-Kommentaren wieder in Form gebracht haben, können Sie erneut einreichen.

Als Nächstes sehen Sie sich Ihren Pull Request bei GitGitGadget an; Sie sollten sehen, dass die CI erneut gestartet wurde. Während die CI läuft, ist es ein guter Zeitpunkt, Ihre Beschreibung am Anfang des Pull Request-Threads zu ändern. Sie wird erneut als Anschreiben verwendet. Verwenden Sie diesen Bereich, um zu beschreiben, was sich seit Ihrer vorherigen Version geändert hat, damit Ihre Gutachter eine Vorstellung davon bekommen, was sie sich ansehen. Wenn die CI abgeschlossen ist, können Sie erneut mit /submit kommentieren – GitGitGadget fügt Ihren Änderungen automatisch eine v2-Markierung hinzu.

Die Konfiguration für send-email kann je nach Betriebssystem und E-Mail-Anbieter variieren und wird daher in diesem Tutorial nicht behandelt, außer dass in vielen Linux-Distributionen git-send-email nicht zusammen mit der üblichen git-Installation installiert wird. Sie müssen möglicherweise dieses zusätzliche Paket installieren; es gibt eine Reihe von Online-Ressourcen, die Ihnen dabei helfen. Sie müssen auch den richtigen Weg zur Konfiguration Ihres SMTP-Servers ermitteln. Da diese Konfiguration je nach System und E-Mail-Einrichtung erheblich variieren kann, liegt sie außerhalb des Umfangs dieses Tutorials.

Das Senden von E-Mails mit Git ist ein zweistufiger Prozess. Bevor Sie die E-Mails selbst vorbereiten können, müssen Sie die Patches vorbereiten. Glücklicherweise ist dies ziemlich einfach.

Der Befehl erstellt eine Patch-Datei pro Commit. Nach der Ausführung können Sie jeden der Patches mit Ihrem bevorzugten Texteditor überprüfen und sicherstellen, dass alles in Ordnung ist. Es wird jedoch nicht empfohlen, Code-Korrekturen über die Patch-Datei vorzunehmen. Es ist besser, die Änderung auf normale Weise mit git rebase -i vorzunehmen oder einen neuen Commit hinzuzufügen, anstatt einen Patch zu ändern.

Prüfen Sie, ob Ihre Patches und die Vorlage für das Anschreiben im angegebenen Verzeichnis vorhanden sind – Sie sind fast bereit, Ihre Überprüfung zu versenden!

Da Sie format-patch mit --cover-letter aufgerufen haben, haben Sie bereits eine Vorlage für ein Anschreiben zur Hand. Öffnen Sie sie in Ihrem bevorzugten Editor.

Sie sollten bereits eine Reihe von Headern sehen. Überprüfen Sie, ob Ihr From:-Header korrekt ist. Ändern Sie dann Ihren Subject: (siehe oben, wie Sie einen guten Titel für Ihre Patch-Serie wählen).

Stellen Sie sicher, dass Sie den Teil "[PATCH 0/X]" beibehalten. Das zeigt der Git-Community, dass diese E-Mail der Beginn einer Patch-Serie ist, und viele Gutachter filtern ihre E-Mails nach dieser Art von Kennzeichnung.

Sie müssen zusätzliche Parameter angeben, wenn Sie git send-email aufrufen, um das Anschreiben hinzuzufügen.

Als Nächstes müssen Sie den Hauptteil Ihres Anschreibens ausfüllen. Lesen Sie auch hier oben, welche Inhalte einzubeziehen sind.

Die von git format-patch --cover-letter erstellte Vorlage enthält einen Diffstat. Dieser gibt den Gutachtern eine Zusammenfassung dessen, was sie bei der Überprüfung Ihres Themas erwartet. Der für psuh aus der Beispielimplementierung generierte sieht wie folgt aus

Schließlich enthält das Anschreiben die Git-Version, die zum Generieren der Patches verwendet wurde. Sie können diese Zeichenkette unverändert lassen.

Zu diesem Zeitpunkt sollten Sie ein Verzeichnis psuh/ haben, das mit Ihren Patches und einem Anschreiben gefüllt ist. Zeit, es zu versenden! Sie können es so senden

Nachdem Sie den obigen Befehl ausgeführt haben, werden Sie bei jedem Patch, der versendet werden soll, zu einer interaktiven Aufforderung aufgefordert. Dies gibt Ihnen eine letzte Chance, etwas zu bearbeiten oder das Senden abzubrechen (aber ändern Sie hier keine Code-Änderungen). Sobald Sie bei diesen Aufforderungen y oder a eingeben, werden Ihre E-Mails versendet! Herzlichen Glückwunsch!

Super, jetzt wird die Community alles stehen und liegen lassen, um Ihre Änderungen zu überprüfen. (Nur ein Scherz – seien Sie geduldig!)

Dieser Abschnitt konzentriert sich darauf, wie man eine v2 Ihres Patch-Satzes sendet. Um zu erfahren, was in v2 gehört, springen Sie zu Antworten auf Überprüfungen, um Informationen darüber zu erhalten, wie Sie mit Kommentaren von Gutachtern umgehen.

Wir werden unseren psuh-Themen-Branch für v2 wiederverwenden. Bevor wir Änderungen vornehmen, markieren wir die Spitze unseres v1-Branches zur einfachen Referenz.

Verfeinern Sie Ihre Patch-Serie, indem Sie git rebase -i verwenden, um Commits basierend auf Gutachterkommentaren anzupassen. Sobald die Patch-Serie zur Einreichung bereit ist, generieren Sie Ihre Patches erneut, aber mit einigen neuen Flags.

Der Parameter --range-diff master..psuh-v1 weist format-patch an, einen Range-Diff zwischen psuh-v1 und psuh in das Anschreiben aufzunehmen (siehe git-range-diff[1]). Dies hilft, den Gutachtern die Unterschiede zwischen Ihren v1- und v2-Patches mitzuteilen.

Der Parameter -v2 weist format-patch an, Ihre Patches als Version "2" auszugeben. Sie werden zum Beispiel feststellen, dass Ihre v2-Patches alle wie v2-000n-my-commit-subject.patch benannt sind. -v2 formatiert Ihre Patches auch, indem es sie mit "[PATCH v2]" anstelle von "[PATCH]" präfixiert, und Ihr Range-Diff wird mit "Range-diff against v1" präfixiert.

Nachdem Sie diesen Befehl ausgeführt haben, gibt format-patch die Patches in das Verzeichnis psuh/ aus, neben den v1-Patches. Die Verwendung eines einzelnen Verzeichnisses erleichtert das Referenzieren der alten v1-Patches beim Korrekturlesen der v2-Patches, aber Sie müssen darauf achten, nur die v2-Patches zu versenden. Wir werden ein Muster wie psuh/v2-*.patch verwenden (nicht psuh/*.patch, was v1- und v2-Patches entsprechen würde).

Bearbeiten Sie Ihr Anschreiben erneut. Dies ist ein guter Zeitpunkt, um zu erwähnen, was sich zwischen Ihrer letzten Version und jetzt geändert hat, wenn es sich um etwas Bedeutsames handelt. Sie benötigen nicht denselben Körper in Ihrem zweiten Anschreiben; konzentrieren Sie sich darauf, den Gutachtern die Änderungen zu erklären, die möglicherweise nicht so sichtbar sind.

Sie müssen auch die Message-ID Ihres vorherigen Anschreibens finden. Sie können sie entweder notieren, wenn Sie die erste Serie senden, aus der Ausgabe von git send-email, oder Sie können sie auf der Mailingliste nachschlagen. Suchen Sie Ihr Anschreiben in den Archiven, klicken Sie darauf, dann auf "Permalink" oder "Raw", um den Message-ID-Header anzuzeigen. Er sollte wie folgt aussehen

Ihre Message-ID ist <foo.12345.author@example.com>. Dieses Beispiel wird auch unten verwendet; stellen Sie sicher, dass Sie es durch die korrekte Message-ID für Ihr **vorheriges Anschreiben** ersetzen – das heißt, wenn Sie v2 senden, verwenden Sie die Message-ID von v1; wenn Sie v3 senden, verwenden Sie die Message-ID von v2.

Während Sie die E-Mail betrachten, sollten Sie auch darauf achten, wer per CC eingetragen ist, da es in der Mailingliste üblich ist, alle CCs in einem Thread zu belassen. Sie können diese CC-Zeilen direkt in Ihr Anschreiben mit einer Zeile wie dieser im Header (vor der Betreffzeile) einfügen.

Senden Sie nun die E-Mails erneut und achten Sie genau darauf, welche Nachrichten Sie an den Befehl übergeben.

In einigen Fällen kann Ihre sehr kleine Änderung nur aus einem einzigen Patch bestehen. Wenn das passiert, müssen Sie nur eine E-Mail senden. Ihre Commit-Nachricht sollte bereits aussagekräftig sein und den Zweck Ihres Patches auf hoher Ebene erklären (was passiert und warum), aber wenn Sie zusätzlichen Kontext angeben müssen, können Sie dies unterhalb der --- in Ihrem Patch tun. Sehen Sie sich das folgende Beispiel an, das mit git format-patch aus einem einzelnen Commit generiert und dann bearbeitet wurde, um den Inhalt zwischen den --- und dem Diffstat hinzuzufügen.

Nach ein paar Tagen erhalten Sie hoffentlich eine Antwort auf Ihren Patch-Satz mit einigen Kommentaren. Hurra! Jetzt können Sie sich wieder an die Arbeit machen.

Es gehört zum guten Ton, auf jeden Kommentar zu antworten und dem Gutachter mitzuteilen, dass Sie die vorgeschlagene Änderung vorgenommen haben, der Meinung sind, dass das Original besser ist, oder dass der Kommentar Sie zu einer neuen, besseren Vorgehensweise inspiriert hat, die sowohl besser ist als das Original als auch als der vorgeschlagene Vorschlag. Auf diese Weise müssen die Gutachter nicht Ihre v2 inspizieren, um herauszufinden, ob Sie ihren Kommentar implementiert haben oder nicht.

Gutachter könnten Sie nach dem fragen, was Sie im Patch-Satz geschrieben haben, entweder in der vorgeschlagenen Commit-Log-Nachricht oder in den Änderungen selbst. Sie sollten diese Fragen in Ihren Antwortnachrichten beantworten, aber oft liegt der Grund dafür, dass Gutachter diese Fragen stellen, um zu verstehen, was Sie schreiben wollten, darin, dass Ihr Patch-Satz zur Klärung benötigt wurde.

Geben Sie sich nicht damit zufrieden, nur ihre Fragen in Ihrer Antwort zu beantworten und zu hören, dass sie jetzt verstehen, was Sie sagen wollten. Aktualisieren Sie Ihre Patches, um die Punkte zu klären, mit denen die Gutachter Schwierigkeiten hatten, und bereiten Sie Ihre v2 vor. Die Worte, die Sie verwendet haben, um Ihre v1 zu erklären, um die Fragen der Gutachter zu beantworten, können nützlich sein. Ihr Ziel ist es, Ihre v2 so klar zu gestalten, dass es für Sie unnötig wird, dieselbe Erklärung dem nächsten Leser zu geben.

Wenn Sie einen Kommentar ablehnen, seien Sie höflich und erklären Sie, warum Sie glauben, dass Ihr Original besser ist. Seien Sie darauf vorbereitet, dass der Gutachter Ihnen möglicherweise immer noch nicht zustimmt und der Rest der Community sich auf die eine oder andere Seite stellt. Wie bei allen Code-Überprüfungen ist es wichtig, offen dafür zu sein, etwas anders zu machen, als Sie ursprünglich geplant hatten. Andere Gutachter haben eine andere Perspektive auf das Projekt als Sie und denken vielleicht an eine gültige Nebenwirkung, die Ihnen nicht eingefallen ist. Es ist immer in Ordnung, um Klärung zu bitten, wenn Sie nicht sicher sind, warum eine Änderung vorgeschlagen wurde oder was der Gutachter von Ihnen verlangt.

Stellen Sie sicher, dass Ihr E-Mail-Client einen Plain-Text-E-Mail-Modus hat und dieser aktiviert ist. Die Git-Liste lehnt HTML-E-Mails ab. Bitte befolgen Sie auch die auf der Mailingliste beschriebene Etikette in den MaintNotes, die den Etikette-Regeln in den meisten Open-Source-Communities ähneln, insbesondere in Bezug auf Bottom-Posting und Inline-Antworten.

Wenn Sie Änderungen an Ihrem Code vornehmen, ist es am saubersten – das heißt, die resultierenden Commits sind am einfachsten zu betrachten –, wenn Sie git rebase -i (interaktiver Rebase) verwenden. Sehen Sie sich diesen Überblick von O'Reilly an. Die allgemeine Idee ist, jeden Commit zu ändern, der Änderungen erfordert. Auf diese Weise, anstatt einen Patch A mit einem Fehler, einen Patch B, der in Ordnung war und keine Upstream-Überprüfungen in v1 erforderte, und einen Patch C, der Patch A für v2 behebt, haben, können Sie einfach eine v2 mit einem korrigierten Patch A und einem korrigierten Patch B versenden. Dies ist eine Änderung der Historie, aber da es sich um eine lokale Historie handelt, die Sie noch mit niemandem geteilt haben, ist das im Moment in Ordnung! (Später ist dies möglicherweise nicht sinnvoll. Sehen Sie sich den Abschnitt unter diesem an, um Kontext zu erhalten.)

Das Git-Projekt hat vier Integrations-Branches: seen, next, master und maint. Ihre Änderung wird ziemlich früh vom Maintainer in seen aufgenommen, während sie noch im Überprüfungsprozess ist; von dort wird sie in next zusammengeführt, wenn sie für breitere Tests bereit ist. Viele Frühtester verwenden next und berichten möglicherweise über Probleme. Schließlich werden Änderungen in next in master überführt, was typischerweise als stabil gilt. Schließlich wird bei der Veröffentlichung einer neuen Version maint verwendet, um Fehlerbehebungen darauf zu basieren. Wie zu Beginn dieses Dokuments erwähnt, können Sie Documents/SubmittingPatches lesen, um weitere Informationen zur Verwendung der verschiedenen Integrations-Branches zu erhalten.

Zurück zum Jetzt: Ihr Code wurde von den Upstream-Gutachtern gelobt. Er ist perfekt. Er ist bereit, angenommen zu werden. Sie müssen nichts weiter tun; der Maintainer wird Ihren Themen-Branch in next zusammenführen und alles ist gut.

Wenn Sie jedoch feststellen, dass er danach nicht mehr perfekt ist, müssen Sie möglicherweise je nach Ihrem Fortschritt einige spezielle Schritte unternehmen.

Wenn der Maintainer in der E-Mail "What’s cooking in git.git" angekündigt hat, dass Ihr Thema für next markiert ist – das heißt, dass er es in next zusammenführen möchte, aber noch nicht getan hat –, sollten Sie eine E-Mail senden und den Maintainer bitten, noch etwas länger zu warten: "Ich habe v4 meiner Serie gesendet und Sie haben sie für next markiert, aber ich muss dies und das ändern – bitte warten Sie auf v5, bevor Sie sie zusammenführen."

Wenn das Thema bereits in next zusammengeführt wurde, sollten Sie weitere Änderungen inkrementell vornehmen, anstatt Ihre Patches mit git rebase -i zu ändern – das heißt, mit einem weiteren Commit, der auf dem Themen-Branch des Maintainers basiert, wie unter https://github.com/gitster/git beschrieben. Ihre Arbeit befindet sich immer noch im selben Thema, ist aber jetzt inkrementell statt eine vollständige Neufassung des Themen-Branches.

Die Themen-Branches im GitHub des Maintainers werden in GitGitGadget gespiegelt. Wenn Sie Ihre Überprüfungen auf diese Weise versenden, sollten Sie sicherstellen, dass Sie Ihren PR gegen den entsprechenden GitGitGadget/Git-Branch öffnen.

Wenn Sie git send-email verwenden, können Sie es auf die gleiche Weise wie zuvor verwenden, aber Sie sollten Ihre Diffs von <topic>..<mybranch> generieren und Ihre Arbeit auf <topic> anstatt auf master basieren.