Table of Contents
- はじめに
- GitHubを5秒で表現すると？
- 絶対にハズせない三大機能
- バージョン管理をしてみよう
- Pull Requestをしてみよう
- 仕事をスムーズにすすめるための補助機能
- 自分のマシンで編集してみよう
- 水研業務のコンテキストから見たGitHub
- 読者の感想
- Appendix
🎉 さぁ、
GitHubを学びましょう！ 🎉
ただし、講師から習うのではありません 🙅 学習の手引きを読み、不明点はIssueとして運営に投げてみましょう。 Pull Requestによる変更の提案も大歓迎てす。 この学びかた自体がもはや共同開発です。
「ここまで読んだだけで既に知らない用語がある...」> 😢
🕺 <大丈夫。下の方で解説されているはずです。解説に不備があったら、ここから教えてください。
ここでは、GitHubの使い方に集中するため、まずブラウザ上でGitHubを操作することからはじめます。 途中から、Gitコマンドも登場しますが、 最低限で済むように工夫してあります1
そもそも、GitHubとGitはどのような関係にあるのでしょうか。 これを理解するには、GitHubが車、Gitをエンジンに例えるとよいでしょう。 エンジンを意識せずとも、車を運転することはできます。 もちろん、Gitの強力なコマンドたちは、日常業務の大きな助けとなります。 興味のある方は GitHubinar of Gitにご参加ください。
チームプレーに必要な全てが詰まったナレッジベースです。
GitHubにはたくさんの機能がありますが、特に重要な機能は3つ— 「バージョン管理」「Issue」「Pull Request」です2。 いちばん重要な機能はバージョン管理ですが、ここでは簡単な順に学んでいきましょう。
Issueを立てるのは簡単です。
g i（Go to Issue）そしてc（Create）とタイプするだけです。
さて、Issueとは何かの説明をしていませんでした; Issueとは、プロジェクトの課題を管理するための機能です。 課題にはどのようなものがあるかというと:
- バグ報告
- ユーザーからの機能追加などの要望
- 開発者が認識している內部の改善案
ほかには...? うーん、思いつかないのでIssueにしておきます。
さて、Issueを使うと、なにかよいことがあるのでしょうか。 まず、Issue番号を使うことで、課題を指す時に誤解がありませんし、URLリンクが使えるようになります。
Issueの検索機能（Ctrl + /）を使うことで、このプロジェクトに過去にどのような問題があったのかを調べることができます。
また、「いつ」「誰が」「どんな方法で」解決したのかを検索できるようになります（このように）。
Issueが解決されたときには、"Close"ボタン押すことでIssueを閉じることができます。 ただし、これは手動でIssueを閉じる方法ですので、なるべく避けてください。 好き勝手にIssueを閉じると、 あとから振り返ったときにその問題が「なぜ」「どのように」解決されたかわからなくなり、GitHubがナレッジベースとして機能しなくなります。 Issueを手動でCloseするときには、最低限、理由を書いてください。 「どのように」を連動させる方法は、あとで学びます。
さて、Issueについての理解を深めるために、別の表現で言い替えてみましょう: 車でいうところのアクセル、仕事の動機です。 仕事は、Issueがあって初めて始まります。 Issueの数は、「Issues」タブに常に表示されていますが、 ここがゼロになると、プロジェクトは止まります。
さて、何度か「仕事」という言葉が出てきました。 バージョン管理を学ぶ準備ができたということです。
さてお気づきの通り、GitHubにはファイルが置かれています3。
（gc（Go to Code）とすれば見ることができます）。
ここに見えているファイルはすべて、既にバージョン管理されています。
正しくは、「Gitというバージョン管理システムを使って」バージョン管理されています。
じつは、バージョン管理システムがなくとも、バージョン管理はできます。
「最終版.txt」「最終版_改.txt」「最終版_改_ファイナル.txt」というのも、 手動ではありますが立派なバージョン管理です。 手動バージョン管理の問題点は何でしょうか？
「最新版がどれかわからない」 「バグまで複製される」 「粒度と安全性のトレードオフが悩みの種」... もっともらしく聞こえる問題点はいくらでも挙がりますが、 一番かんたんかつ重要な問題点は「見た目が汚くなる」です。
バージョン管理システムを導入したプロジェクトでは、 ファイルの変更は全て上書きして構いません。 後でもとに戻すことができます。 バージョン管理システムでは、ファイルの変更のことを「コミット」といいます。
GitHub上でコミットするのは簡単です:
- 編集したいファイルに移動し
- 鉛筆のボタンを押して編集モードに入る4
- 「お作法（後述）」に従ってコミットメッセージを入力
- 左下の"Commit changes"を押す
コミット時には、必ずコミットメッセージ（仕事の内容が大まかにわかるような要約文）を入力する必要があります。 このコミットメッセージの書き方にはお作法があり、例えば次のように入力します:
Write about commit message
（空行)
To explain importance of building knowledge base.
This commit resolves #123
コミットメッセージの 1行目は、コミットの要約、 3行目以降は詳細説明です。 これらは、GitHub上でファイルを編集したとき、ページ下方に見える二つのメッセージ入力ウインドウに対応しています。 それぞれ入力の仕方を解説します。
ここは、ファイルの変更履歴を一覧したときに表示されますので、 なるべくきれいに書く必要があります。 プロジェクトの方針によって決めて構いませんが、一応の慣習があります（参考: https://chris.beams.io/posts/git-commit/ ）:
- 英語で
- 頭文字は現在形の動詞で、大文字はじめる
- 末尾ピリオドなし
- 50文字以内で
一覧の状態でつらつらと読めるように「要するに何をしたのか」を書いてください。 具体的な変更内容は、ファイルの変更差分を見ればわかりますので書く必要はありません。 余談ですが、コミットメッセージを読まなくとも、変更内容の種類を大まかに伝えるための方法として、絵文字の使用も推奨されています（参考: https://medium.com/@sa.nitawaki/enjoy-your-commit-with-gitmoji-c-1eca5fe35143 ）。
コミットメッセージには、必要であれば詳細を入力することができます。
ここには、「なぜ」を書いてください。
ただし、いちばんよい方法は、Issue番号を書くことです。
コミットとは、貢献のこと。
その仕事（変更）がなされた理由は、Issueにあるはずです。
下に示すように、#につづけてIssue番号を書けば、GitHub上でIssueとコミットとの間にリンクが形成され、
Issueが自動でCloseされます。
This commit resolves #123Fix #123Close #123
Issue側から見ると、その課題が「どのように」解決されたかが明確になります（例えば#4 ）。 これは、手動でIssueを閉じる手間を省略するためではなく、ナレッジベースを育てるために有効な方法です。
さて、「上書きするのはちょっと恐いよ...」と思われた方、正解です。
上書きはやめてください。masterブランチの上書きは。
ブランチを切りさえすれば、いくらでも上書きして構いません。
ブランチを切るのは簡単です。
g c（Go to Code）と打ってコード置き場のトップに行き、
w（sWitch）を打って、お好みのブランチ名を入力してください。
何の仕事をするのかを忘れないために、ブランチ名はissue/123のようにIssue番号をつけるのがおすすめです（仕事は必ずIssueから生じることを忘れないでください）。
ブランチを作りましたか？
ブランチコントロールボタンに今作ったブランチ名が表示されているのを確認できたら、自由にファイルを編集してかまいません。
もしよければ、このチュートリアルの読みにくい箇所を書き換えてください。
Pull Requestとはなんでしょうか。 共同開発者に、変更を提案することです。 複数人での仕事は、コミュニケーションコストが伴います。 相手に変更を指示するよりも自分で変更した方が早いとき、 「このように変更しました。異論なければ受け入れてください」というふうに、仕事を進めることがてきます。
言い方を変えましょう。
先程、「masterブランチの上書きはダメ」と言いました。
では、masterブランチは、いつ更新されるのでしょうか。
Pull Requestが承認されたときです。
Pull Requestを出すのは簡単です。
g p（Go to Pull request）のあとc（Creat）とタイプするだけです。
"Campare changes"というページに飛び、"base"と"compare"というブランチボタンが表示されます。 "compare"に、あなたの作業ブランチを指定してみましょう。 あなたが自分の作業ブランチで何らかの変更（コミット）をしていれば、差分が表示されるはずです（なにも作業していなければ、差分は出ません） 変更内容がこれでよければ、Pull Requestを作ってみましょう。
メッセージのお作法は、コミットメッセージとだいたい同じです。 ただし、Pull Requestを受け取る側は、あなたが思っている以上に変更内容を理解できないものです。 「要は何をしたのか」をかいつまんで説明することを心がけてください。 「## やったこと」などのように、Markdown記法をうまく使って内容を整理しましょう。
ナレッジベースを育てるために、Pull requestのメッセージにも関連するIssue番号を書いてください。
Resolve #123と書けは、そのPull requestが承認（mergeといいます）された時に自動的にIssueがcloseされます。
- fork
- History
- Blame
- Gitの環境構築
- クリックでやっていたことをコマンドでやってみよう
- コラム: GitHubとGitの関係は？
- 参考サイト
- さらなる学びのために
1: git (reset|revert|rebase|stash|cherry-pick|bisect)は割愛します
2: 車の運転でいえば「アクセル」「ブレーキ」「ハンドル操作」といったところでしょうか
3: 「そんなこと知らないよ！」という方は、Issueに追加してください。ショートカットはgi cですよ
4: ファイル編集にもショートカットがありますが、ブラウザ上での編集は避けるべきなので解説しません