GitHub Docs での Git の使用

この記事では、ドキュメントリポジトリのトピックブランチを作成し、変更をコミットしてリモートリポジトリにプッシュするプロセスについて説明します。

この記事では、ドキュメントリポジトリをローカルで既にクローンしており、GitHub や codespace ではなく、ローカルコンピューターで変更を行うことを前提としています。詳しくは、「リポジトリをクローンする」を参照してください。

トピックブランチの設定と変更

ローカルブランチをリモートと同期し、マージ競合を回避するために、ドキュメントを操作する際は次の手順に従います。

ターミナルで、現在の作業ディレクトリを、ドキュメントリポジトリを複製した場所に変更します。たとえば次のような点です。
```
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 からのフィードバックを取り入れています"、"請求の構成手順を更新しています - 正確を期すため、@monalisa に CC してください" など。
コミットで issue が解決された場合は、コミット内の issue 番号を参照でき、コミットへのリンクが issue 会話タイムラインに表示されます ("#1234 を解決 - アップグレード前に VM をバックアップするための手順を追加")。

注: 通常、コミットを使用して issue を閉じることはありません。 issue を閉じるには、pull request を開き、説明に "Closes #1234" を追加します。リンクされた issue は、pull request がマージされたときに閉じられます。詳しくは、「Pull RequestをIssueにリンクする」を参照してください。
コミットメッセージは、明確かつ詳細な命令形にします。例: "情報の追加" ではなく、"2FA について概念的な記事を追加する"。
その日の作業が終了するときに、コミットされていない変更をローカルブランチに残さないようにしてください。適切な停止点に到達し、変更をコミットしてプッシュし、作業がリモートリポジトリにバックアップされるようにします。
いくつかのコミットを行った後にのみ、GitHub にプッシュします。コミットのたびにプッシュすると、Slack 上の ops チャネルにノイズが追加され、不要なビルドが実行されます。

マージ競合の解決

異なる変更を含む 2 つのブランチをファイルの同じ部分にマージしようとすると、マージ競合が発生します。ワークフローでは、これは、main をローカルトピックブランチにマージするときに最も頻繁に発生します。

マージ競合を処理するには、次の 2 つの方法があります。

テキストエディターでファイルを編集し、保持する変更を選択します。次に、更新されたファイルをコマンドラインからトピックブランチにコミットします。
「GitHub でのマージコンフリクトを解決する」

ファイルを編集し、変更をコミットしてマージ競合を解決する

コマンドラインで、マージ競合を含むファイルをメモします。
これらのファイルのうち、最初のファイルをテキストエディターで開きます。

ファイル内で、マージ競合マーカーを探します。

 <<<<<<< HEAD
 Here are the changes you've made.
 =====================
 Here are the changes from the main branch.
 >>>>>>> main

どの変更を保持するかを決定し、不要な変更とマージ競合マーカーを削除します。さらに変更を加える必要がある場合は、同時に行うことができます。たとえば、前のコードサンプルに示されている 5 行を次の 1 行に変更できます。
```
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
```

pull request の作成

早い段階で、GitHub で pull request を開くことをお勧めします。レビューする準備ができるまで、pull request を下書きとして作成します。変更をプッシュするたびに、コミットが pull request に追加されます。

注: GitHub の各ページの上部にある [pull request] をクリックすると、作成済みのプルリクエストにすばやくアクセスできます。

詳しくは、「pull request の作成」を参照してください。