Konfigurowanie lokalnego repozytorium Git na potrzeby dokumentacji

W tym artykule opisano kroki prowadzące do skonfigurowania repozytorium Git na komputerze lokalnym na potrzeby współtworzenia dokumentacji firmy Microsoft. Współautorzy mogą korzystać z lokalnie sklonowanego repozytorium, dodając nowe artykuły, wprowadzając istotne zmiany w istniejących artykułach lub zmieniając ich grafikę.

Uruchomisz te jednorazowe działania konfiguracyjne, aby rozpocząć współtworzenia:

• Określ odpowiednie repozytorium.
• Rozwidlenie repozytorium na koncie usługi GitHub.
• Wybierz folder lokalny dla sklonowanych plików.
• Sklonuj repozytorium na komputerze lokalnym.
• Skonfiguruj nadrzędną wartość zdalną.

Ważne

Jeśli wprowadzasz tylko drobne zmiany, nie musisz wykonywać kroków opisanych w tym artykule. Zobacz Edytowanie w przeglądarce , aby dowiedzieć się, jak tworzyć szybkie edycje bez instalowania jakichkolwiek narzędzi.

Omówienie

Aby współtworzyć dokumentację w środowisku Microsoft Learn, możesz lokalnie tworzyć i edytować pliki markdown, klonując odpowiednie repozytorium dokumentacji. Firma Microsoft wymaga rozwidlenia odpowiedniego repozytorium na własnym koncie usługi GitHub, aby mieć uprawnienia do odczytu/zapisu w celu przechowywania proponowanych zmian. Następnie użyjesz żądań ściągnięcia do scalenia zmian w centralnym repozytorium udostępnionym tylko do odczytu.

Repozytorium firmy Microsoft jest określane jako nadrzędne repozytorium. Korzystając z akcji rozwidlenia w interfejsie użytkownika usługi GitHub, użytkownik rozwidli repozytorium Microsoft do własnego konta usługi GitHub. To rozwidlenie jest określane jako Źródło. Przy użyciu klonowania git użytkownik klonuje źródło na komputer lokalny. Na koniec użytkownik używa zdalnego dodawania git do łączenia lokalnego klonu z repozytorium nadrzędnego firmy Microsoft.

Określenie repozytorium

Dokumentacja hostowana w witrynie Microsoft Learn znajduje się w kilku repozytoriach w witrynie GitHub.

1. Jeśli nie masz pewności, w którym repozytorium znajduje się artykuł, odwiedź artykuł przy użyciu przeglądarki internetowej. Wybierz link Edytuj (ikona ołówka) w prawym górnym rogu artykułu.

   

2. Ta akcja powoduje przejście do pliku źródłowego w usłudze GitHub. Nazwa repozytorium jest wyświetlana w lewym górnym rogu strony.

   

   Poniżej przedstawiono kilka popularnych repozytoriów, które są dostępne dla kontrybucjów publicznych:

   • Zawartość społeczności platformy Microsoft Learn https://github.com/MicrosoftDocs/community-content/
   • Dokumentacja platformy Azure https://github.com/MicrosoftDocs/azure-docs
   • Dokumentacja programu SQL Server https://github.com/MicrosoftDocs/sql-docs
   • Dokumentacja programu Visual Studio https://github.com/MicrosoftDocs/visualstudio-docs
   • Dokumentacja platformy .NET https://github.com/dotnet/docs
   • Dokumentacja zestawu .NET SDK platformy Azure https://github.com/azure/azure-docs-sdk-dotnet
   • Dokumentacja programu ConfigMgr https://github.com/MicrosoftDocs/SCCMdocs

Utworzenie rozwidlenia repozytorium

Po zidentyfikowaniu poprawnego repozytorium następnym krokiem jest rozwidlenie repozytorium na własnym koncie usługi GitHub.

Aby utworzyć rozwidlenie repozytorium, należy utworzyć jego kopię na koncie usługi GitHub. Wymagany jest osobisty rozwidlenie, ponieważ wszystkie repozytoria dokumentacji firmy Microsoft zapewniają dostęp tylko do odczytu, ale rozwidlenie zapewnia dostęp do zapisu w celu wprowadzenia zmian. Rozwidlenie umożliwia otwieranie żądania ściągnięcia z rozwidlenia do repozytorium firmy Microsoft.

1. Na stronie GitHub repozytorium głównego wybierz przycisk Rozwidlenie w prawym górnym rogu.

   

2. Na ekranie Tworzenie nowego rozwidlenia upewnij się, że opcja Właściciel jest ustawiona na nazwę użytkownika i że zaznaczono pole wyboru Kopiuj tylko gałąź główną. Opcjonalnie zmień pola Nazwa repozytorium i Opis .

   

Klonowanie repozytorium

Klonowanie oznacza utworzenie kopii repozytorium na komputerze lokalnym.

Ostrzeżenie

1. Nie klonuj repozytoriów lokalnych do folderów synchronizowanych z usługą OneDrive. Podczas wybierania folderu, w którym sklonujesz repozytorium, unikaj folderów synchronizowanych z usługą OneDrive (na przykład folderu Dokumenty ). Usługa OneDrive może powodować niezamierzone konflikty scalania podczas scalania zmian z gałęzią główną. Zamiast tego najlepiej utworzyć krótką ścieżkę pliku na C:\ dysku (na przykład C:\GitHub).

