Lokales Einrichten eines Git-Repositorys für die Dokumentation

Dieser Artikel beschreibt die Schritte zum Einrichten eines Git-Repositorys auf Ihrem lokalen Computer in der Absicht, zur Microsoft-Dokumentation beizutragen. Mitwirkende können ein lokal geklontes Repository verwenden, um neue Artikel hinzuzufügen, größere Änderungen an vorhandenen Artikel vorzunehmen oder Grafiken zu ändern.

Sie müssen die folgenden Einrichtungsaktivitäten einmalig ausführen, um mit der Mitwirkung zu beginnen:

  • Ermitteln des geeigneten Repositorys.
  • Fork des Repositorys zu Ihrem GitHub-Konto
  • Auswählen eines lokalen Ordners für die geklonten Dateien.
  • Klone das Repository auf deinen lokalen Computer.
  • Konfigurieren des Upstreamremotewerts.

Wichtig

Wenn Sie nur kleine Änderungen vornehmen, müssen Sie die Schritte in dieser Anleitung nicht durchführen. Lesen Sie Bearbeiten im Browser , um zu erfahren, wie Sie schnelle Bearbeitungen vornehmen können, ohne Tools zu installieren.

Überblick

Um an der Dokumentation auf Microsoft Learn mitzuwirken, können Sie Markdowndateien lokal erstellen und bearbeiten, indem Sie das entsprechende Dokumentationsrepository klonen. Microsoft erfordert, dass Sie das entsprechende Repository in Ihr eigenes GitHub-Konto forken, damit Sie über Lese-/Schreibberechtigungen verfügen, um Ihre Änderungsvorschläge zu speichern. Dann verwenden Sie Pullanforderungen (PRs), um die Änderungen in das schreibgeschützte gemeinsam genutzte Zentralrepository zu mergen.

Screenshot showing the GitHub workflow for information flowing between the upstream, origin, and local clone.

Das Microsoft Repository wird häufig als Upstream-Repository bezeichnet. Mit der Fork-Aktion in der GitHub-Benutzeroberfläche forkt der Benutzer das Microsoft Repository in sein eigenes GitHub-Konto. Dieser Fork wird als Ursprung bezeichnet. Mit git clone klont der Benutzer den Origin auf seinen lokalen Computer. Schließlich verwendet der Benutzer git remote add upstream, um seinen lokalen Klon wieder mit dem Microsoft-Upstream-Repository zu verbinden.

Ermitteln des Repositorys

Die Dokumentation, die auf Microsoft Learn gehostet wird, befindet sich in mehreren Repositories auf GitHub.

  1. Wenn Sie sich nicht sicher sind, in welchem Repository sich ein Artikel befindet, besuchen Sie den Artikel mit Ihrem Webbrowser. Wählen Sie den Link Bearbeiten (Bleistiftsymbol) in der oberen rechten Ecke des Artikels.

    Screenshot of the pencil edit icon on a Microsoft documentation article.

  2. Diese Aktion führt Sie zur Quelldatei auf GitHub. Der Repository-Name wird in der oberen linken Ecke der Seite angezeigt.

    Screenshot of where the repo name is found in a GitHub repo.

    Hier sind einige beliebte Repositories, die für öffentliche Beiträge zur Verfügung stehen:

Forken des Repositorys

Nachdem Sie das richtige Repository identifiziert haben, besteht der nächste Schritt darin, das Repository in Ihr eigenes GitHub-Konto zu forken.

