一人でもmainに直接コミットしない — PRとレビュー

PRとレビュー。コードの差分書類と確認チェック、分岐して合流する履歴線。

roadmap.sh のどこをやっているか

Frontend/Backend/DevOps›Version Control / Collaboration
  • GitHub / GitLab / Bitbucket とプルリクエスト
  • コードレビューとドキュメントの置き場

この記事は、上の項目を実際に手を動かして確かめる回です。

前回: 同じボタンが3種類できる理由 — デザインシステム 作業場所はVMの中(Ubuntu Server)です。GitHubに上げた ~/server と、前に作ったCIがそのまま動いている状態から始めます。ブランチ保護の設定だけ、Windows側のブラウザを使います。

ここまで、コードはずっと main に直接コミットしてきました。

書いて、git add して、git commit して、git push。速いし、迷うところがありません。一人なので、誰の邪魔にもなりません。

問題は、速さではなく「戻せなくなる瞬間」です。

たとえば、こういう2時間です。認証まわりを直しはじめて、途中でログの出し方が気に入らなくなって直して、ついでにインデントを揃えて、その途中でバグを見つけて直して、main に3回 push しました。そして、動かなくなりました。

このとき、あなたが知りたいのは「どの変更が壊したのか」です。ところが main の履歴には、認証・ログ・整形・バグ修正が混ざった3つのコミットしか残っていません。1つ戻すと、関係ない修正まで消えます。全部戻すと、2時間が消えます。

そして、いま動いているサービスは main から動いています。 壊れたものが、そのまま本番の位置にあります。

これは人数の問題ではありません。「作業中のものと、動いてよいものが同じ場所にある」という置き方の問題です。だから一人でも直せます。

この回でやるのは、精神論ではありません。ブランチを切って、PRを作って、自分でレビューして、マージする、という一周を実際に回します。そして、CIが落ちたPRは自分でもマージできないように、機械の側に鍵をかけます。

対象レベル: 中級 / 区分: 必修

目次

この記事でわかること

  • main に直接コミットする問題は「速さ」ではなく「作業中のものが本番の位置にある」こと
  • PRは他人に見せるための機能ではないこと。一人なら、未来の自分に向けたチェックリストになる
  • 自分のプルリクエストは、自分でApproveできないこと。だから一人のときは「レビュー必須」を設定してはいけない
  • レビューで見るのは「好み」ではないこと。見るべきものは5つに絞れる
  • ブランチ戦略は GitHub Flow で十分で、Git Flow は一人には重すぎること

この記事でやること

  1. ブランチを切って変更し、push して、プルリクエストを作る(gh かブラウザ)
  2. 自分のPRを自分でレビューする。見るところをチェックリストにして、実際に指摘を書く
  3. ブランチ保護を入れて、CIが落ちたPRはマージできない状態にする
  4. わざとCIを落として、マージボタンが押せなくなることを確かめる
  5. コンフリクトをわざと起こして、直す。そして中止の仕方も覚える

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
ブランチ履歴の枝。main から分かれて作業し、あとで合流させる
プルリクエスト(PR)「この枝を main に合流させたい」という申請。GitHub の機能で、Git そのものの機能ではない
マージ枝を合流させること
コンフリクト合流させようとしたとき、同じ行が両側で違う内容に変わっていて機械が決められない状態
ブランチ保護 / ルールセット「この条件を満たすまで main に入れさせない」という GitHub 側の鍵
ステータスチェックPRに対して走る自動チェック。前回作ったCIがこれになる
レビュー変更を読んで、マージしてよいかを判断すること。Approve / Comment / Request changes の3種類がある
ghGitHub 公式のコマンドラインツール。ブラウザを開かずにPRを作れる

① main に直接コミットすると、何が戻せなくなるのか

まず、いまの状態を見てください。

bash
$ cd ~/server
$ git branch
* main

枝が1本しかありません。 * が「いまここにいる」という印です。

この状態の何が困るのかを、言葉ではなく履歴で見ます。

bash
$ git log --oneline -5

コミットが並びます。ここで、そのうち1つだけを取り消したいと考えてみてください。

bash
$ git revert <取り消したいコミットID>

revert は「そのコミットと逆の変更を、新しいコミットとして足す」コマンドです。履歴を消さずに打ち消すので、push 済みでも安全です。

問題は、コミットの中身が混ざっているときです。 1つのコミットに「認証の修正」と「インデント揃え」が両方入っていると、revert は両方を打ち消します。片方だけ残すことはできません。混ぜた時点で、分けて戻す手段が消えています。

もうひとつ、もっと直接的な困りごとがあります。

bash
$ git status

