В этой статье описывается процесс создания ветви раздела для репозитория документации, фиксации изменений и отправки изменений в удаленный репозиторий.
В статье предполагается, что вы уже клонировали репозиторий документации локально, и вы будете вносить изменения на локальном компьютере, а не на GitHub или в пространстве кода. Дополнительные сведения см. в разделе Клонирование репозитория.
Настройка ветви раздела и внесение изменений
Чтобы обеспечить синхронизацию локальных ветвей с их удаленными и избежать конфликт слияния, выполните следующие действия, как вы работаете над документацией.
-
В терминале измените текущий рабочий каталог на расположение, в котором клонировали репозиторий документации. Например:
cd ~/my-cloned-repos/docs
-
Переключитесь на ветвь по умолчанию:
main
git checkout main
-
Получение последних фиксаций из удаленный репозиторий.
git pull origin main
-
Перейдите к разделу или создайте ветвь раздела.
-
Чтобы запустить новый проект, создайте ветвь раздела из
main
.git checkout -b YOUR-TOPIC-BRANCH
Примечание. Вы можете использовать косую черту вперед в качестве части имени ветви, например, чтобы включить имя пользователя:
git checkout -b my-username/new-codespace-policy
-
Чтобы работать с существующим проектом, перейдите в ветвь раздела и выполните слияние изменений
main
.git checkout YOUR-TOPIC-BRANCH git merge main
Если вы работаете с конфликт слияния, выполните действия, описанные далее в этой статье для разрешения конфликт слияния.
-
-
Откройте предпочитаемый текстовый редактор, измените файлы по мере необходимости, а затем сохраните изменения.
Фиксация и отправка изменений
-
Когда вы будете готовы зафиксировать изменения, откройте терминал и проверьте состояние ветви раздела.
git status
Убедитесь, что вы видите правильный набор изменений.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
-
Выполните этап измененных файлов, чтобы они были готовы к фиксации в ветви раздела.
-
Если вы создали новые файлы или обновили существующие файлы, используйте
git add FILENAME [FILENAME...]
. Например:git add example-new-file.md example-changed-file.md
Это добавляет обновленную версию файлов в промежуточную область Git, из которой можно зафиксировать изменения. Чтобы отменить метку файла, используйте
git reset HEAD FILENAME
. Например,git reset HEAD example-changed-file.md
. -
При удалении файлов используйте
git rm FILENAME [FILENAME...]
. Например:git rm example-deleted-file.md
-
-
Выберите параметр Фиксировать для ваших изменений.
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."
Это фиксирует промежуточные изменения локально. Теперь вы можете отправить эту фиксацию и любые другие незавершенные фиксации в удаленный репозиторий.
Чтобы удалить эту фиксацию, используйте
git reset --soft HEAD~1
. После выполнения этой команды изменения больше не фиксируются, но измененные файлы остаются в промежуточной области. Вы можете внести дальнейшие изменения, а затемadd
иcommit
снова. -
Отправьте изменения в удаленный репозиторий на GitHub.
-
При первом отправке ветви можно добавить ветвь вышестоящего отслеживания. Это позволяет использовать
git pull
иgit push
в этой ветви без дополнительных аргументов.git push --set-upstream origin YOUR-TOPIC-BRANCH
-
Если вы выполнили отправку этой ветви раньше и настроили ветвь отслеживания вышестоящего потока, которую можно использовать:
git push
-
Рекомендации по фиксациям
-
Благоприятствовайте фиксации, содержащие небольшие, ориентированные группы изменений по поводу фиксаций с большими, нефокусными группами изменений, так как это поможет вам писать сообщения о фиксации, которые другие пользователи могут легко понять. Исключением является начальная фиксация для нового проекта или категории. Эти фиксации иногда являются большими, так как они часто вводят голые версии многих статей одновременно, чтобы предоставить организационную схему для последующей работы.
-
Если вы включаете отзывы или хотите обратиться к набору изменений для конкретного человека или команды для проверки, пользователь, @mention чьи предложения вы включаете. Например: "Включение обратной связи от @octocat", или "Обновление действий по настройке выставления счетов — cc @monalisa для точности".
-
Если фиксация устраняет проблему, можно указать номер проблемы в фиксации, а ссылка на фиксацию появится на временной шкале беседы о проблеме: "Адреса #1234 — добавляет шаги по резервному копированию виртуальной машины перед обновлением".
Примечание. Обычно мы не закрываем проблему с помощью фиксации. Чтобы закрыть проблему, откройте запрос на вытягивание и добавьте "Закрыть #1234" в описание. Связанная проблема будет закрыта при слиянии запроса на вытягивание. Дополнительные сведения см. в разделе Связывание запроса на вытягивание с проблемой.
-
Сделать сообщения фиксации понятными, подробными и императивными. Например: "Добавляет концептуальную статью о 2FA", а не "Добавить информацию".
-
Старайтесь не оставлять незафиксированные изменения в локальной ветви после завершения работы в течение дня. Получите хорошую точку остановки и зафиксируйте и отправьте изменения, чтобы ваша работа была создана в удаленный репозиторий.
-
После выполнения нескольких фиксаций только до GitHub. Pushing после каждой фиксации добавляет шум к нашим каналам ops в Slack и приводит к ненужным сборкам для выполнения.
Разрешение конфликтов слияния
При попытке объединить две ветви, содержащие различные изменения в одной части файла, вы получите конфликт слияния. В нашем рабочем процессе это чаще всего происходит при слиянии main
в локальную ветвь раздела.
Существует два способа обработки конфликт слияния:
- Измените файл в текстовом редакторе и выберите, какие изменения следует сохранить. Затем зафиксируйте обновленный файл в ветви раздела из командной строки.
- "Разрешение конфликта слияния в GitHub".
Разрешение конфликт слияния путем редактирования файла и фиксации изменений
-
В командной строке обратите внимание на файлы, содержащие конфликт слияния.
-
Откройте первый из этих файлов в текстовом редакторе.
-
В файле найдите маркеры конфликт слияния.
<<<<<<< HEAD Here are the changes you've made. ===================== Here are the changes from the main branch. >>>>>>> main
-
Определите, какие изменения следует сохранить и удалить нежелательные изменения и маркеры конфликт слияния. Если необходимо внести дальнейшие изменения, это можно сделать одновременно. Например, можно изменить пять строк, показанных в предыдущем примере кода, на одну строку:
Here are the changes you want to use.
Если есть несколько файлов с конфликт слияния, повторите предыдущие шаги, пока не устраните все конфликты.
Примечание. При разрешении конфликт слияния следует применять осторожность. Иногда вы просто принимаете собственные изменения, иногда вы будете использовать изменения вышестоящего потока из
main
ветви, а иногда будете объединять оба набора изменений. Если вы не уверены в лучшем разрешении, будьте осторожны замены изменений из вышестоящей части, так как они, возможно, были сделаны по определенным причинам, о которых вы не знаете. -
В терминале этап файла или файлов, которые вы только что изменили.
git add changed-file-1.md changed-file-2.md
-
Зафиксируйте файлы.
git commit -m "Resolves merge conflicts"
-
Отправьте зафиксированные изменения в удаленный репозиторий на GitHub.
git push
Создание запроса на включение изменений
Рекомендуется открыть запрос на вытягивание на GitHub раньше. Создайте запрос на вытягивание в виде черновика, пока не будете готовы к просмотру. При каждом отправке изменений фиксации будут добавлены в запрос на вытягивание.
Примечание. Вы можете быстро получить доступ к созданным запросам на вытягивание, щелкнув запросы на вытягивание в верхней части каждой страницы на GitHub.
Дополнительные сведения см. в разделе Создание запроса на включение изменений.