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ę.

Aby rozpocząć współtworzenie, należy wykonać poniższe jednorazowe czynności konfiguracyjne.

• Określenie odpowiedniego repozytorium
• Utworzenie rozwidlenia repozytorium do swojego konta w usłudze GitHub
• Wybranie lokalnego folderu na sklonowane pliki
• Sklonowanie repozytorium na komputerze lokalnym
• Skonfigurowanie wartości zdalnego połączenia nadrzędnego

Ważne

Jeśli wprowadzasz jedynie drobne zmiany do artykułu, nie musisz wykonywać kroków opisanych w tym artykule. Możesz przejść bezpośrednio do przepływu pracy dla szybkich zmian.

Omówienie

W celu współtworzenia zawartości witryny dokumentacji firmy Microsoft można lokalnie tworzyć i edytować pliki Markdown poprzez klonowanie odpowiedniego repozytorium dokumentacji. Firma Microsoft wymaga wykonania rozwidlenia odpowiedniego repozytorium do konta użytkownika w usłudze GitHub, dzięki czemu użytkownik będzie miał uprawnienia do odczytu i zapisu umożliwiające przechowywanie proponowanych zmian. W dalszej kolejności użytkownik stosuje żądania ściągnięcia w celu scalenia zmian w centralnym repozytorium udostępnionym tylko do odczytu.

Określenie repozytorium

Dokumentacja hostowana w witrynie Microsoft Learn znajduje się w kilku różnych repozytoriach w github.com.

1. Jeśli nie masz pewności, którego repozytorium użyć, odwiedź artykuł w witrynie Microsoft Learn przy użyciu przeglądarki internetowej. Wybierz link Edytuj (ikona ołówka) w prawej górnej części tego artykułu.

   

2. Ten link umożliwia przejście do lokalizacji w witrynie github.com, w której we właściwym repozytorium znajduje się odpowiedni plik Markdown. Zapisz adres URL, aby określić nazwę repozytorium.

   

   Na przykład na potrzeby publicznego dodawania zawartości dostępne są następujące popularne repozytoria:

   • 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 pakietu Azure .Net SDK https://github.com/azure/azure-docs-sdk-dotnet
   • Dokumentacja programu ConfigMgr https://github.com/MicrosoftDocs/SCCMdocs

Utworzenie rozwidlenia repozytorium

Korzystając z odpowiedniego repozytorium, utwórz rozwidlenie repozytorium do własnego konta usługi GitHub przy użyciu witryny usługi GitHub.

Wymagane jest osobiste rozwidlenie, ponieważ wszystkie repozytoria główne dokumentacji oferują dostęp tylko do odczytu. W celu dokonania zmian musisz przesłać do repozytorium głównego żądanie ściągnięcia ze swojego rozwidlenia. Aby wykonać ten proces, najpierw musisz dysponować swoją własną kopią repozytorium, do której masz prawa do zapisu. Do tego służy rozwidlenie GitHub.

1. Przejdź do strony GitHub repozytorium głównego i naciśnij przycisk Fork (Rozwidlenie) w prawym górnym rogu.

   

2. W odpowiedzi na pytanie o miejsce utworzenia rozwidlenia repozytorium wskaż kafelek swojego konta usługi GitHub. Spowoduje to utworzenie rozwidlenia, czyli kopii repozytorium w ramach Twojego konta usługi GitHub.

Wybieranie folderu lokalnego

Utwórz folder lokalny, w którym będzie przechowywana lokalna kopia repozytorium. Niektóre repozytoria mogą być duże, nawet do 5 GB, na przykład azure-docs. Wybierz lokalizację z dostępnym miejscem na dysku.

1. Wybierz nazwę folderu, która będzie łatwa do zapamiętania i wpisywania. Na przykład rozważ użycie folderu głównego C:\docs\ lub utwórz folder w swoim katalogu profilu użytkownika ~/Documents/docs/.

   Ważne

   Nie należy wybierać lokalnej ścieżki folderu zagnieżdżonej wewnątrz lokalizacji innego folderu repozytorium Git. Chociaż dopuszczalne jest przechowywanie folderów sklonowanych usługi Git obok siebie, zagnieżdżanie folderów Git jeden wewnątrz drugiego powoduje błędy podczas śledzenia plików.

2. Uruchamianie powłoki Git Bash

   

   Domyślną lokalizacją, w której uruchamiana jest powłoka Git Bash, jest zwykle katalog macierzysty (~) lub /c/users/<Windows-user-account>/ w systemie operacyjnym Windows.

   Aby określić bieżący katalog, wpisz ciąg pwd w wierszu polecenia $.

