Настройка локального репозитория Git для документации

В этой статье показано, как настроить репозиторий Git на локальном компьютере для создания документации по продуктам Майкрософт. Добавлять новые статьи, вносить значительные правки в существующие и изменять графическое оформление можно при помощи локально клонированного репозитория.

Чтобы начать участие, выполните следующие однократные действия по настройке:

• Определите соответствующий репозиторий.
• Репозиторий, скопированный в учетную запись GitHub.
• Выберите локальную папку для клонированных файлов.
• Клонируйте репозиторий на локальный компьютер.
• Настройте вышестоящее удаленное значение.

Внимание

Если вы вносите только незначительные изменения, вам не нужно выполнить действия, описанные в этой статье. См. статью "Изменить" в браузере , чтобы узнать, как быстро изменять без установки средств.

Обзор

Чтобы внести свой вклад в документацию в Microsoft Learn, вы можете создавать и изменять файлы Markdown локально, клонируя соответствующий репозиторий документации. Корпорация Майкрософт требует, чтобы вы вилировали соответствующий репозиторий в собственную учетную запись GitHub, чтобы у вас были разрешения на чтение и запись для хранения предлагаемых изменений. Затем вы используете запросы на вытягивание (PR) для объединения изменений в центральный общий репозиторий только для чтения.

Репозиторий Майкрософт называется вышестоящим репозиторием. Используя действие вилки в пользовательском интерфейсе GitHub, пользователь перекваливали репозиторий Майкрософт в собственную учетную запись GitHub. Этот вилки называется источником. Используя клон git, пользователь клонирует источник на локальный компьютер. Наконец, пользователь использует удаленное добавление git для подключения локального клона обратно к вышестоящему репозиторию Майкрософт.

Определение репозитория

Документация, размещенная в Microsoft Learn , находится в нескольких репозиториях на GitHub.

1. Если вы не уверены, в каком репозитории находится статья, посетите статью с помощью веб-браузера. Щелкните ссылку "Изменить " (значок карандаша) в правом верхнем углу статьи.

   

2. Это действие принимает вас в исходный файл на GitHub. Имя репозитория отображается в левом верхнем углу страницы.

   

   Ниже приведены некоторые популярные репозитории, доступные для публичный вклад:

   • Содержимое сообщества Microsoft Learn https://github.com/MicrosoftDocs/community-content/
   • Документация по Azure https://github.com/MicrosoftDocs/azure-docs
   • Документация по SQL Server https://github.com/MicrosoftDocs/sql-docs
   • Документация по Visual Studio https://github.com/MicrosoftDocs/visualstudio-docs
   • Документация по .NET https://github.com/dotnet/docs
   • Документация по пакету SDK для Azure .NET https://github.com/azure/azure-docs-sdk-dotnet
   • Документация по Configuration Manager https://github.com/MicrosoftDocs/SCCMdocs

Создание вилки репозитория

После определения правильного репозитория следующий шаг — вилку репозитория в собственную учетную запись GitHub.

Создание копии репозитория в учетной записи GitHub. Требуется личный вилок, так как все репозитории документации Майкрософт предоставляют доступ только для чтения, но вилка предоставляет доступ на запись для внесения изменений. Вилка позволяет открывать PR из вилки в репозиторий Майкрософт.

1. На странице GitHub основного репозитория нажмите кнопку "Вилку " в правом верхнем углу.

   

2. На экране "Создание нового вилки" убедитесь, что для владельца задано имя пользователя, и установлен флажок "Копировать только основную ветвь". При необходимости измените имя репозитория и поля описания .

   

Клонирование репозитория

Клонирование означает создание копии репозитория на локальном компьютере.

Предупреждение

1. НЕ клонируйте локальные репозитории в папки, синхронизированные с OneDrive. При выборе папки, в которую вы клонируете репозиторий, избегайте синхронизации папок с OneDrive (например, папка "Документы "). OneDrive может вызвать непреднамеренные конфликт слияния при слиянии изменений обратно в основную ветвь. Вместо этого рекомендуется создать короткий путь к файлу на C:\ диске (например, C:\GitHub).