途中まで書いたコードが ~/server にある状態で、別の急ぎの修正が必要になったとします。 いまのやり方だと、選べる道は「書きかけを捨てる」か「書きかけごと push する」しかありません。

ブランチは、この2つを同時に解きます。

main に直接ブランチを使う
作業中のコードの置き場所main(=本番と同じ枝)別の枝
1つだけ戻したい混ざっていると無理枝ごと捨てれば消える
途中で別件が来た捨てるか、混ぜるか枝を切り替えるだけ
壊れたコードが main に入る止める人がいないCIとブランチ保護が止める

「一人だから要らない」ではありません。「一人だから、止めてくれる人が誰もいない」のです。

② ブランチを切る

まず、main を最新にします。

bash
$ cd ~/server
$ git switch main
$ git pull

そのうえで、枝を作ります。

bash
$ git switch -c feat/health-endpoint
Switched to a new branch 'feat/health-endpoint'

switch -c の -c は create です。「作って、そこに移る」を一度にやります。

git checkout -b と同じです。 checkout は「ブランチ切り替え」と「ファイルを元に戻す」という別の仕事を1つのコマンドが持っていたので、Git 2.23 で switch(枝の切り替え)と restore(ファイルを戻す)に分けられました。古い記事は checkout で書かれていますが、どちらも動きます。

確かめます。

bash
$ git branch
* feat/health-endpoint
  main

枝の名前の付け方に決まりはありませんが、あとで一覧を見たときに何の枝か分かるようにします。この記事では次の形を使います。

接頭辞何の枝か
feat/機能を足す
fix/不具合を直す
docs/ドキュメントだけ
chore/設定・整理など、動作が変わらないもの

③ 変更して、push する

枝の中で、小さな変更を1つだけします。 例として「サーバーが生きているかを返すエンドポイント」を足します。

~/server の中身は人によって違うので、ここは自分のコードに合わせてください。 Express なら、ルーティングを書いている場所に1つ足すだけです。

bash
$ nano ~/server/src/app.js
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

変更を確かめます。

bash
$ git diff

足した行だけが出てくれば正解です。 ここで関係ない行が大量に出てきたら、整形が混ざっています。(対処は⑧に書きます)

コミットして、枝ごと push します。

bash
$ git add src/app.js
$ git commit -m "feat: 死活確認用の /health を追加"
$ git push -u origin feat/health-endpoint

-u(--set-upstream)は「この枝の push 先はここ」と覚えさせる指定です。次からは git push だけで済みます。

remote: Create a pull request for 'feat/health-endpoint' on GitHub by visiting:
remote:      https://github.com/<ユーザー名>/server/pull/new/feat/health-endpoint

GitHub が「PRを作れますよ」とURLを返してきます。 これが次の手順です。

ここで main は1文字も変わっていません。 ブラウザで main を見ると、/health はまだありません。作業中のものが、本番の位置に無い状態が作れました。

④ プルリクエストを作る

2つの道があります。どちらでも同じものができます。

道A: ブラウザで作る

上のURLをWindows側のブラウザで開くと、PR作成画面が出ます。タイトルと説明を書いて「Create pull request」を押すだけです。

[スクリーンショット: 01_pr作成画面.png] GitHub のプルリクエスト作成画面を撮ってください。タイトル欄と説明欄、下に差分が出ている状態です。

道B: VMの中から gh で作る

ブラウザに切り替えずに済むので、慣れるとこちらが速いです。

まず入っているか確認します。

bash
$ gh --version

command not found なら入れます。Ubuntu の標準リポジトリにも gh がありますが、版が古いことがあります。 まずこちらを見てください。

bash
$ apt-cache policy gh

候補が出てくるなら、それで十分です。

bash
$ sudo apt install -y gh

出てこない(Unable to locate package)場合は、GitHub 公式の手順に従います。 最新の手順は公式の案内にあります。外部のリポジトリを足す操作なので、コピペで済ませず、リンク先の手順をそのまま使ってください。

入ったら、ログインします。

bash
$ gh auth login

対話で聞かれます。GitHub.com → SSH → 既存の鍵を使う、を選んでください。 前にGitHubに登録した鍵がそのまま使えます。ブラウザでのワンタイムコード入力を求められるので、画面の指示どおりに進めます。

確認します。

bash
$ gh auth status

PRを作ります。

bash
$ cd ~/server
$ gh pr create --base main --title "feat: 死活確認用の /health を追加" --body "監視から叩くための、依存を一切見ない軽いエンドポイントを足しました。DBやRedisには触っていません。"
https://github.com/<ユーザー名>/server/pull/1

URLが返ってきたら成功です。

