diff options
| -rw-r--r-- | docs/ja/_summary.md | 5 | ||||
| -rw-r--r-- | docs/ja/newbs.md | 6 | ||||
| -rw-r--r-- | docs/ja/newbs_git_best_practices.md | 24 | ||||
| -rw-r--r-- | docs/ja/newbs_git_resolving_merge_conflicts.md | 94 | ||||
| -rw-r--r-- | docs/ja/newbs_git_resynchronize_a_branch.md | 88 | ||||
| -rw-r--r-- | docs/ja/newbs_git_using_your_master_branch.md | 101 | ||||
| -rw-r--r-- | docs/ja/newbs_learn_more_resources.md | 8 |
7 files changed, 320 insertions, 6 deletions
diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md index 22db3a7fe1..e5e19ddc80 100644 --- a/docs/ja/_summary.md +++ b/docs/ja/_summary.md @@ -3,7 +3,10 @@ * [初めてのファームウェアの構築](ja/newbs_building_firmware.md) * [ファームウェアのフラッシュ](ja/newbs_flashing.md) * [テストとデバッグ](ja/newbs_testing_debugging.md) - * [Gitのベストプラクティス](ja/newbs_best_practices.md) + * [QMK における Git 運用作法](ja/newbs_git_best_practices.md) + * [あなたのフォークの master ブランチ](ja/newbs_git_using_your_master_branch.md) + * [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md) + * [同期のとれていない git ブランチの再同期](ja/newbs_git_resynchronize_a_branch.md) * [学習リソース](ja/newbs_learn_more_resources.md) * [QMKの基本](ja/README.md) diff --git a/docs/ja/newbs.md b/docs/ja/newbs.md index 54189cce48..84e9732752 100644 --- a/docs/ja/newbs.md +++ b/docs/ja/newbs.md @@ -2,8 +2,8 @@ <!--- grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh - original document: ed0575fc8:docs/newbs.md - git diff ed0575fc8 HEAD docs/newbs.md | cat + original document: adf4acf59:docs/newbs.md + git diff adf4acf59 HEAD docs/newbs.md | cat --> QMK は、メカニカルキーボード用の強力なオープンソースファームウェアです。 @@ -24,7 +24,7 @@ QMK は[多くの趣味のキーボード](http://qmk.fm/keyboards/)をサポー * [オンライン GUI を使用して初めてのファームウェアを構築する](ja/newbs_building_firmware_configurator.md) * [ファームウェアを書きこむ](ja/newbs_flashing.md) * [テストとデバッグ](ja/newbs_testing_debugging.md) -* [QMK における Git 運用作法](ja/newbs_best_practices.md) +* [QMK における Git 運用作法](ja/newbs_git_best_practices.md) * [さらに学ぶための学習リソース](ja/newbs_learn_more_resources.md) このガイドは、これまでソフトウェアをコンパイルしたことがない人を支援することに特化しています。 diff --git a/docs/ja/newbs_git_best_practices.md b/docs/ja/newbs_git_best_practices.md new file mode 100644 index 0000000000..1b0bda1e4e --- /dev/null +++ b/docs/ja/newbs_git_best_practices.md @@ -0,0 +1,24 @@ +# QMK における Git 運用作法 :id=best-git-practices-for-working-with-qmk + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: adf4acf59:docs/newbs_git_best_practices.md + git diff adf4acf59 HEAD docs/newbs_git_best_practices.md | cat +--> + +## または、"如何にして私は心配することをやめて Git を愛することを学んだか。" + +このセクションは、QMK への貢献をスムーズに行なう最もよい方法を初心者に教えることを目的としています。 +QMK に貢献するプロセスを順を追って説明し、この作業を簡単にするいくつかの方法を詳しく説明します。 +その後、意図的に一部を壊してみせて、それらを修正する方法を説明します。 + +このセクションは以下のことを前提としています: + +1. あなたは GitHub アカウントがあり、アカウントに [qmk_firmware リポジトリをフォーク](ja/getting_started_github.md) している。 +2. あなたは、[環境構築](ja/newbs_getting_started.md#set-up-your-environment) と [QMK の設定](ja/newbs_getting_started.md#set-up-qmk) を両方とも完了している。 + +--- + +- パート 1: [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) +- パート 2: [マージの競合の解決](ja/newbs_git_resolving_merge_conflicts.md) +- パート 3: [同期のとれていない git ブランチの再同期](ja/newbs_git_resynchronize_a_branch.md) diff --git a/docs/ja/newbs_git_resolving_merge_conflicts.md b/docs/ja/newbs_git_resolving_merge_conflicts.md new file mode 100644 index 0000000000..f1096e52ed --- /dev/null +++ b/docs/ja/newbs_git_resolving_merge_conflicts.md @@ -0,0 +1,94 @@ +# マージの競合の解決 + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: adf4acf59:docs/newbs_git_resolving_merge_conflicts.md + git diff adf4acf59 HEAD docs/newbs_git_resolving_merge_conflicts.md | cat +--> + +ブランチでの作業の完了に時間がかかる場合、他の人が行った変更が、プルリクエストを開いたときにブランチに加えた変更と競合することがあります。 +これは *マージの競合* と呼ばれ、複数の人が同じファイルの同じ部分を編集すると発生します。 + +?> このドキュメントは [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) で詳述されている概念に基づいています。 +その概念に慣れていない場合は、まずそれを読んでから、ここに戻ってください。 + +## 変更のリベース + +*リベース* は、コミット履歴のある時点で適用された変更を取得し、それらを元に戻し、次に同じ変更を別のポイントに適用する 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 は、競合するファイルへの変更をログに記録し、ブランチのコミットが最後に達するまで適用し続けます。 diff --git a/docs/ja/newbs_git_resynchronize_a_branch.md b/docs/ja/newbs_git_resynchronize_a_branch.md new file mode 100644 index 0000000000..747fe1e610 --- /dev/null +++ b/docs/ja/newbs_git_resynchronize_a_branch.md @@ -0,0 +1,88 @@ +# 同期のとれていない git ブランチの再同期 + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: adf4acf59:docs/newbs_git_resynchronize_a_branch.md + git diff adf4acf59 HEAD docs/newbs_git_resynchronize_a_branch.md | cat +--> + +仮にあなたの `master` ブランチにあなたのコミットを行い、そしてあなたの QMK リポジトリの更新が必要になったとします。 +(フォーク元の) QMKの `master` ブランチをあなたの `master` ブランチに `git pull` することもできますが、GitHub は、あなたのブランチが `qmk:master` より何コミットか先行していると通知します、この状態で QMK にプルリクエストを行う場合、問題が発生する可能性があります。 +(訳注：この通知は、GitHub のあなたのリポジトリの code ペインのブランチ選択メニューの下のあたりで `This branch is 3 commit ahead of qmk:master` という様な文面で表示されています。) + +?> このドキュメントは [あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと](ja/newbs_git_using_your_master_branch.md) で詳述されている概念に基づいています。その概念に慣れていない場合は、まずそれを読んでから、ここに戻ってください。 +(訳注：この文書で言う、「同期のとれていない git ブランチ」とは、master ブランチに関する、この「コミットしない」方針を逸脱して、QMK の master リポジトリに存在しないコミットがあなたのフォークの master ブランチに入っている状態を指します。) + +## あなた自身の `master` ブランチでの変更のバックアップ（オプション） + +救えるものなら自分の行った変更を失いたくはないでしょう。 +あなたの `master` ブランチに既に加えた変更を保存したい場合、最も簡単な方法は、単に「ダーティな」`master` ブランチの複製を作成することです： + +```sh +git branch old_master master +``` + +これで、 `master` ブランチの複製である `old_master` という名前のブランチができました。 + +## あなたのブランチの再同期 + +さあ、`master` ブランチを再同期します。 +この手順では、QMK のリポジトリを git のリモートリポジトリとして設定する必要があります。 +設定済みのリモートリポジトリを確認するには、`git remote -v` を実行し、次のような結果が返されなければなりません。 + +```sh +QMKuser ~/qmk_firmware (master) +$ 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) +``` + +もし、上記のようにならずに以下のように参照されるフォークが、1つだけ表示される場合： + +```sh +QMKuser ~/qmk_firmware (master) +$ git remote -v +origin https://github.com/qmk/qmk_firmware.git (fetch) +origin https://github.com/qmk/qmk_firmware.git (push) +``` + +新しいリモートリポジトリを追加します： + +```sh +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +次に、`origin` リモートリポジトリを、あなた自身のフォークにリダイレクトします： + +```sh +git remote set-url origin https://github.com/<あなたのユーザ名>/qmk_firmware.git +``` + +両方のリモートリポジトリが設定されたので、次を実行して、QMK である `upstream` リポジトリの参照を更新する必要があります。 + +```sh +git fetch upstream +``` + +この時点で、次を実行してあなたの(訳注：master)ブランチを QMK のブランチに再同期します。 +(訳注： 今現在 `master` ブランチがチェックアウトされていなければなりません。 + そうなってなければ、`git checkout master` を先に実行しておく必要があります。) + +```sh +git reset --hard upstream/master +``` + +これらの手順により、あなたのコンピュータ上のリポジトリが更新されますが、あなたの GitHub 上のフォークはまだ同期されていません。 +GitHub 上のフォークを再同期するには、あなたのフォークにプッシュして、ローカルリポジトリに反映されていないリモート変更をオーバーライドするように Git に指示する必要があります。 +これを行うには、次を実行します： + +```sh +git push --force-with-lease +``` + +!> 他のユーザーがコミットを投稿するフォークで `git push --force-with-lease` を**実行しないでください**。これをすると、かれらのコミットが消去されてしまいます。 + +これで、あなたの GitHub フォーク、あなたのローカルファイル、および QMK のリポジトリはすべて同じになりました。 +ここから、[ブランチを使って](ja/newbs_git_using_your_master_branch.md#making-changes)さらに必要な変更を加え、通常どおりそれらを投稿できます。 diff --git a/docs/ja/newbs_git_using_your_master_branch.md b/docs/ja/newbs_git_using_your_master_branch.md new file mode 100644 index 0000000000..41013560d3 --- /dev/null +++ b/docs/ja/newbs_git_using_your_master_branch.md @@ -0,0 +1,101 @@ +# あなたのフォークの master ブランチ: 更新は頻繁に、コミットはしないこと + +<!--- + grep --no-filename "^[ ]*git diff" docs/ja/*.md | sh + original document: adf4acf59:docs/newbs_git_using_your_master_branch.md + git diff adf4acf59 HEAD docs/newbs_git_using_your_master_branch.md | cat +--> + +QMK の開発では、何がどこで行われているかにかかわらず、`master` ブランチを最新の状態に保つことを強くお勧めします、しかし `master` ブランチには***絶対に直接コミットしないでください***。 +代わりに、あなたのすべての変更は開発ブランチで行い、あなたが開発する時にはそのブランチからプルリクエストを発行します。 + +マージの競合 — これは 2人以上のユーザーがファイルの同じ部分をそれぞれ異なる編集をして統合できなくなった状態 — の可能性を減らすため `master` ブランチをなるべく最新の状態に保ち、新しいブランチを作成して新しい開発を開始します。 + +## あなたの master ブランチを更新する + +`master` ブランチを最新の状態に保つには、git のリモートリポジトリとして QMK ファームウェアのリポジトリ(以降、QMK リポジトリ)を追加することをお勧めします。 +これを行うには、Git コマンドラインインターフェイスを開き、次のように入力します。 + +``` +git remote add upstream https://github.com/qmk/qmk_firmware.git +``` + +?> `upstream`(訳注: `upstream` は`上流`という意味です)という名前は任意ですが、一般的な慣習です。 +QMK のリモートリポジトリには、あなたにとって分かりやすい名前を付けることができます。 +Git の `remote` コマンドは、構文 `git remote add <name> <url>` を使用します。 +`<name>` はリモートリポジトリの省略形としてあなたが指定するものです。 +この名前は、`fetch`、`pull`、`push` やそれ以外の多くの Git コマンドで、対象のリモートリポジトリを指定するために使用されます。 + +リポジトリが追加されたことを確認するには、`git remote -v` を実行します。 +次のように表示されます。 + +``` +$ 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` ブランチをコンピュータにダウンロードしてから、あなたのフォークにアップロードします。 + +## 変更を行なう :id=making-changes + +変更するには、以下を入力して新しいブランチを作成します: + +``` +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 -- path/to/file1 path/to/file2 ...` を実行すれば、あなたの望むファイルを追加できます。 + +## 変更を公開する + +最後のステップは、変更をフォークにプッシュすることです。 +これを行うには、`git push`と入力します。 +Gitは、 `dev_branch`の現在の状態をフォークに公開します。 diff --git a/docs/ja/newbs_learn_more_resources.md b/docs/ja/newbs_learn_more_resources.md index 14feb61b32..35101cdce6 100644 --- a/docs/ja/newbs_learn_more_resources.md +++ b/docs/ja/newbs_learn_more_resources.md @@ -14,13 +14,17 @@ * [Great General Tutorial](https://www.codecademy.com/learn/learn-git) * [Git Game To Learn From Examples](https://learngitbranching.js.org/) -* [Git Resources to Learn More About Github](ja/getting_started_github.md) -* [Git Resources Aimed Specifically toward QMK](ja/contributing.md) +* [Git Resources to Learn More About Github](getting_started_github.md) +* [Git Resources Aimed Specifically toward QMK](contributing.md) ### 日本語 _日本語のリソース情報を募集中です。_ +* [Git Game To Learn From Examples(日本語対応有り)](https://learngitbranching.js.org/) +* [QMK で Github を使う方法](ja/getting_started_github.md) +* [貢献方法](ja/contributing.md) + ## コマンドラインに関するリソース: ### 英語 |