3. Zmień katalog (za pomocą polecenia cd) na folder utworzony na potrzeby lokalnego hostowania repozytorium. Pamiętaj, że powłoka Git Bash używa dla ścieżek folderów konwencji z ukośnikami zamiast ukośników odwrotnych.

   Na przykład cd /c/docs/ lub cd ~/Documents/docs/

Tworzenie lokalnego klona

Korzystając z powłoki Git Bash, przygotuj uruchomienie polecenia clone, aby ściągnąć kopię repozytorium (rozwidlenie) na Twoje urządzenie w bieżącym katalogu.

Uwierzytelnianie przy użyciu programu Git Credential Manager

Jeśli została zainstalowana najnowsza wersja usługi Git dla systemu Windows i została zaakceptowana instalacja domyślna, program Git Credential Manager jest domyślnie włączony. Program Git Credential Manager bardzo ułatwia uwierzytelnianie, ponieważ likwiduje potrzebę odwoływania się do osobistego tokenu dostępu podczas kolejnego ustanawiania uwierzytelnionych połączeń i dostępów zdalnych w usłudze GitHub.

1. Uruchom polecenie clone, podając nazwę repozytorium. Klonowanie pobiera (klonuje) repozytorium rozwidlone na komputer lokalny.

   Porada

   Adres URL Twojego rozwidlenia w usłudze GitHub potrzebny do polecenia klonowania możesz uzyskać za pośrednictwem przycisku Clone or download (Klonuj lub pobierz) interfejsu użytkownika usługi GitHub:

   

   Upewnij się, że podczas procesu klonowania została określona ścieżka do Twojego rozwidlenia, a nie do repozytorium głównego, z którego zostało utworzone rozwidlenie. W przeciwnym razie nie będziesz mieć możliwości współtworzenia zmian. Twoje rozwidlenie jest przywoływane za pośrednictwem Twojego osobistego konta użytkownika usługi GitHub, na przykład github.com/<github-username>/<repo>.

   git clone https://github.com/<github-username>/<repo>.git
   

   Twoje polecenie klonowania powinno wyglądać podobnie do tego:

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

2. Po wyświetleniu monitu wprowadź swoje poświadczenia usługi GitHub.

   

3. Po wyświetleniu monitu wprowadź kod uwierzytelniania dwuetapowego.

   

   Uwaga

   Twoje poświadczenia zostaną zapisane i będą używane do uwierzytelniania przyszłych żądań kierowanych do usługi GitHub. To uwierzytelnianie należy wykonać jednokrotnie dla danego komputera.

4. Polecenie clone uruchamia i pobiera kopię plików repozytorium z rozwidlenia do nowego folderu na dysku lokalnym. Nowy folder zostaje utworzony w bieżącym folderze. Może to potrwać kilka minut w zależności od rozmiaru repozytorium. Po zakończeniu możesz eksplorować folder, aby wyświetlić jego strukturę.

Konfigurowanie zdalnego połączenia nadrzędnego

Po sklonowaniu repozytorium skonfiguruj połączenie zdalne z repozytorium głównym przeznaczone tylko do odczytu, o nazwie upstream. 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. Polecenie git remote służy do ustawiania wartości konfiguracji. Polecenie fetch służy do odświeżania informacji o gałęzi z repozytorium nadrzędnego.

1. Jeśli korzystasz z programu Git Credential Manager, użyj poniższych poleceń. Zastąp elementy zastępcze <repo> i <organization>.

   cd <repo>
   git remote add upstream https://github.com/<organization>/<repo>.git
   git fetch upstream
   

2. Wyświetl skonfigurowane wartości i potwierdź, że adresy URL są poprawne. Upewnij się, że adresy URL źródła (origin) wskazują na Twoje osobiste rozwidlenie. Upewnij się, że adresy URL repozytorium upstream wskazują repozytorium główne, takie jak MicrosoftDocs lub Azure.

   git remote -v 
   

   Poniżej pokazany jest przykład danych wyjściowych połączenia zdalnego. Fikcyjne konto usługi git o nazwie MyGitAccount jest konfigurowane przy użyciu osobistego tokenu dostępu w celu uzyskania dostępu do repozytorium azure-docs:

   origin  https://github.com/MyGitAccount/azure-docs.git (fetch)
   origin  https://github.com/MyGitAccount/azure-docs.git(push)
   upstream        https://github.com/MicrosoftDocs/azure-docs.git (fetch)
   upstream        https://github.com/MicrosoftDocs/azure-docs.git (push)
   

3. W przypadku popełnienia błędu możesz usunąć wartość połączenia zdalnego. Aby usunąć wartość połączenia nadrzędnego, uruchom polecenie git remote remove upstream.

Kolejne kroki

• Aby dowiedzieć się więcej na temat dodawania i aktualizowania zawartości, przejdź do strony GitHub contribution workflows (Przepływy pracy dotyczące współautorstwa w usłudze GitHub).