中身をVMの中から見られます。

bash
$ gh pr view
$ gh pr diff

--body を空にしないでください。 一人でも、3週間後の自分は他人です。「なぜこれを足したのか」は、コードの差分には書いてありません。

⑤ 自分でレビューする — 見るところを5つに絞る

ここが、この記事で一番大事なところです。

PRの Files changed タブを開きます。そして、自分が書いたコードを、他人が書いたものとして読みます。

[スクリーンショット: 02_差分レビュー.png] PRの Files changed タブで、行にコメントを付けている画面を撮ってください。

「よく見る」では何も見えません。見る順番を決めます。

レビューのチェックリスト

#見ること具体的に何を確かめるか
1動くかCIは緑か。手元でも動かしたか。エラーのときの分岐も通したか
2読めるか名前で意味が分かるか。説明のコメントが要る箇所は、コードのほうを直せないか
3戻せるかこれだけを revert して元に戻るか。DBの構造変更やデータ移行が混ざっていないか
4秘密が入っていないかAPIキー・パスワード・トークン・自分のIPやドメイン。.env が差分に出ていないか
5テストがあるかこの変更が壊れたとき、CIが気づくか。気づかないなら、テストが無い

上から順に見ます。1が×なら、2以降は読む価値がありません。

実際に、いまのPRで4番を機械的に確かめます。

bash
$ git diff main --stat
 src/app.js | 4 ++++
 1 file changed, 4 insertions(+)

変更したファイルが1つだけです。 ここに .env や id_rsa が出てきたら、その時点で止めます。(秘密の扱いは別の回でやりました)

中身の文字列も見ます。

bash
$ git diff main | grep -inE "password|secret|token|api[-_]?key" 

何も出ないのが正解です。 出たら、それが変数名なのか、値そのものなのかを必ず目で確かめます。

指摘してよいこと、してはいけないこと

レビューが嫌われる一番の理由は「好みを指摘されること」です。

指摘してよい指摘してはいけない
このエラーのとき落ちますクォートはシングルのほうが好きです
この名前だと、中身と逆に読めますここは3行でなく1行で書けます(動作が同じなら)
この変更を戻すと、DBだけ戻りませんインデントが揃っていません
ここ、テストが無いので次に壊れても気づけません私ならこう書きます

右の列は、人ではなく機械の仕事です。 インデントや引用符はESLintとPrettierが決めます。機械が決められることを人が指摘すると、レビューは「意見の言い合い」になります。

一人のときも同じです。 未来の自分に「好み」を書き残しても、判断材料になりません。

自分のPRは、自分でApproveできない

やってみると分かります。

bash
$ gh pr review --approve
GraphQL: Can not approve your own pull request (addPullRequestReview)

GitHub がそういう作りです。 これは制限ではなく、「承認は、書いた人以外がするもの」という考え方です。

なので、一人のときのレビューはこうします。

bash
$ gh pr comment --body "セルフレビュー: 依存なし・秘密なし・戻せる。テストは未追加のため次のPRで追加する。"

Approve ではなく Comment を使います。 「読んだ」「何を確かめた」「何を残した」を文字にして残すのが目的です。

そして、ここが後で効いてきます。⑥でブランチ保護を入れますが、「レビュー承認を必須」にすると、一人では永遠にマージできなくなります。 その設定は入れません。

⑥ ブランチ保護 — 自分が自分を止める

チェックリストは、忘れます。 忘れても止まるようにします。

やることは1つです。「CIが緑でないPRは、main にマージさせない」。

画面で設定する

  1. GitHub でリポジトリを開く
  2. Settings → 左メニューの Rules → Rulesets → New ruleset → New branch ruleset
  3. 名前を protect-main にする
  4. Enforcement status を Active にする
  5. Target branches → Add target → Include default branch(= main)
  6. Rules で次の2つに ✅ を入れる
  • Require a pull request before merging(PRを通さずに main へ push させない)
  • Require status checks to pass → Add checks で、前回作ったCIのジョブ名(test)を選ぶ
  1. Create を押す

[スクリーンショット: 03_ブランチ保護.png] Ruleset の編集画面で、Require a pull request before merging と Require status checks to pass にチェックが入っている状態を撮ってください。

Require approvals は 0 のままにしてください。 1以上にすると、自分のPRは自分で承認できない(⑤)ため、一人では絶対にマージできなくなります。

「Upgrade」と出て設定できないとき

前回作ったリポジトリを非公開にしている場合、ここで止まることがあります。 GitHub の無料プランでは、非公開リポジトリでの保護機能に制限がかかることがあるためです(GitHub の料金プランは変わるので、最新は画面の表示が正です)。