2. Git w systemie Windows: włącz nazwy długich ścieżek. Domyślnie usługa Git dla systemu Windows wyłącza obsługę długich ścieżek plików, co uniemożliwia sklonowanie dowolnego pliku ze ścieżką docelową dłuższą niż 255 znaków. Włącz długie ścieżki plików, aby uniknąć tego problemu, uruchamiając następujące polecenie jako administrator:
   git config --global core.longpaths true

1. GitHub Utwórz folder na komputerze lokalnym. Na przykład C:\GitHub. (Nie klonuj do folderu synchronizacja usługi OneDrive).

2. W przeglądarce przejdź do GitHub.com i zaloguj się.

3. W witrynie GitHub w prawym górnym rogu z listy rozwijanej profilu wybierz pozycję Repozytoria. Zostanie wyświetlona strona repozytoriów z listą rozwidlonych repozytoriów.

4. Wybierz repozytorium, które chcesz sklonować. Zostanie wyświetlona strona repozytorium Rozwidlenia .

   Upewnij się, że jesteś na stronie repozytorium rozwidlenia, a nie na stronie repozytorium produkcyjnego. Możesz potwierdzić, że repozytorium, w którym się znajdujesz, jest rozwidleniem, sprawdzając adres URL: powinien on wyświetlić nazwę użytkownika usługi GitHub, a nie organizację firmy Microsoft (na przykład https://github.com/nancydavolio/azure-docs i NIEhttps://github.com/MicrosoftDocs/azure-docs). Ponadto twoja nazwa zostanie wyświetlona w lewym górnym rogu i zobaczysz notatkę z napisem rozwidlenie, po którym następuje nazwa repozytorium głównego.

   

5. Wybierz kartę <> Kod w lewym górnym rogu strony.

6. Po prawej stronie z listy rozwijanej Kod skopiuj adres URL w obszarze opcji HTTPS .

   

Ważne

Skopiowano adres URL klonowania za pośrednictwem interfejsu użytkownika usługi GitHub. Pozostałe kroki należy wykonać w terminalu programu VS Code.

Aby sklonować z programu Visual Studio Code

1. Otwórz Visual Studio Code.

2. Z górnego menu nawigacji wybierz pozycję Widok , a następnie wybierz pozycję Terminal. Widok terminalu zostanie wyświetlony w dolnej części ekranu programu Visual Studio Code.

3. W widoku terminalu uruchom polecenie , aby zmienić katalog (cd) na GitHub folder utworzony dla repozytoriów na dysku w kroku 1 w sekcji Klonowanie repozytorium.

   Przykład:

    cd C:\GitHub
   

   Jeśli wystąpi błąd, może być konieczne zmiana katalogu po jednym folderze naraz.

4. Uruchom następujące polecenie, aby sklonować repozytorium:

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

   Na przykład:

   git clone https://github.com/nancydavolio/azure-docs.git
   

5. Po wyświetleniu monitu o uwierzytelnienie za pośrednictwem przeglądarki wybierz przycisk "Zaloguj się przy użyciu przeglądarki" i ukończ proces. Pamiętaj, aby pobrać najnowszą wersję narzędzia Git, która obsługuje uwierzytelnianie za pośrednictwem funkcji przeglądarki. Jeśli zdecydujesz się użyć osobistego tokenu dostępu usługi GitHub, możesz wygenerować jeden z następujących instrukcji: Tworzenie osobistego tokenu dostępu.

   Polecenie klonowania pobiera pliki repozytorium z rozwidlenia do nowego folderu w lokalizacji wybranej w kroku 3. Nowy folder zostaje utworzony w bieżącym folderze. Może to potrwać kilka minut w zależności od rozmiaru repozytorium. Możesz eksplorować folder, aby zobaczyć strukturę po zakończeniu.

Konfigurowanie zdalnych

Po sklonowaniu repozytorium skonfiguruj połączenie zdalne z repozytorium głównym przeznaczone tylko do odczytu, o nazwie upstream. Zdalne to aliasy odwołujące się do repozytoriów zdalnych. Źródło odwołuje się do rozwidlenia, a nadrzędny element odwołuje się do repozytorium produkcyjnego. Usługa Git automatycznie utworzyła origin zdalne polecenie po uruchomieniu clone polecenia . Z adresu URL połączenia nadrzędnego będziesz korzystać w celu synchronizowania Twojego lokalnego repozytorium z najnowszymi zmianami wykonywanymi przez innych użytkowników.

Uruchom następujące polecenia w terminalu git Bash lub VS Code.

1. Zmień katalog (cd) na folder repozytorium utworzony przez clone polecenie . Na przykład:

   cd repo-name
   

2. Uruchom następujące polecenie, aby dodać zdalną nazwę upstream wskazującą repozytorium produkcyjne. Na przykład upstream adres URL repozytorium to https://github.com/MicrosoftDocs/azure-docs.git zamiast https://github.com/nancydavolio/azure-docs.git.

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

   Na przykład:

   git remote add upstream https://github.com/MicrosoftDocs/azure-docs.git
   

3. Uruchom następujące polecenie, aby upewnić się, że zdalne elementy są poprawne:

   git remote -v
   

   Przykład danych wyjściowych:

   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. Jeśli popełnisz błąd, usuń zdalny i powtórz krok, aby go dodać. Aby usunąć upstreampolecenie , uruchom polecenie:

   git remote remove upstream
   

Następne kroki

• Po skonfigurowaniu klonu lokalnego nadszedł czas na wprowadzenie istotnych zmian.