Verwenden von Git in der GitHub-Dokumentation

In diesem Artikel wird beschrieben, wie du einen Topic-Branch für das Dokumentationsrepository erstellst, Änderungen committest und deine Änderungen zurück in das Remoterepository überträgst.

Der Artikel geht davon aus, dass Sie das Dokumentations-Repository bereits lokal geklont haben und dass Sie die Änderungen auf Ihrem lokalen Computer und nicht auf GitHub oder in einem Codespace vornehmen. Weitere Informationen findest du unter Ein Repository klonen.

Einrichten deines Themenbranchs und Vornehmen von Änderungen

Führe die folgenden Schritte aus, während du an der Dokumentation arbeitest, um deine lokalen Branches mit deinen Remotestandorten synchron zu halten und um Mergekonflikte zu vermeiden.

1. Ändere im Terminal das aktuelle Arbeitsverzeichnis in den Speicherort, an dem du das Dokumentationsrepository geklont hast. Zum Beispiel:

   cd ~/my-cloned-repos/docs
   

2. Wechsle zum Standardbranch main.

   git checkout main
   

3. Rufe die neuesten Commits aus dem Remoterepository ab.

   git pull origin main
   

4. Wechsle zu einem Topic-Branch, oder erstelle einen Topic-Branch.

   • Um ein neues Projekt zu starten, erstelle einen neuen Topic-Branch aus main.

     git checkout -b YOUR-TOPIC-BRANCH
     

     Hinweis: Du kannst Schrägstriche als Teil des Branchnamens verwenden, z. B. um deinen Benutzernamen einzuschließen:

     git checkout -b my-username/new-codespace-policy
     

   • Um an einem vorhandenen Projekt zu arbeiten, wechsle zu deinem Topic-Branch, und führe die Änderungen aus main zusammen.

     git checkout YOUR-TOPIC-BRANCH
     git merge main
     

     Wenn Mergekonflikte auftreten, führe die Schritte weiter unten in diesem Artikel aus, um Mergekonflikte zu lösen.

5. Öffne deinen bevorzugten Text-Editor, bearbeite Dateien nach Bedarf, und speichere dann deine Änderungen.

Commit und Push deiner Änderungen

1. Wenn du bereit bist, deine Änderungen zu committen, öffne ein Terminal, und überprüfe den Status deines Topic-Branchs mit git status. Stelle sicher, dass die richtigen Änderungen angezeigt werden.

   git status
   On branch YOUR-TOPIC-BRANCH
   
   Changes not staged for commit:
     (use "git add <file>..." to update what will be committed)
     (use "git checkout -- <file>..." to discard changes in working directory)
           deleted:    example-deleted-file.md
           modified:   example-changed-file.md
   
   Untracked files:
     (use "git add <file>..." to include in what will be committed)
           example-new-file.md
   

2. Stelle die geänderten Dateien bereit, damit sie in deinem Topic-Branch committet werden können.

   • Wenn du neue Dateien erstellst oder vorhandene Dateien aktualisiert hast, verwende git add FILENAME [FILENAME...]. Zum Beispiel:

     git add example-new-file.md example-changed-file.md
     

     Dadurch wird die aktualisierte Version der Dateien dem Stagingbereich von Git hinzugefügt, über den Änderungen committet werden können. Um das Staging einer Datei aufzuheben, verwende git reset HEAD FILENAME. Beispiel: git reset HEAD example-changed-file.md.

   • Wenn du Dateien gelöscht hast, verwende git rm FILENAME [FILENAME...]. Zum Beispiel:

     git rm example-deleted-file.md
     

3. Committe deine Änderungen.

   git commit -m "Commit message title (max 72 characters)
   
   Optional fuller description of what changed (no character limit).
   Note the empty line between the title and the description,
   and the closing quotation mark at the end of the commit message."
   

   Dadurch werden die gestageten Änderungen lokal committet. Du kannst jetzt diesen Commit und alle anderen nicht gepusteten Commits an das Remoterepository pushen.

   Um diesen Commit zu entfernen, verwende git reset --soft HEAD~1. Nach dem Ausführen dieses Befehls werden unsere Änderungen nicht mehr committet, aber die geänderten Dateien verbleiben im Stagingbereich. Du kannst weitere Änderungen vornehmen und dann add und commit wieder ausführen.

4. Pushen Sie Ihre Änderungen in das entfernte Remoterepository auf GitHub.

   • Wenn du deinen Branch zum ersten Mal pushst, kannst du einen Upstreamnachverfolgungsbranch hinzufügen. Dadurch kannst du git pull und git push in diesem Branch ohne zusätzliche Argumente verwenden.

     git push --set-upstream origin YOUR-TOPIC-BRANCH
     

   • Wenn du diesen Branch zuvor gepusht und einen Upstreamnachverfolgungsbranch festgelegt hast, kannst du Folgendes verwenden:

     git push
     

Best Practices für Commits