選べる道は3つです。

道やること向くとき
A. 公開にするSettings → General → 一番下の Danger Zone → Change visibility秘密が1つも入っていないと確認できたときだけ
B. 手元で自分を止める下の pre-push フック非公開のまま続けたいとき(推奨)
C. 有料プランにする—いまは不要

Aは、履歴の全部が世界に見えるようになる操作です。 「いまのファイルに秘密が無い」では足りません。過去のコミットに1度でも .env を入れたことがあるなら、公開してはいけません。 前の回で書いたとおり、消しても履歴に残ります。

ついでに、セルフホストランナーを動かしているリポジトリを公開にしてはいけません。(理由はCIの回に書きました)

Bのやり方です。 Git は、特定の操作の前後に自分のスクリプトを走らせられます。これをフックと呼びます。

bash
$ nano ~/server/.git/hooks/pre-push
bash
#!/bin/sh
  branch=$(git rev-parse --abbrev-ref HEAD)
  if [ "$branch" = "main" ]; then
    echo "main に直接 push しようとしています。ブランチを切ってください。"
    echo "どうしても必要なときだけ: git push --no-verify"
    exit 1
  fi
  exit 0
bash
$ chmod +x ~/server/.git/hooks/pre-push

確かめます。

bash
$ git switch main
$ git commit --allow-empty -m "test: フックの確認"
$ git push
main に直接 push しようとしています。ブランチを切ってください。
どうしても必要なときだけ: git push --no-verify
error: failed to push some refs

止まりました。 空コミットは要らないので消しておきます。

bash
$ git reset --hard HEAD~1
$ git switch feat/health-endpoint

フックには弱点が2つあります。 ⓵ .git/hooks/ は Git の管理外なので、clone した先には付いてきません。 ⓶ --no-verify で素通りできます。

それでも意味があります。 これは他人を防ぐ壁ではなく、「あ、いまブランチを切っていなかった」と気づかせる仕掛けだからです。うっかりは、これで9割止まります。

CIが落ちたPRは、本当にマージできないのか

設定は、確かめるまで信じません。わざと落とします。

bash
$ git switch feat/health-endpoint

テストファイルに、必ず落ちる1行を足します。

test('わざと落とす', () => {
  assert.strictEqual(1, 2);
});
bash
$ git add -A
$ git commit -m "test: わざと落とす(あとで戻す)"
$ git push

PRの画面を見ます。

bash
$ gh pr checks
test  fail  1m2s  https://github.com/.../actions/runs/...

画面では、マージボタンが灰色になり、押せません。

[スクリーンショット: 04_ci失敗でマージ不可.png] PRの下部で、チェックが赤くなり、Merge ボタンが押せなくなっている状態を撮ってください。

これが「自分が自分を止める仕組み」です。 覚えていなくても、疲れていても、深夜でも、同じように止まります。

戻します。

bash
$ git revert --no-edit HEAD
$ git push
$ gh pr checks

緑に戻れば、マージできる状態です。

git reset ではなく git revert を使いました。 push 済みの履歴に reset を使うと、強制 push(--force)が必要になります。 一人のうちはまだ被害が出ませんが、枝を共有した瞬間に、相手の履歴を壊す操作になります。 最初から revert の癖を付けるほうが安全です。

⑦ マージして、枝を消す

bash
$ gh pr merge --squash --delete-branch

3つのマージ方法があります。

方法main に残る形向くとき
Squash and mergePRの全コミットが1つにまとまるほぼこれでよい。 main の履歴が「PR1つ=1行」で読める
Create a merge commit全コミット+合流の記録が残る枝の中の経過も残したいとき
Rebase and merge全コミットが一直線に並ぶ合流の記録が邪魔なとき

一人なら Squash が一番わかりやすいです。 枝の中の「あ、typo」「もう1回」も含めて、main には結果だけが1行で残ります。

手元も片づけます。

bash
$ git switch main
$ git pull
$ git branch -d feat/health-endpoint
bash
$ git branch
* main

リモートで消えた枝の情報が手元に残っていることがあります。

bash
$ git fetch --prune

これで一周しました。 ブランチ → 変更 → PR → レビュー → CI → マージ → 削除。一人で、全部やりました。

⑧ レビューされやすいPRの作り方

ここは「他人のため」に見えて、一番効くのは自分です。読めないPRは、自分でもレビューできません。

1. 小さくする

行数の目安があります。 一般に、400行を超えると、指摘の見つかる率が落ちると言われます。人間の集中が続かないためです。

「小さく」は感覚ではなく、測れます。