2. Git в Windows. Включение длинных имен путей. По умолчанию Git для Windows отключает поддержку длинных путей к файлам, что предотвращает клонирование любого файла с целевым путем с длиной больше 255 символов. Включите длинные пути к файлам, чтобы избежать этой проблемы, выполнив следующую команду от имени администратора:
   git config --global core.longpaths true

1. Создайте папку GitHub на локальном компьютере. Например, C:\GitHub. (Не клонируйте приложение синхронизации OneDrive папку.)

2. В браузере перейдите к GitHub.com и войдите в систему.

3. В GitHub справа в раскрывающемся списке профиля выберите репозитории. Откроется страница репозиториев со списком вилированных репозиториев.

4. Выберите репозиторий, который требуется клонировать. Откроется страница репозитория вашего вилки.

   Убедитесь, что вы находитесь на странице репозитория для вилки, а не на странице рабочего репозитория. Вы можете убедиться, что репозиторий, на который вы работаете, является вилкой, проверив URL-адрес: он должен отображать имя пользователя GitHub, а не организацию Майкрософт (например, https://github.com/nancydavolio/azure-docs а НЕhttps://github.com/MicrosoftDocs/azure-docs). Кроме того, вы увидите свое имя в левом верхнем углу, и вы увидите заметку, которая отображается вилкой, за которой следует имя основного репозитория.

   

5. Выберите вкладку "Код" <> в левом верхнем углу страницы.

6. В раскрывающемся списке "Код" в раскрывающемся списке "Код" скопируйте URL-адрес в параметре HTTPS.

   

Внимание

Вы скопировали URL-адрес клона через Пользовательский интерфейс GitHub. Остальные шаги должны выполняться в терминале VS Code.

Клонирование из Visual Studio Code

1. Откройте Visual Studio Code.

2. В верхнем меню навигации выберите "Вид " и выберите "Терминал". Представление терминала отображается в нижней части экрана Visual Studio Code.

3. В представлении терминала выполните команду, чтобы изменить каталог (cd) на GitHub папку, созданную для репозиториев на диске на шаге 1 в разделе клонирования репозитория.

   Пример:

    cd C:\GitHub
   

   При возникновении ошибки может потребоваться изменить каталог по одной папке за раз.

4. Выполните следующую команду, чтобы клонировать репозиторий:

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

   Например:

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

5. При появлении запроса на проверку подлинности через браузер нажмите кнопку "Войти с помощью браузера" и завершите процесс. Не забудьте скачать последнюю версию Git, которая поддерживает проверку подлинности с помощью функций браузера. Если вы решили использовать личный маркер доступа GitHub, можно создать один из следующих инструкций. Создайте личный маркер доступа.

   Команда клонирования скачивает файлы репозитория из вилки в новую папку в расположении, выбранном на шаге 3. Новая папка создается в текущей папке. В зависимости от размера репозитория этот процесс может занять несколько минут. Вы можете просмотреть папку, чтобы увидеть структуру после завершения.

Настройка удаленных служб

После клонирования репозитория следует установить удаленное подключение только для чтения, называемое вышестоящим, к основному репозиторию. Удаленные — это псевдонимы , ссылающиеся на удаленные репозитории. Источник относится к вашему вилку и вышестоящему репозиторию относится к рабочему репозиторию. Git автоматически создал удаленный origin при выполнении clone команды. С помощью URL-адреса вышестоящего подключения вы сможете обеспечить синхронизацию вашего локального репозитория с последними правками, внесенными другими участниками.

Выполните следующие команды в терминале Git Bash или VS Code.

1. Измените каталог (cd) в папку репозитория, созданную командой clone . Например:

   cd repo-name
   

2. Выполните следующую команду, чтобы добавить удаленное имя upstream , указывающее на рабочий репозиторий. Например, URL-адрес https://github.com/MicrosoftDocs/azure-docs.git репозитория upstream не https://github.com/nancydavolio/azure-docs.gitявляется.

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

   Например:

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

3. Выполните следующую команду, чтобы убедиться, что удаленные элементы правильно:

   git remote -v
   

   Пример выходных данных:

   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. Если вы сделали ошибку, удалите удаленный и повторите шаг, чтобы добавить его. Чтобы удалить upstream, выполните команду:

   git remote remove upstream
   

Следующие шаги

• Теперь, когда вы настроили локальный клон, пришло время внести основные изменения.