How Git Works by ジュリア・エヴァンス
Git、毎日使っているのにまだ怖いと思うこと、ありませんか？ git pushが拒否されたとき、同僚に「リベースして上げてください」と言われたとき、 detached HEAD stateというメッセージが出たとき。 頭の中が真っ白になって、とりあえずフォルダごと消して新しくcloneし直したこと、 一度くらいはあるはずです。 この講義は、そんな方たちのための講義です。 世界中の開発者に愛されたJulia Evansの〈How Git Works〉、 ついに日本語版で登場です。 コマンドを暗記する講義ではありません。 Gitが内部でどのように動作しているのかを、じっくりと覗き見る講義です。 .gitフォルダの中に何が入っているのか、 ブランチは実際どのように保存されているのか、 「迷子になった」コミットはどこへ行き、どうやって取り戻せるのか、 「up to date with origin/main」が本当はどういう意味なのか。 全27ページ、6つのチャプターで構成されています。 ★ コミット(commits) ★ ブランチ(branch) ★ .gitフォルダを覗いてみる ★ マージ(merge) ★ リモートリポジトリ(remote) ★ 大惨事から生き残る 内部モデルを一度しっかり掴んでしまえば、 次からはGitが投げかけるどんなメッセージも自分で解釈できるようになります。 コマンドを覚えるのではなく、「なぜこう動くのか」を理解して使えるようになるからです。 Juliaがジン（zine）の最初のページでした約束を、そのままお伝えします。 「内部原理さえしっかり把握すれば、どんなGitの混乱状態からも自力で抜け出すことができます。」
48名 が受講中です。
難易度 初級
受講期間 無制限
お知らせ
2 件
･
修正済み
こんにちは、BFS(Byte Freaks Studio)です。 🎲
今日は、ジュリア・エヴァンスが昨年1月に自身のブログに投稿した記事をご紹介したいと思います。それは、Gitの公式ドキュメント（documentation）を自ら修正した話です。
Gitを使っていると、一度は
object、reference、indexといった用語の前で立ち止まったことがあるはずです。ジュリアも同じところで立ち止まり、結局同僚のMarieと一緒にGitの公式マニュアルページ（man page）のいくつかを直接修正することにしました。80人のテスト読者から「どこが分かりにくいか」というフィードバックを受けながら、
git add、git checkout、git push、git pullのページをブラッシュアップした過程、そしてその中で知ることになったオープンソースのドキュメント作成作業における意外な難しさまで、Gitユーザーなら興味深く読んでいただける内容です。
翻訳は以下に続きます。原文が気になる方はこちらから直接ご確認いただけます。楽しんで読んでください。 🎲
Gitのデータモデル（およびいくつかのドキュメントの更新）
こんにちは！
去年の秋、私はGitのドキュメントを改善する作業に時間を充ててみることにしました。普段、ドキュメントが物足りないと感じたときは、ブログ記事やZine（小冊子）を別途書くことで解決してきました。しかし、今回はふとこんな考えが浮かびました。
"公式ドキュメント自体をもっと良くすることはできないだろうか？"
そこで、同僚のMarieと一緒に、Gitドキュメントにいくつかの改善作業を行いました。
Gitのためのデータモデル
Gitのドキュメントを調べてみると、Gitは
object、reference、indexといった用語を非常に頻繁に使用していました。しかし、これらの用語が正確に何を意味するのか、そしてcommitやbranchといった核となる概念とどのような関係があるのかを説明する資料が不足していることに気づきました。そこで、私たちは新しい"データモデル(Data Model)"ドキュメントを作成しました。
現在はこちらで読むことができ、次回のリリース以降にはGit公式ウェブサイトにも含まれる予定です。
BFS NOTE: 現在はGit公式ウェブサイトに反映されています。
私がこの作業に特に満足している理由は、Gitがコミットやブランチのデータをどのように構成しているかを理解することが、長年Gitを理解する上で大きな助けになってきたからです。そのため、Gitのデータモデルを短く（約1,600単語）、かつ正確に説明する文書がどうしても必要だと考えていました。
ただ、正確であるということは思ったより簡単ではありませんでした。基本的な構造はすでに知っていましたが、レビューの過程で多くの新しい詳細事項を学ぶことになり、それに伴い多くの部分を修正しなければなりませんでした。例えば、マージコンフリクト（merge conflict）がステージングエリアにどのように保存されるかについての説明も修正されました。
git push、git pullなどを含むドキュメントの改善
また、Gitの主要なマニュアルページ（man page）数件の導入部を改善する作業も進めました。
最初は単に「自分がより良いと思う方向に直してみよう」と考えましたが、すぐに問題があることに気づきました。"自分の説明の方が良いと言ったところで、Gitのメンテナーたちがそれを信じてくれる理由があるだろうか？"
オープンソースのドキュメント作業をしていると、このような状況をよく目にします。
"このように説明するほうがより明確ではないだろうか？"
"いや、あのように説明するほうがもっと良いのでは？"
しかし、ソフトウェアの専門家同士で「どちらの説明がより理解しやすいか」を論争することは、それほど生産的ではないと考えました。特定のツールを長く使っている人は、初心者が何に苦労しているのかを判断するのが難しい場合が多いからです。
そこで、私たちはもう少し根拠に基づいた方法を見つけたいと考えました。
テスト読者を通じて問題を見つける
Mastodonでボランティアを募り、既存のドキュメントを読んでみて、どこが分かりにくいか、どのような疑問が生じるかを教えてほしいと依頼しました。
約80名のテスト読者が意見を寄せてくださり、その過程で本当に多くのことを学びました。
人々が残してくれたフィードバックは非常に多様でした。
理解しにくい用語
pathspecとは何ですか？?referenceはどういう意味ですか？ mean?upstreamという用語は、Gitにおいて特別な意味がありますか？ có ý nghĩa đặc biệt gì trong Git không? have a special meaning in Git?
特定の文章が理解しにくいという意見
追加してほしい内容の提案
「私はいつもこのような作業をしているので、ここに含まれると嬉しいです。」
ドキュメント間の不一致の指摘
ある場所ではXがデフォルトであるかのように見えますが、別の場所ではYがデフォルトであるかのように見えます。
興味深かった点は、テスト読者のほとんどがGitを少なくとも5〜10年以上使用している人たちだったということです。
これがむしろ良かったです。Gitを長年使ってきた人々でさえ、ある文章や用語を理解しにくいと感じるのであれば、それはドキュメントをより明確に修正すべきだという強力な根拠になるからです。
このような方式、つまり
"実際のユーザーが既存のドキュメントを読んで問題点を指摘すれば、その問題を修正する"
というアプローチが非常に効果的だと感じましたし、今後も他のプロジェクトで再び試してみたいと思っています。
どのマニュアルページを修正しましたか？
私たちは次の4つのマニュアルページを修正しました。
特に
git pushとgit pullの作業が最も興味深かったです。導入部を改善するだけでなく、次の内容を新しく作成しました。
upstream branchとは何かを説明するセクション(以前は事実上、まともに説明されていませんでした。)
push refspecに関する説明の整理explanation cleanup
この作業をしながら、オープンソースのドキュメントをメンテナンスすることがいかに難しいか、改めて実感しました。
"文章は明快であるだけでなく、同時に事実とも一致していなければなりません。"
時には妥協も必要でした。例えば、次の文章を見てみましょう。
git pushmay fail if you haven't set anupstreamfor the current branch, depending on whatpush.defaultis set to.
("現在のブランチのupstreamが設定されていない場合、push.defaultの設定によってはgit pushが失敗することがあります。")この説明は多少曖昧です。しかし、「設定によって」が正確に何を意味するのかを完全に説明するには、はるかに複雑な内容を扱う必要があり、それだけで一つの大きなプロジェクトになるほどでした。
Gitへの寄稿プロセスについて
Gitの開発プロセスを理解するのにも、かなりの時間がかかりました。
ここで全てを説明するつもりはありません。それだけで別の記事が一編書けてしまうほどですから。
代わりに、いくつか短いメモを残しておきます。
GitにはDiscordサーバーがあり、初めて貢献する人のための"my first contribution"チャンネルがあります。
始めるのに必要な助けを得ることができましたし、皆とても親切でした。
私はすべての貢献をGitGitGadgetを通じて行いました。
GitHub Pull Requestという慣れ親しんだワークフローを使用することができ、
GitGitGadgetがこれをGit開発者たちが使用するメールパッチ形式に変換してくれました。
おかげで、メールパッチを送る方法を新たに学ぶ必要がありませんでした。
レビューに返信する際は、普段使っているメールクライアント（Fastmailのウェブインターフェース）を使用しました。
メーリングリストの慣習に合わせて、テキストを80文字単位で改行しました。
また、lore.kernel.orgのメーリングリストアーカイブは、探索するのが多少不便でした。そのため、長い議論のスレッドを読みやすくするために、個人的に簡単なGitメーリングリストビューアを作成して使用しました。
貢献の過程やレビューの過程では、多くの方々の助けを借りました。Emily Shaffer、Johannes Schindelin（GitGitGadgetの作成者）、Patrick Steinhardt、Ben Knoble、Junio Hamanoをはじめとする多くの方々に感謝いたします。
BFS
この文章で最も印象的だった部分は、ジュリアが「自分の方がうまく説明できる」という確信だけで文書を直さなかった点でした。代わりに、実際のユーザーの反応をまず集め、そのデータを根拠に修正の方向性を決めました。2人の専門家が「この表現の方が明確だ」と論争するよりも、実際に混乱している人々の声を聞く方が、はるかに信頼できるということです。
Gitを毎日使っていながらも、どこか腑に落ちなかった表現があったなら、この記事がその答えを少しは示してくれるかもしれません。
これからは、ジュリアがこれまで自身のブログに綴ってきたGitに関する記事を一つずつ選んで、翻訳して紹介していこうと思います。ある記事は私たちがGitを使いながらよく経験する些細な不便さを、またある記事は慣れ親しんでいると思っていた概念に対する誤解を改めて見つめ直すような内容です。
『How Git Works』とあわせて読むと理解がより一層深まるような記事を、一つずつゆっくりお届けする予定ですので、楽しみにしていてください。 🎲
- BFS 🎲
･
修正済み
" こんにちは！
『How Git Works』の日本語翻訳版が出版されることを心から嬉しく思います。私は日本語を読むことはできませんが、翻訳版のデザインと完成度を見て、本当に美しく作られていると感じました。
この小さなZine（ジン）が、皆さんがGitをより自信を持って理解し、使いこなすための助けになることを願っています。
楽しく読んでください！ "
— Julia Evans
こんにちは。BFS(Byte Freaks Studio)です。🎲
Juliaの挨拶を読んで、一つ疑問が湧いたかもしれません。Juliaはなぜこのジン（Zine）を作ることになったのでしょうか？
Gitは世界中の数多くの開発者が毎日使用するツールですが、同時に最も多くの人が難しさを感じるツールでもあります。Juliaもその点に注目し、その悩みが最終的に『How Git Works』という作品につながりました。
以下の文章は、Juliaが『How Git Works』の出版当時に自ら執筆したブログ記事です。このZine（ジン）がどのような問題意識から始まり、何を伝えたかったのかをより深く理解できる内容だと思い、日本語でご紹介します。
楽しく読んでください。 🎲
こんにちは！
ここ数ヶ月、このブログでGitの話ばかりし続けていたような気がしますが、ついにGit Zine（ジン）が完成しました！先週の金曜日に出版されました。
このジン（Zine）は誰のための本ですか？
このZineは、Gitを何年も使っているけれど、いまだにGitが怖いと感じている人たちのために書きました。私はいつもこう思っています。毎日仕事で使う道具を怖がらなければならないなんて、本当に嫌なことですよね！私は、皆さんに自信を持ってGitを使えるようになってほしいと願っています。
このZineの目標は以下の通りです。
最初は怖く感じられるかもしれないGitの概念（例えば"detached HEAD状態"）が、実際には何が起きているのかさえ理解すれば、かなり単純であることを説明すること
Gitで特に注意すべき点について説明すること。例えば、stashは作業内容を最も失いやすい機能の一つであり、一度問題が発生すると復旧も非常に面倒です。そのため、私はstashをあまり使わないようにしています。
コミット（commit）、ブランチ（branch）、マージ（merge）といったGitの核心概念について、広く知れ渡っている誤解を正すこと
一体Gitの何がそんなに紛らわしいのでしょうか？
この記事を書くのは思った以上に本当に大変でした。書き始めたとき、私はすでに10年間かなり自信を持ってGitを使いこなしていたからです。そのため、Gitのせいで苦労していた頃がどのような感じだったか、ほとんど覚えていませんでした。
しかし、MarieやMastodonでGitについて話してくれた多くの方々の助けのおかげで、結局のところGitには直感的でなかったり、誤解を招いたり、あるいは単に紛らわしい部分が本当にたくさんあるという事実に改めて気づかされました。
例えば、次のようなものです。
紛らわしい用語（「fast-forward」、「reference」、「remote-tracking branch」のような表現）
誤解を招くメッセージ（例えば
Your branch is up to date with 'origin/main'というメッセージが、必ずしもリモートリポジトリの main ブランチと実際に同期されていることを意味するわけではありません）十分な情報を与えてくれない出力結果（例えば、私は今でもマージコンフリクトを見ているとき、どのコードがどのブランチから来たのか一度に把握できないことがあります）
ブランチが互いに分かれた（diverged）状況に対する不十分な案内（例えば
git pullを実行した際にローカルブランチとリモートブランチが分かれている場合、Gitはこの状況をどのように処理すべきか、それほど親切に説明してくれません）一貫性のない動作（例えば、reflogはほとんど常に記録が追加される方式で動作しますが、stashだけは例外です。
git stash dropを実行すると、既存の項目が実際に削除されます）
人々がGitをどれほど混乱していると感じているかという話を聞けば聞くほど、Gitは単に使ってみるだけではその内部ロジックを理解するのが容易ではないツールであるという事実が、ますます明白になりました。
Gitの奇妙な点も、結局は慣れます
ここまでの内容を読んでいると、Gitが本当にひどいツールのように聞こえるかもしれません。「一体誰がこんなものを使っているんだ？」と思うほどに。
しかし、私の経験は少し違います。Gitが吐き出す奇妙なエラーメッセージが実際に何を意味しているのかを理解してからは、ほとんどの状況がかなり日常的なことになりました。
例えば、次のようなエラーに遭遇したとしましょう。
failed to push some refs to 'github.com/wizard-zines-site'
すると私は「あ、最後に
git pullをしてから、誰かがmainブランチに変更をプッシュしたんだな」と考えます。そしてgit pull --rebaseを実行して変更を取り込み、作業を続けます。通常、10秒ほどで終わる作業です。または次のような警告が表示されることもあります。
You are in 'detached HEAD' state
そんな時は、単にコードを書き続ける前に
git checkout mybranchを実行すれば大丈夫です。大きな問題ではありません。私にとっても、そしてGitについて語り合う多くの人々にとっても、Git特有の奇妙な表現はあまりにも馴染み深いものになりすぎて、なぜ誰かがそれを難しく感じるのかさえ忘れてしまうほどです。
Gitの内部構造はどこまで深く扱うべきか？
このジン（Zine）を書きながら最も悩んだことの一つは、
.gitディレクトリの内部をどこまで説明すべきかということでした。結局、私たちはGitの内部構造を扱うページ（「.gitフォルダを覗いてみる」）を含めることにしましたが、全体的にはGitを使用する際に実際に目にすることになる動作と、Gitが時折予想外の挙動をする理由により集中することにしました。
その理由は2つあります。一つは、すでにGitの内部構造を説明する優れた資料がたくさん存在しているからです。
そしてもう一つは、そのような資料を読んだとしても、それがGitのユーザーインターフェースで実際に目にする現象とどのように結びついているのかを理解するのは、思ったほど簡単ではないと感じたからです。
例えば、Gitのリモートリポジトリ（remote）に関する説明は簡単に見つけることができます。あるドキュメントでは、次のように説明されています。
Remote-tracking branches [...] remind you where the branches in your remote repositories were the last time you connected to them.
しかし、この説明を読んだからといって、
git statusに表示される次のメッセージがYour branch is up to date with 'origin/main'
必ずしもリモートリポジトリのmainブランチと完全に同期されているという意味ではないという事実まで、自然に理解できるわけではありません。
ですので、このジンではGitの内部構造を先に説明するのではなく、皆さんがGitを使いながら実際に遭遇する動作に焦点を当て、そのような動作がGitの内部ではどのような原理で行われているのかを併せて説明しようとしました。
実は、私はGitが大好きです
この記事ではGitに対してかなり批判的な話をたくさんしました。しかし、私は自分が好きな技術についてのみジン（Zine）を書きます。Gitも例外ではありません。
私がGitを好きな理由はいくつかあります。
速いです！
後方互換性に優れています。10年前に学んだGitの知識が、今でもほとんどそのまま通用します。
無料で利用できる素晴らしいGitホスティングサービスが本当にたくさんあります。（GitHub！GitLab！そして他にもたくさんあります！）そのおかげで、自分のコードを簡単にバックアップすることができます。
シンプルなワークフローは本当に単純です。一人でプロジェクトを進める時は、
git commit -am 'whatever'とgit pushを繰り返すだけでも、ほとんどの場合うまく機能します。Gitの内部ファイルのほとんどは、かなり単純なテキストファイルです。（あるいは、テキスト形式で確認できるバージョンが存在します。）そのため、必要であれば内部で何が起きているのかをいつでも理解できるような安心感を与えてくれます。
このZine（ジン）が、皆さんもGitを好きになるための少しでも助けになれば幸いです。
このジン（Zine）を作るのに協力してくれた人たち
私はこのジン（Zine）を一人で作っているわけではありません！
私は8か月間、毎朝 Marie Claire LeBlanc Flanagan と共に、Gitをより分かりやすく説明する方法を悩みながら作業しました。表紙は Vladimir Kašiković が手掛け、Gersande La Flèche が校正を担当しました。『Building Git』の著者である James Coglan は技術監修を、運営マネージャーの Lee はテキストの書き起こしだけでなく、数え切れないほど多くのことを手伝ってくれました。私のパートナーである Kamal は、いつものように初稿を読んで不自然な部分を教えてくれました。また、Marco Rogers とも Git について本当に多くの有意義な対話を交わしました。
最後にベータリーダーの皆様にも感謝の言葉を伝えたいと思います。今回はなんと66名ものベータリーダーが参加してくれましたが、これは今までで最も多い人数でした！彼らは何が分かりにくかったか、何を新しく学んだか、そして私のジョークのどれが面白かったかについて、数百もの意見を残してくれました。
自分が分かりやすく説明したと思っていたページが、実は非常に混乱を招くものだったと聞くのは、いつだって簡単なことではありません。しかし、そのような問題を最終的な出版前に発見して修正できたことで、このジン（Zine）はより良い仕上がりになりました。
ありがとうございますいつものように、これまで私のZineを購入してくださったすべての方々に心から感謝申し上げます。皆さんの変わらぬ応援のおかげで、ここまで来ることができました。
そして、出版からわずか3日という短期間でこのジンを購入してくださった1,000名を超える皆様にも感謝申し上げます！！！
おかげさまで、このZineはWizard Zinesの歴史の中で、1日に最も多く販売されたZineという記録を打ち立てました。本当に驚きましたし、大きな感動を覚えています。
BFS(Byte Freaks Studio)
Juliaの記事は楽しんでいただけましたか？
この文章で最も印象深かった点は、JuliaがGitの不便さを単に批判するにとどまらなかった点でした。Gitは難しいです。時には奇妙で、あるメッセージは理解しにくく、ある動作は直感的ではありません。しかし、Juliaは「Gitはなぜこうなのだろう？」という問いを投げかけました。そして、Gitを理解するのが難しい理由を一つひとつ分析し、説明しようとしました。
もう一つ印象深かった点は、Gitの学習教材に対する視点でした。
すでに市中にはGitの内部構造を説明する優れた資料がたくさん存在します。しかし、そのような資料を読んだ後でも、いざターミナルでGitを使っていると「それで、今Gitはどうしてこういう挙動をしているんだ？」という疑問が残る場合が多いです。
Gitの内部原理と、実際のユーザーが向き合うユーザーインターフェースの間には、思った以上に大きな隔たりが存在します。おそらく多くの方が似たような経験をしたことがあるでしょう。Gitに関する分厚い本をいくらか読んで理解したつもりになっても、いざ実際の作業中にエラーメッセージに遭遇すると、再び戸惑ってしまうという経験です。
私たちは、Juliaがまさにそのギャップを正確に指摘した点を高く評価しました。何よりも、この一文には特に共感しました。
You are in 'detached HEAD' state
開発者なら一度は、このメッセージを見て戸惑ったことがあるはずです。
"これってどういう意味？" "今何をすべき？" "下手にいじると何かが壊れてしまうのではないか？"
私自身も皆さんと同じような悩みを抱えてきました。ですから、この本はGitのすべてを説明しようとする本というよりは、Gitがなぜそのような挙動をするのかを理解する手助けをしてくれる本に近いと感じました。
そしてその理解が深まるほど、Gitは少しずつ身近になり、少しずつ怖くないツールになっていきます。皆さんも『How Git Works』を通じてGitをもう少し理解し、Gitを少しでも怖がらなくなることを願っています。
— BFS 🎲