bash
$ git diff main --stat | tail -1
 3 files changed, 62 insertions(+), 8 deletions(-)

これが数百行になったら、分けられないかを考えます。

2. 目的を1つにする

「ついでに」を入れないということです。

ダメなPR分けたPR
「/health を足した。ついでにログの形式を変えて、ESLintの設定も直した」feat/health-endpoint / chore/log-format / chore/eslint-config

理由は①と同じです。 混ざったPRは、あとから片方だけ戻せません。

3. 説明を書く

PRの説明に書くのは「何をしたか」ではありません。 それは差分に書いてあります。書くのは、差分に書けないことです。

## なぜ
監視から死活確認をしたいが、既存の `/` は DB を見ているため、
DB が重いときに監視まで巻き込まれる。

## どうした
依存を一切見ない `/health` を足した。

## 確かめたこと
- `curl localhost:3000/health` で `{"status":"ok"}` が返る
- DB を止めた状態でも 200 が返ることを確認した

## やっていないこと
- 認証は付けていない(内部からしか叩かない前提)

この4つの見出しで、だいたい足ります。 テンプレートにして、毎回出せます。

bash
$ mkdir -p ~/server/.github
$ nano ~/server/.github/pull_request_template.md

上の内容を貼って保存し、コミットして push すると、次からPR作成画面に自動で入ります。

4. 差分を汚さない

これが一番効きます。

bash
$ git diff main

ここに、自分が意図していない行が出ていたら、その時点でPRは読めません。 主な原因は3つです。

原因症状対処
整形と機能変更を混ぜたファイル全体が変更扱いになる整形だけのPRを先に出して、マージしてから作業する
改行コードが混ざった変更していない行が全部出るgit config --global core.autocrlf input(Linux/Mac 側)
生成物をコミットしたdist/ や node_modules/ が出る.gitignore に入れる

「整形だけのPR」は、レビューで中身を読みません。 「機能の変更が1行も入っていないこと」だけを確かめます。だから混ぜてはいけないのです。混ぜた瞬間、数千行の中から意味のある3行を探す作業になります。

⑨ コミットメッセージ — 「何をしたか」は書かなくていい

差分を見れば、何をしたかは分かります。 分からないのは、なぜそうしたかです。

悪いよい
修正fix: DB接続が切れたときに落ちるので再接続を入れた
app.js を変更feat: 監視用に依存なしの /health を追加
いろいろ(そもそも1つのコミットに「いろいろ」を入れない)

Conventional Commits

メッセージの先頭に「種類」を付ける書き方が、広く使われています。種類: 内容 という形です。

feat: 新しい機能
fix: 不具合の修正
docs: ドキュメントだけ
style: 動作が変わらない整形
refactor: 動作を変えずに構造を直す
test: テストの追加・修正
chore: 設定やビルドまわり

利点は2つです。 ⓵ git log --oneline を眺めたときに、種類で目が滑らない。 ⓶ 機械が読めるので、リリースノートを自動生成できる。 欠点は、慣れるまで毎回どれか迷うことです。

一人なら feat / fix / docs / chore の4つだけで始めて構いません。 足りなくなってから増やします。最初から7種類を暗記しようとすると、続きません。

bash
$ git log --oneline -10

種類が付いているだけで、履歴の読みやすさが変わります。

⑩ ブランチ戦略 — GitHub Flow で十分

「戦略」と呼ばれていますが、要は「枝を何本立てるか」の話です。

枝の構成マージ先向くとき一人には
GitHub Flowmain + 作業枝常に main常に最新を出す。Webサービスこれでよい
Git Flowmain / develop / feature / release / hotfix段階的版を切って配るもの(インストーラ、ライブラリ)重すぎる
Trunk Basedmain のみ、枝は数時間で消すmain1日に何度も出す大人数チーム枝が短命すぎて逆に難しい

Git Flow は 2010年に提案された方式で、提案者自身が後に「Webアプリには向かない」と補足を出しています。「継続的に1つの版を出し続けるもの」には、develop と release の分だけ手間が増えるだけです。

この記事でやったのが GitHub Flow です。 ルールは5行で終わります。

  1. main は常に動く状態にする
  2. 作業は必ず枝を切る
  3. 枝は push して、PRを作る
  4. CIが通ったらマージする
  5. マージしたら枝を消す

これ以上は、人が増えてから足せば済みます。

「人が増えたらどうするか」は、コードの分け方の話とセットになります。 サービス自体を分けるかどうかはモノリスとマイクロサービスの回で扱いました。枝の戦略を先に複雑にしても、そこは解決しません。

⑪ コンフリクトを、わざと起こして直す