• Es sollten Commits, die kleine, fokussierte Gruppen von Änderungen enthalten, gegenüber Commits mit großen, nicht fokussierten Gruppen von Änderungen bevorzugt werden, da dir dies hilft, Commitnachrichten zu schreiben, die andere Personen leicht verstehen können. Eine Ausnahme ist der anfängliche Commit für ein neues Projekt oder eine neue Kategorie. Diese Commits sind manchmal groß, da sie oft die bloßen Versionen vieler Artikel gleichzeitig einführen, um ein Organisationsschema für nachfolgende Arbeiten bereitzustellen.

• Wenn du Feedback einbinden oder dich aufgrund einer Reihe von Änderungen an eine bestimmte Person oder ein bestimmtes Team zur Überprüfung wenden möchtest, erwähne mit @mention die Person, deren Vorschläge du einbeziehst. Beispiel: „Feedback von @octocat integrieren“ oder „Abrechnungskonfigurationsschritte aktualisieren – @monalisa für Genauigkeit in CC setzen“.

• Wenn sich ein Commit um ein Issue kümmert, kannst du im Commit auf die Nummer des Issues verweisen, und ein Link zum Commit wird in der Unterhaltungszeitleiste des Issues angezeigt: „Gilt für #1234 – Fügt Schritte zum Sichern des virtuellen Computers vor dem Upgrade hinzu“.

  Hinweis: Wir schließen ein Issue in der Regel nicht über einen Commit. Um ein Issue zu schließen, öffne einen Pull Request, und füge der Beschreibung „Closes #1234“ hinzu. Das verknüpfte Issue wird geschlossen, wenn der Pull Request zusammengeführt wird. Weitere Informationen findest du unter Einen Pull Request zu einem Issue verknüpfen.

• Formuliere Commitnachrichten klar, detailliert und imperativ. Beispiel: „Fügt einen konzeptionellen Artikel zu 2FA hinzu“, nicht „Info hinzufügen“.

• Lasse keine ausgecheckten Änderungen in deinem lokalen Branch zurück, wenn du die Arbeit für den Tag beendet hast. Wenn du an einen guten Haltepunkt gelangst, committe und pushe deine Änderungen, damit deine Arbeit im Remoterepository gesichert wird.

• Pushen Sie nur bis zu GitHub, nachdem Sie einige Commits vorgenommen haben. Das Pushen nach jedem Commit führt zu Rauschen in unseren Ops-Kanälen in Slack und führt dazu, dass unnötige Builds ausgeführt werden.

Auflösen von Mergekonflikten

Wenn du versuchst, zwei Branches zusammenzuführen, die unterschiedliche Änderungen an demselben Teil einer Datei enthalten, erhältst du einen Mergekonflikt. In unserem Workflow tritt dies am häufigsten beim Zusammenführen von main in einen lokalen Topic-Branch auf.

Es gibt zwei Möglichkeiten, mit Mergekonflikten umzugehen:

• Bearbeite die Datei in deinem Text-Editor, und wähle aus, welche Änderungen beibehalten werden sollen. Committe dann die aktualisierte Datei über die Befehlszeile in deinen Topic-Branch.
• Mergekonflikt auf GitHub beheben

Auflösen von Mergekonflikten durch Bearbeiten der Datei und Committen der Änderungen

1. Du siehst, dass in der Befehlszeile Dateien mit Mergekonflikten vorhanden sind.

2. Öffne die erste dieser Dateien in deinem Text-Editor.

3. Suche in der Datei nach den Mergekonfliktmarkern.

    <<<<<<< HEAD
    Here are the changes you've made.
    =====================
    Here are the changes from the main branch.
    >>>>>>> main
   

4. Entscheide, welche Änderungen beibehalten werden sollen, und lösche die unerwünschten Änderungen und die Mergekonfliktmarker. Wenn du weitere Änderungen vornehmen musst, kannst du dies gleichzeitig tun. Du kannst z. B. die im vorherigen Codebeispiel gezeigten fünf Zeilen in die einzelne Zeile ändern:

   Here are the changes you want to use.
   

   Wenn mehrere Dateien mit Mergekonflikten vorhanden sind, wiederhole die vorherigen Schritte, bis alle Konflikte gelöst sind.

   Hinweis: Beim Auflösen von Mergekonflikten solltest du vorsichtig vorgehen. Manchmal akzeptierst du die eigenen Änderungen, ein anderes Mal verwendest du Upstreamänderungen aus dem main-Branch und wieder ein anderes Mal kombinierst du beide Änderungstypen. Wenn du nicht sicher bist, was die beste Lösung ist, dann sei Vorsichtig mit dem Ersetzen der Änderungen aus Upstream, da diese aus bestimmten Gründen vorgenommen wurden, die dir nicht bekannt sind.

5. Stelle im Terminal die soeben geänderte(n) Datei(n) bereit.

   git add changed-file-1.md changed-file-2.md
   

6. Committe die Dateien.

   git commit -m "Resolves merge conflicts"
   

7. Pushen Sie die übertragenen Änderungen in das Remoterepository auf GitHub.

   git push
   

Erstellen eines Pull Requests

Es wird empfohlen, den Pull Request für GitHub frühzeitig zu öffnen. Erstelle den Pull Request als Entwurf, bis du bereit bist, ihn zu überprüfen. Jedes Mal, wenn du Änderungen pushst, werden deine Commits dem Pull Request hinzugefügt.

Weitere Informationen findest du unter Erstellen eines Pull Requests.