jlj-qmk/docs/ja/newbs_best_practices.md

QMK における Git 運用作法

または、如何にして私は心配することをやめて Git を愛することを学んだか。

この文書は、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。 QMK に貢献するプロセスを順を追って説明し、この作業を簡単にするいくつかの方法を詳しく説明します。 その後、意図的に一部を壊してみせて、それらを修正する方法を教えます。

このドキュメントは以下のことを前提としています:

1. あなたは GitHub アカウントがあり、アカウントに qmk_firmware リポジトリをフォーク している。
2. あなたは、環境構築 と QMK の設定 を両方とも完了している。

あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと

QMK の開発では、何がどこで行われているかにかかわらず、master ブランチを最新の状態に保つことを強くお勧めします、しかし master ブランチには絶対に直接コミットしないでください。 代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。

マージの競合 — これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 — の可能性を減らすため master ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。

あなたの master ブランチを更新する

master ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。 これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。

git remote add upstream https://github.com/qmk/qmk_firmware.git

リポジトリが追加されたことを確認するには、git remote -v を実行します。 次のように表示されます。(訳注: upstream は上流という意味です。)

$ git remote -v
origin  https://github.com/<your_username>/qmk_firmware.git (fetch)
origin  https://github.com/<your_username>/qmk_firmware.git (push)
upstream        https://github.com/qmk/qmk_firmware.git (fetch)
upstream        https://github.com/qmk/qmk_firmware.git (push)

これが完了すると、git fetch upstream を実行してリポジトリの更新を確認できます。 このコマンドは upstream というニックネームを持つ QMK リポジトリから、ブランチとタグ — "refs" と総称されます — を取得します。 これで、あなたのフォーク origin のデータを QMK が保持するデータと比較できます。

あなたのフォークの master を更新するには、次を実行します、各行の後にEnterキーを押してください:

git checkout master
git fetch upstream
git pull upstream master
git push origin master

これにより、あなたの master ブランチに切り替わり、QMK リポジトリから 'refs' を取得し、現在の QMK の master ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。

変更を行なう

変更するには、以下を入力して新しいブランチを作成します:

git checkout -b dev_branch
git push --set-upstream origin dev_branch

これにより、dev_branch という名前の新しいブランチが作成され、チェックアウトされ、新しいブランチがあなたのフォークに保存されます。 --set-upstream 引数は、このブランチから git push または git pull を使用するたびに、あなたのフォークと dev_branch ブランチを使用するように git に指示します。 この引数は最初のプッシュでのみ使用する必要があります。 その後、残りの引数なしで git push または git pull を安全に使用できます。

!> git push では、-set-upstream の代わりに -u を使用できます、 -u は --set-upstream のエイリアスです。

ブランチにはほぼ任意の名前を付けることができますが、あなたが行なう変更を表す名前を付けることをお勧めします。

デフォルトでは、git checkout -bは、今チェックアウトされているブランチに基づいて新しいブランチを作成します。 コマンド末尾に既存のブランチの名前を追加指定することにより、チェックアウトされていない既存のブランチを基にして新しいブランチを作成できます:

git checkout -b dev_branch master

これで開発ブランチができたのでテキストエディタを開き必要な変更を加えます。 ブランチに対して多くの小さなコミットを行うことをお勧めします。 そうすることで、問題を引き起こす変更をより簡単に特定し必要に応じて元に戻すことができます。 変更を加えるには、更新が必要なファイルを編集して保存し、Git の ステージングエリア に追加してから、ブランチにコミットします:

git add path/to/updated_file
git commit -m "My commit message."

git addは、変更されたファイルを Git の ステージングエリア に追加します。 これは、Git の「ロードゾーン」です。 これには、git commit によって コミット される変更が含まれており、リポジトリへの変更が保存されます。 変更内容が一目でわかるように、説明的なコミットメッセージを使用します。

!> 多くのファイルを変更したが、すべてのファイルが同じ変更の一部である場合、各ファイルを個別に追加するのではなく、 git add . を使用して、現在のディレクトリにあるすべての変更されたファイルを追加できます。

変更を公開する

最後のステップは、変更をフォークにプッシュすることです。これを行うには、git pushと入力します。 Git は dev_branch の現在の状態をフォークに公開します。

マージの競合の解決

ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。 これは マージの競合 と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。

変更のリベース

リベース は、ある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する Git の方法です。 マージの競合が発生した場合、ブランチをリベースして、ブランチを作成してから現在までに行われた変更を取得できます。

開始するには、次を実行します:

git fetch upstream
git rev-list --left-right --count HEAD...upstream/master

ここに入力された git rev-list コマンドは、現在のブランチと QMK の master ブランチで異なるコミットの数を返します。 最初に git fetch を実行して、upstream リポジトリの現在の状態を表す refs があることを確認します。 入力された git rev-list コマンドの出力は2つの数値を返します:

$ git rev-list --left-right --count HEAD...upstream/master
7       35

最初の数字は、現在のブランチが作成されてからのコミット数を表し、2番目の数字は、現在のブランチが作成されてから upstream/master に対して行われたコミットの数であり、したがって、現在のブランチに記録されていない変更です。

現在のブランチと upstream リポジトリの両方の現在の状態がわかったので、リベース操作を開始できます:

git rebase upstream/master

これにより、Git は現在のブランチのコミットを取り消してから、QMK の master ブランチに対してコミットを再適用します。

$ git rebase upstream/master
First, rewinding head to replay your work on top of it...
Applying: Commit #1
Using index info to reconstruct a base tree...
M       conflicting_file_1.txt
Falling back to patching base and 3-way merge...
Auto-merging conflicting_file_1.txt
CONFLICT (content): Merge conflict in conflicting_file_1.txt
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch' to see the failed patch
Patch failed at 0001 Commit #1

Resolve all conflicts manually, mark them as resolved with
"git add/rm <conflicted_files>", then run "git rebase --continue".
You can instead skip this commit: run "git rebase --skip".
To abort and get back to the state before "git rebase", run "git rebase --abort".

これにより、マージの競合があることがわかり、競合のあるファイルの名前が示されます。 テキストエディタで競合するファイルを開くと、ファイルのどこかに次のような行があります:

<<<<<<< HEAD
<p>For help with any issues, email us at support@webhost.us.</p>
=======
<p>Need help? Email support@webhost.us.</p>
>>>>>>> Commit #1

行 <<<<<<< HEAD はマージ競合の始まりを示し、行 >>>>>>> commit #1 は終了を示し、競合するセクションは ======= で区切られます。 HEAD 側の部分はファイルの QMK master バージョンからのものであり、コミットメッセージでマークされた部分は現在のブランチとコミットからのものです。

Git はファイルの内容ではなく ファイルへの変更 を直接追跡するため、Git がコミットの前にファイル内にあったテキストを見つけられない場合、ファイルの編集方法がわかりません。 ファイルを再編集して、競合を解決します。 変更を加えてから、ファイルを保存します。

<p>Need help? Email support@webhost.us.</p>

そしてコマンド実行:

git add conflicting_file_1.txt
git rebase --continue

Git は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。