コンフリクトは、初心者が一番怖がるものです。 そして怖がる理由は、初めて出会うのが「急いでいるとき」だからです。

急いでいないいま、わざと起こします。

枝を2本作って、同じ行を違う内容に変えます。

bash
$ cd ~/server
$ git switch main
$ git pull
$ echo "バージョン: 1.0" > VERSION.md
$ git add VERSION.md
$ git commit -m "chore: VERSION.md を追加"
$ git push

(pre-push フックを入れている場合は、ここだけ git push --no-verify を使うか、この準備も枝でやってマージしてください)

枝A:

bash
$ git switch -c chore/version-a
$ echo "バージョン: 1.1" > VERSION.md
$ git commit -am "chore: 1.1 にする"

枝B:

bash
$ git switch main
$ git switch -c chore/version-b
$ echo "バージョン: 2.0" > VERSION.md
$ git commit -am "chore: 2.0 にする"

Aを先に main に入れます。

bash
$ git switch main
$ git merge chore/version-a

そのうえで、Bを入れようとします。

bash
$ git merge chore/version-b
Auto-merging VERSION.md
CONFLICT (content): Merge conflict in VERSION.md
Automatic merge failed; fix conflicts and then commit the result.

出ました。まず、いま何が起きているかを見ます。

bash
$ git status
You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Unmerged paths:
        both modified:   VERSION.md

Git は、ちゃんと出口を書いてくれています。 both modified は「両方が同じファイルを変えた」という意味です。

ファイルを開きます。

bash
$ cat VERSION.md
<<<<<<< HEAD
バージョン: 1.1
=======
バージョン: 2.0
>>>>>>> chore/version-b

この記号の読み方だけ覚えれば、もう怖くありません。

記号意味
<<<<<<< HEADここから下が、いま自分がいる側(=main)の内容
=======境目
>>>>>>> chore/version-bここまでが、合流させようとしている側の内容

Git は「どちらが正しいか」を判断できないので、両方を並べて人に渡しています。 それだけです。

直し方は、テキストを普通に編集するだけです。 記号ごと消して、残したい形にします。

bash
$ nano VERSION.md
バージョン: 2.0

<<<<<<< ======= >>>>>>> の3行を消し忘れるのが、最も多い失敗です。消し忘れたままコミットすると、そのままコードに残ります。 保存したら必ず cat で見てください。

bash
$ git add VERSION.md
$ git commit

メッセージは Git が用意しているので、そのまま保存して構いません。

bash
$ git log --oneline -3

中止のしかた — これが一番大事

途中で「やっぱりやめたい」と思ったら、いつでも戻せます。

bash
$ git merge --abort

マージを始める前の状態に、完全に戻ります。 何も壊れません。

これを知っているかどうかで、コンフリクトの怖さが変わります。 「一度始めたら最後までやらないといけない」と思っていると焦ります。いつでも --abort で降りられます。

状況コマンド
マージ中に、やめたいgit merge --abort
いま何が衝突しているか見たいgit status
片側の内容をまるごと採用したいgit checkout --ours VERSION.md / git checkout --theirs VERSION.md
直したファイルを「解決済み」にするgit add <ファイル>

--ours は「いま自分がいる枝」、--theirs は「合流させようとしている枝」です。 マージ中とリベース中で意味が入れ替わるので、迷ったら使わずに手で編集するほうが安全です。

練習用の枝を片づけます。

bash
$ git branch -d chore/version-a chore/version-b

コンフリクトを減らす方法

技術ではなく、進め方の問題です。

  • 枝を長く持たない。 3日置いた枝は、main から3日分ずれます
  • こまめに main を取り込む。 git switch <枝> してから git merge main
  • 同じファイルを触るPRを同時に開かない
  • 整形と機能変更を混ぜない(⑧)。整形はファイル全体を変えるので、必ず衝突します

⑫ 置き場所は GitHub だけではない

Git はソフトウェアで、GitHub はそれを置くサービスです。(この区別は前にやりました)置き場所には他の選択肢もあります。

GitHub は、利用者数が最も多く、事実上の標準です。公開リポジトリのほとんどがここにあるので、他人のコードを読む・issue を出す・PRを送るという体験がそのまま学習になります。CI(GitHub Actions)が最初から統合されていて、この記事でやったことは全部ここで完結します。選ぶ理由に迷いがないなら、ここでよいです。

GitLab は、自分のサーバーに丸ごと立てられるのが最大の違いです(Community Edition)。ソースコードを社外に置けない組織で採用されます。CI/CD が早くから統合されていて、Auto DevOps のように「設定を書かなくても一通り回る」方向に寄っています。自前運用ができる代わりに、その運用は自分の仕事になります。