Wenn Sie ein Repository forken, wird eine Kopie davon in Ihrem GitHub-Konto erstellt. Es ist ein persönlicher Fork erforderlich, da alle Dokumentations-Repositories von Microsoft nur Lesezugriff bieten, Ihr Fork jedoch Schreibzugriff ermöglicht, um Ihre Änderungen vorzunehmen. Der Fork ermöglicht es Ihnen, PRs von Ihrem Fork für das Microsoft Repository zu öffnen.

  1. Wählen Sie auf der GitHub-Seite oben rechts des Haupt-Repositorys die Schaltfläche Fork aus.

    Screenshot of the fork icon in the GitHub user interface.

  2. Vergewissern Sie sich im Fenster Erstellen eines neuen Forks, dass unter Besitzer Ihr Benutzernamen hinterlegt ist und dass Nur den Mainbranch kopieren aktiviert ist. Optional können Sie die Felder Repository-Name und Beschreibung ändern.

    Screenshot of the Create a new fork screen.

Klonen des Repositorys

Klonen bedeutet, eine Kopie eines Repositorys auf Ihrem lokalen Rechner zu erstellen.

Warnung

  1. Klonen Sie KEINE lokalen Repositorys in OneDrive-synchronisierten Ordnern. Vermeiden Sie beim Auswählen des Ordners, in den Sie das Repository klonen, Ordner, die mit OneDrive synchronisiert werden (z. B. Ihren Ordner Dokumente). OneDrive kann zu unbeabsichtigten Zusammenführungskonflikten führen, wenn Sie Ihre Änderungen wieder mit der Mainbranch zusammenführen. Stattdessen ist es am besten, einen kurzen Dateipfad auf Ihrem C:\-Laufwerk zu erstellen (z B. C:\GitHub).

  2. Git unter Windows: Aktivieren langer Pfadnamen. Bei Git für Windows ist die Unterstützung für lange Dateipfade standardmäßig deaktiviert, wodurch verhindert wird, dass Dateien mit einem Zielpfad, der länger als 255 Zeichen ist, geklont werden. Aktivieren Sie lange Dateipfade, um dieses Problem zu umgehen, indem Sie den folgenden Befehl als Administrator ausführen:
    git config --global core.longpaths true

  1. Erstellen Sie auf Ihrem lokalen Computer einen GitHub-Ordner. Zum Beispiel: C:\GitHub. (Klonen Sie nicht in einen OneDrive-Synchronisations-Ordner.)

  2. Wechseln Sie in einem Browser zu GitHub.com und melden Sie sich an.

  3. Wählen Sie in GitHub oben rechts in der Dropdownliste Ihres Profils Ihre Repositorys aus. Die Repository-Seite wird mit einer Liste Ihrer geforkten Repositories angezeigt.

  4. Wählen Sie das Repository aus, das Sie klonen möchten. Die Repository-Seite Ihres Forks wird angezeigt.

    Vergewissern Sie sich, dass Sie sich auf der Repository-Seite für Ihren Fork befinden, nicht auf der Seite für das Produktions-Repository. Sie können sich vergewissern, dass es sich bei dem Repository, auf dem Sie sich befinden, um Ihren Fork handelt, indem Sie die URL überprüfen: Sie sollte Ihren GitHub-Benutzernamen anzeigen und nicht die Microsoft-Organisation (zum Beispiel https://github.com/nancydavolio/azure-docs und NICHThttps://github.com/MicrosoftDocs/azure-docs). Außerdem sehen Sie oben links Ihren Namenund eine Notiz, die besagt: geforkt von, gefolgt von dem Namen des Standard-Repositorys.

    Screenshot showing a forked repo in GitHub.

  5. Wählen Sie die Registerkarte <>-Code oben links auf der Seite.

  6. Kopieren Sie auf der rechten Seite in der Code-Dropdown-Liste die URL unter der HTTPS-Option.

    Screenshot showing how to copy the clone HTTPS URL in GitHub.

Wichtig

Sie haben die Klon-URL über die GitHub-Benutzeroberfläche kopiert. Die restlichen Schritte sollten im VS Code Terminal ausgeführt werden.

Klonen in Visual Studio Code

  1. Öffnen Sie Visual Studio Code.

  2. Wählen Sie im oberen Navigationsmenü Ansicht und dann Terminal aus. Die Terminal-Ansicht wird am unteren Rand des Visual Studio Code-Bildschirms angezeigt.

  3. Führen Sie in der Terminal-Ansicht den Befehl zum Wechseln des Verzeichnisses (cd) zum GitHub-Ordner aus, den Sie in Schritt 1 im Abschnitt Klonen eines Repositorys auf Ihrem Laufwerk angelegt haben.

    Beispiel:

     cd C:\GitHub
    

    Wenn eine Fehlermeldung angezeigt wird, müssen Sie möglicherweise das Verzeichnis einzeln wechseln.

  4. Führen Sie den folgenden Befehl aus, um das Repository zu klonen:

    git clone <paste the clone URL you copied via the GitHub UI>
    

    Beispiel:

    git clone https://github.com/nancydavolio/azure-docs.git
    
  5. Wenn Sie aufgefordert werden, sich über den Browser zu authentifizieren, wählen Sie die Schaltfläche „Mit Ihrem Browser anmelden“ aus, und schließen Sie den Vorgang ab. Laden Sie unbedingt die neueste Version von Git herunter, die die Authentifizierung über Browserfunktionen unterstützt. Wenn Sie ein GitHub-Zugriffstoken verwenden, können Sie eine der folgenden Anweisungen generieren: Erstellen eines persönlichen Zugriffstokens.

    Der Befehl „Klonen“ lädt die Repository-Dateien aus Ihrem Fork in einen neuen Ordner an den Ort herunter, den Sie in Schritt 3 gewählt haben. Es wird ein neuer Ordner innerhalb des aktuellen Ordners erstellt. Dies kann je nach Größe des Repositorys einige Minuten dauern. Sobald der Vorgang abgeschlossen ist, können Sie den Ordner durchsuchen, um seine Struktur anzuzeigen.

Einrichten von Remotes

Richten Sie nach dem Klonen des Repositorys eine Remoteverbindung mit Lesezugriff zum Hauptrepository namens Upstream ein. Remotessind Aliase, die auf Remoterepositories verweisen. Ursprung bezieht sich auf Ihren Fork, und Upstream bezieht sich auf das Produktions-Repository. Git hat das origin-Remote automatisch erstellt, als Sie den clone-Befehl ausgeführt haben. Die Upstream-URL wird genutzt, um Ihr lokales Repository mit den letzten Änderungen anderer Benutzer zu synchronisieren.

Führen Sie die folgenden Befehle entweder in Git Bash oder VS Code Terminal aus.

  1. Ändern Sie das Verzeichnis (cd) in den Repositoryordner, den der clone-Befehl erstellt hat. Beispiel:

    cd repo-name
    
  2. Führen Sie den folgenden Befehl aus, um dem Remote den Namen upstream hinzuzufügen, der auf das Produktions-Repository verweist. Die upstream Repository-URL ist https://github.com/MicrosoftDocs/azure-docs.git und nicht https://github.com/nancydavolio/azure-docs.git.

    git remote add upstream <the clone URL of the main repo>
    

    Beispiel:

    git remote add upstream https://github.com/MicrosoftDocs/azure-docs.git
    
  3. Führen Sie den folgenden Befehl aus, um sicherzustellen, dass Ihre Remotes korrekt sind:

    git remote -v
    

    Beispiel für die Ausgabe:

    origin  https://github.com/nancydavolio/azure-docs.git (fetch)
    origin  https://github.com/nancydavolio/azure-docs.git (push)
    upstream        https://github.com/MicrosoftDocs/azure-docs.git (fetch)
    upstream        https://github.com/MicrosoftDocs/azure-docs.git (push)
    
  4. Wenn Sie einen Fehler gemacht haben, entfernen Sie das Remote, und wiederholen Sie den Schritt, um es hinzuzufügen. Um upstream zu entfernen, führen Sie folgenden Befehl aus:

    git remote remove upstream
    

Nächste Schritte

  • Nachdem Sie ihren lokalen Klon eingerichtet haben, ist es an der Zeit, wichtige Änderungen vorzunehmen.