Bitbucket は、Atlassian の製品で、Jira との連携が前提にあります。「チケット番号を枝の名前に入れると、チケット側に自動で紐づく」といった動き方が標準です。すでに Jira を使っている組織で選ばれますが、それ以外の理由で選ぶことは少なくなりました。

CIツールの違いは別の回で比較しました。 置き場所を移しても、この記事でやった「枝 → PR → レビュー → マージ」は、名前が変わるだけで同じです。(GitLab では「マージリクエスト」と呼びます)

⑬ ドキュメントをどこに置くか

コードの外に置いたドキュメントは、必ず腐ります。 別の場所にあるものは、コードを直すときに一緒に直されないからです。

置き場所は、基本的に3層で考えます。

置き場所何を書くか誰が読むか
README.mdこれは何か / どう動かすか / どう止めるか初めて開いた人(3週間後の自分を含む)
リポジトリの中(docs/, CONTRIBUTING.md)設計の理由、決めごと、運用手順作業する人
自動生成(OpenAPI、型定義、--help)仕様そのもの使う人

優先順位ははっきりしています。

  1. コードで表せることは、ドキュメントに書かない(名前を直す)
  2. 機械が生成できることは、手で書かない(APIの仕様は、コードから出す)
  3. それでも残った「なぜ」だけを、文章で書く

README.md に最低限入れるのはこれだけです。

# server

Express + MySQL の練習用API。

## 動かす
    npm ci
    cp .env.example .env   # 値は各自で入れる
    npm start

## 止める
    sudo systemctl stop myserver

## 注意
- `.env` はコミットしない
- main への直接 push は禁止(PR経由)

このサイト自体も、同じことをしています。 リポジトリの直下に CLAUDE.md という1枚を置いて、「記事を書くときに毎回守るルール」だけを書いています。経緯や履歴は別の場所に書き、この1枚には『毎回必要なこと』しか置かない、という分け方です。ドキュメントが読まれなくなる最大の原因は、量です。

⑭ やりすぎない

ここまで書いてきましたが、一人で全部を厳密にやる必要はありません。

一人でもやる価値がある一人ならやらなくていい
ブランチを切るレビュー承認を必須にする(そもそも不可能)
PRを作って、説明を書く複数人での相互レビュー体制
CIが緑でないとマージできない設定develop / release 枝を作る
セルフレビューのチェックリストPRごとのラベル運用・自動割り当て
コミットメッセージに理由を書くリリースノートの自動生成(後から入る)

左の列だけでも、得られるものは大きいです。

  • main が常に動く(壊れたものは入れない、が機械で保証される)
  • 変更の単位が「PR1つ=目的1つ」になるので、あとから1つだけ戻せる
  • なぜそうしたかが、3週間後に読める
  • 人が増えたときに、やり方を変えなくていい

PRは「他人に許可をもらう手続き」ではありません。 一人のときは、変更を main に入れる前に、自分で立ち止まるための場所です。立ち止まる場所があるだけで、事故は減ります。

つまずいたところ

⓵ gh pr create で「no git remote found」と言われた

~/server 以外のディレクトリで打っていました。gh は、いまいるディレクトリの Git リポジトリを見ます。 cd ~/server してから打ちます。

⓶ ブランチ保護を入れたのに、main に push できてしまった

Ruleset の Enforcement status が Disabled のままでした。 作った直後は有効になっていないことがあります。Active になっているかを必ず見てください。 また、リポジトリの管理者は「バイパス」できる設定になっていることがあります(Bypass list)。一人のときは、自分が管理者なので、ここを空にしておかないと意味がありません。

⓷ ステータスチェックの一覧に、CIのジョブ名が出てこない

GitHub は「最近走ったチェック」から候補を出します。 一度もPR上でCIが走っていないと、選べません。先にPRを1つ作ってCIを走らせてから、設定に戻ってください。

⓸ Require approvals を 1 にして、詰んだ

自分のPRは自分で承認できない(⑤)ので、マージボタンが永久に押せなくなりました。設定を 0 に戻して解決しました。 一人のときは絶対に入れない設定です。

⓹ PRの差分が2000行を超えた

エディタの設定で保存時整形が有効になっていて、触ったファイル全体の引用符とインデントが変わっていました。 一度 git checkout -- . で捨てて、整形だけのコミットを先に main に入れてから作業をやり直しました。⑧の「差分を汚さない」は、この日にできた項目です。

⓺ コンフリクトを直したのに、まだコンフリクトと言われる

git add を忘れていました。 ファイルを直しただけでは、Git には「解決した」と伝わりません。直す → git add → git commit の3手で1組です。

⓻ git branch -d が拒否された

error: The branch 'feat/x' is not fully merged.

まだマージしていない変更が残っている枝を消そうとしたときに出ます。これは親切な警告です。 本当に捨ててよいと分かっているときだけ -D(大文字)を使います。中身を確かめずに -D を打つ癖を付けないでください。

後片づけ

練習で作ったものを片づけます。

bash
$ cd ~/server
$ git switch main
$ git pull
$ git fetch --prune
$ git branch

main だけになっていれば片づけ完了です。 残っている枝があれば消します。

bash
$ git branch -d <枝の名前>

わざと落としたテストが残っていないかを確かめます。

bash
$ grep -rn "わざと落とす" ~/server --include="*.js"

何も出ないのが正解です。 出たら消して、コミットしてください。

練習で作った VERSION.md が要らなければ、枝を切って消します。

bash
$ git switch -c chore/remove-version
$ git rm VERSION.md
$ git commit -m "chore: 練習用の VERSION.md を削除"
$ git push -u origin chore/remove-version
$ gh pr create --fill

この片づけ自体を、PRでやってみてください。 一周が身体に入ります。

残しておくもの:

  • ブランチ保護(または pre-push フック) — これが本体です
  • .github/pull_request_template.md — 次から自動で出ます
  • README.md — 3週間後の自分のために

まとめ

  • main に直接コミットする問題は、速さではなく「作業中のものが本番の位置にある」こと。 一人でも同じ
  • 混ざったコミットは、片方だけ戻せない。 分けて戻す手段は、混ぜた時点で消えている
  • ブランチは「作業場所を本番から離す」ためのもの。 git switch -c で作って、git push -u で上げる
  • PRは Git の機能ではなく GitHub の機能。 「合流させたい」という申請であって、他人の許可を得る手続きではない
  • 一人のPRは、未来の自分に向けたチェックリスト。 3週間後の自分は他人なので、「なぜ」を説明に書く
  • レビューで見るのは5つだけ。 動くか / 読めるか / 戻せるか / 秘密が入っていないか / テストがあるか
  • 「好み」を指摘しない。 インデントも引用符も機械の仕事。人が指摘すると意見の言い合いになる
  • 自分のPRは自分でApproveできない。 だから Require approvals を入れると、一人では永久にマージできない
  • 入れるのは「ステータスチェック必須」だけでいい。 これでCIが落ちたPRは自分でもマージできない
  • 設定は、わざと落として確かめる。 マージボタンが灰色になるのを見るまで、入っていると信じない
  • 無料プランの非公開リポジトリで保護が使えないときは、pre-push フックで代替できる。 完璧ではないが、うっかりは9割止まる
  • 保護が使いたいからといって、非公開を公開に切り替えない。 過去のコミットは消えない
  • push 済みの履歴は reset ではなく revert で戻す。 強制 push は、枝を共有した瞬間に人を壊す
  • PRは小さく、目的は1つ、説明を書き、差分を汚さない。 整形と機能変更を混ぜたPRは、誰にも読めない
  • コミットメッセージには「なぜ」を書く。 「何を」は差分に書いてある
  • ブランチ戦略は GitHub Flow で十分。 Git Flow は版を切って配るもの向けで、一人のWebサービスには重い
  • コンフリクトは、急いでいないときにわざと起こしておく。 記号3つの読み方と、git merge --abort で降りられることを知っていれば怖くない
  • git add を忘れると、直しても解決したことにならない
  • 置き場所は GitHub / GitLab / Bitbucket。 名前は変わるが、枝 → PR → レビュー → マージは同じ
  • ドキュメントはコードの近くに置く。 機械が生成できることは手で書かない。 残った「なぜ」だけを書く
  • 一人ならやりすぎない。 ブランチ・PR・CI必須・セルフレビューの4つで、得られるものはほとんど取れる

ここまでで、「変更を main に入れる前に立ち止まる場所」ができました。 立ち止まって何を見るかも、5項目の表になっています。あとは、それを毎回やるだけです。 そして毎回やるための仕組みは、記憶ではなくブランチ保護が持っています。

参考リンク

GitHub の設定画面は改編が多く、メニューの位置がよく変わります。 「Rules」が見当たらないときは、Settings 内を 「branch」「ruleset」「protection」 で探してください。やりたいことは「main に入れる条件を決める」の1つです。


次に読む

この記事は 【第8段階】深掘り の 19 / 30 本目です。

記事
← 前の記事同じボタンが3種類できる理由 — デザインシステム
→ 次の記事FTPは平文で流れる — 仕事で出会う古い技術

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次