manabuyasuda/GitHubの使い方

## GitHubの使い方
# GitHub
## 用語集
* repository（リポジトリ）：ファイルや変更内容が保存される場所のことで、パソコン内にあるものをローカルリポジトリ、GitHubなどローカル以外のサーバ上にあるものをリモートリポジトリと呼ぶ
* 作業ディレクトリ：リモートリポジトリをclone（複製）したディレクトリ（ローカルリポジトリ）のことで、作業中のファイルが含まれる
* ステージングエリア：ローカルリポジトリのなかにあるコミットをする予定のファイルを仮置きしておく場所のこと
* Gitディレクトリ：ステージングエリアにあるファイルをコミット（登録）して、変更が確定したディレクトリ
* branch（ブランチ）：並行して作業を進めるためにmasterブランチからコミットの流れを分岐すること（最終的にmasterブランチにマージ（合体）される）

---

* clone（クローン）：リモートリポリトジを複製して、パソコン内に新しいローカルリポリトジを作成すること
* fork（フォーク）：GitHub上の他人のリモートリポリトジを編集するために、自分のアカウントにリモートリポリトジのコピーを作成すること
* commit（コミット）：変更された記録をリポジトリに登録（バージョン管理）すること
* push（プッシュ）：ローカルリポジトリのコミットをアップロードしてGitHub上のリモートリポジトリに反映させること
* marge（マージ）：複数のブランチやコミットを合体させること
* Pull Requet（プルリクエスト）：自分がおこなった変更をマージしてもらうようにリクエストをすること
* checkout（チェックアウト）：ブランチの切り替えなどによって作業ディレクトリを指定したコミットの状態にすること
* pull（プル）：GitHub上のリモートリポジトリからコミットをダウンロードしてローカルリポジトリに反映させること
* conflict （コンフリクト）：複数人が同じ場所を変更してしまうことから発生するGitが自動でマージできなくなった状態のこと

---

* Userアカウント：個人のアカウントのことで、Organizationアカウントのメンバーになれたり、リポジトリの共同作業者（Collaborator）になることができる
* Organizationアカウント：複数人の管理者や共同作業者を設定することができる会社やオープンソース向けのアカウントのこと
* Owners：Organizationアカウントで自動的に作られるすべての権限をもったチームのこと
* Read Access：閲覧とclone、wikiの編集をする権限のこと
* Write Access：閲覧とclone、pushとwikiの編集をする権限のこと
* Admin Access：閲覧とclone、pushとwikiの編集、メンバーの追加をする権限のこと

---

* Issue（イシュー）：作業に関する問題を話し合うために使用される掲示板のような機能のことで、issueを終了させることをcloseという
* Milestone（マイルストーン）：Issueページにある大まかな期限を設定する機能のこと
* Label（ラベル）：Issueページにあるbug（不具合）やquestion（質問）などの分類分けをする機能のこと
* Assignee（アサイニー）：IssueページにあるIssueの担当者を割り振る機能のこと
* diff（ディフ）：変更された差分を確認する機能のことで、追加された文字列とファイル名には`+`と`+++`が、削除や変更された文字列とファイル名には`-`と`---`が表示される

## Issueページ
メニューからIssues（イシュー）を選択します。Issueページでは以下のような機能を使用することができます。

* Milestone
* Issue
* Label
* assignee
* wiki

### Milestone
IssueページにあるMilestone（マイルストーン）でスケジュールの大まかな区切りを設定します。例えば機能単位やリリースの予定日などです。「New milestone」ボタンから作成します。

Milestoneでは以下のような項目を入力します。

* Title（タイトル）
* Description（詳細）
* Due Date（期限）

### Issue
Milestoneを作成したら、そのなかにIssueを作成します。Issueページトップの「New Issue」ボタンから作成します。Issueを作成した時点、もしくはあとからMilestoneと担当者を設定できます。

Writeタブで内容の入力、PreviewタブでMarkdownをプレビュー、「Comment」ボタンで完了します。

よく使う機能として以下のようなものがあります。

* シンタックスハイライト
* Issueのリンク
* チェックボックスの作成
* 画像のアップロード

コードにシンタックスハイライトを適応させる場合には以下のように記述します。使用出来る言語は[linguist/languages.yml](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml)から確認できます。

```scss
.foo {
  padding: 0;
  .bar {
    padding: 0 1rem;
  }
}
```

IssueのコメントやGitHubでのコミットメッセージなどでは`#1`のようにシャープにIssue番号をつけることで自動でそのIssueへのリンクを貼ることができます。URLのみを入力した場合にもテキストはURLになりますがリンクを生成してくれます。

Issue内でチェックボックスを作成できます。

```
[ ] 半角スペースを入れるとチェックボックスを作成できる
[x] xを入れるとチェック済みのチェックボックスを作成できる
```

コメント欄に画像をドラッグ&ドロップすると画像がGitHubにアップロードされて自動で画像用のMarkdownが生成されます。PhotoshopやIllustratorなどのあらゆる種類のファイルをpushできます。1つのリポジトリにつき合計1GB、1つのファイルにつき100MBまでと制限されているのでDropboxの共有フォルダを使用するなどの対策が必要な場合もあります。

議論が終わったら「Close issue」ボタンか、コミットメッセージにIssue番号とキーワード（fixやcloseなど）を入力することでIssueをclose（終了）します。

```
fix #1
```

### Label
Label（ラベル）はIssueを仕分けしやすくする機能です。任意のLabelだけを一覧表示させるといったこともできます。自分でLabelを作成することもできます。

### Assignee
Assignee（アサイニー）はIssueの担当者を割り振る機能のことです。1つのIssueにつき1人を担当者として指定できます。Issue一覧で「Assignee」をクリックすると特定の担当者のIssueだけを一覧表示することもできます。

### wiki
wiki（ウィキ）はWikipediaのように複数人で編集することができるコンテンツを作成できる機能です。wikiとIssueとREADMEの役割の違いは以下のようになります。

* wiki：リポジトリで作成しているものの詳細な使い方や注意点に関するドキュメント
* Issue：リポジトリで作成しているもののバグや機能の追加のメモ
* README：リポジトリで作成しているもののアピールや説明、簡単な使い方など

wikiの作成は「wiki」アイコンをクリックして「Create the first page」をクリックします。cloneをしてローカルで編集することもできます。ただし、日本語の扱いでトラブルを起こすケースがあるので、ページのタイトルはできるだけ英語でつけましょう。

wikiには自動で目次がつけられます。

## コンフリクトの解決
conflict （コンフリクト）は競合という意味で、Pull Request元（リモートリポジトリ）との間で変更内容が重なってしまい自動的にマージできなくなった状態のことです。コンフリクトの解決は担当者を事前に決めておくか、一般的にはあとからpushをする人が解決します。

コンフリクトした内容は`<<<<<<< HEAD`から`=======`と、`=======`から`>>>>>>> コミットID`のように表示されます。どちらかを削除（`HEAD`なども削除）したらファイルをステージングしてからコミットとpushをおこないます。

Pull Requestを放置していてmasterブランチとの差が進んでしまった場合にもコンフリクトを起こすことがあります。この場合はローカルリポジトリのmasterブランチとPull Request元のトピックブランチとの間でマージをします。

手順としては、masterブランチに切り替えてpullをおこない最新のコードにします。コンフリクトの解決方法は同じです。Pull Requestのマージはできるだけ送られてから時間をおかずにしておきましょう。

## Pul Request
Pull Request（プルリクエスト）はリポジトリのソースコードなどの修正や機能の追加などを送る機能です。prやプルリク、プルリなどと呼ばれます。

Pull Requestには2つのパターンがあります。

* 共有のリモートリポジトリを自分のリモートリポジトリとしてforkしてからPull Requestをする
* 共有のリモートリポジトリでブランチを作成してからPull Requestをする

前者はOwnerやCollaboratorでない場合に使用されます。前者の方が後者に比べて操作がやや複雑なため、権限に問題がなければ基本的には後者の方法を使用しましょう。

### 共有のリモートリポジトリを自分のリモートリポジトリとしてforkしてからPull Requestをする
他の人が作っているリポジトリで自分に編集をする権限がない場合には自分のリモートリポジトリにforkしてからPull Requestを送ります。

1. リポジトリを表示して「Fork」ボタンをクリックします
1. 自分のアカウントのリモートリポジトリとしてコピーされるのでコードを修正します
1. 自分のリモートリポジトリにpushします
1. GitHubの「Pull Request」をクリックします

### 共有のリモートリポジトリでブランチを作成してからPull Requestをする
そのリポジトリを編集できる権限を持っている場合はブランチを作成して、そのブランチから元のブランチにPull Requestを送ります。

1. リポジトリをcloneします（リモートリポリトジを複製して、パソコン内に新しいローカルリポリトジを作成すること）
1. 新しいブランチを作成します（新しいブランチにチェックアウトした状態にします）
1. originにpushします
1. GitHubのリモートリポジトリに作成したブランチが追加・表示されているので「Compare & pull Request]をクリックします
1. タイトルと内容を入力して「Create pull request」をクリックします

Pull Requestが採用されたらブランチは必要ないので削除しましょう。残しておくと次回に修正する時に削除していいブランチなのか分からなくなってしまいます。

### コミットの粒度とコミットメッセージ
コミットは粒度に気をつけましょう。1つの機能（例えばコンポーネントごとに）を目安にするといいでしょう。

コミットをする時に入力するコミットメッセージはタイトルだけで内容が判断できるように簡潔かつ明瞭につけましょう。

### レビュー
Pull Requestが送られてきたらコードレビューをおこない、マージをします。レビューは以下のような点に気をつけるといいでしょう。

* validationをおこないエラーが出ていないか
* 命名規則やメソッド名などが適切か
* コメントが適切に書かれているか
* 意図がわからないコードがないか
* パフォーマンスが悪くならないか

### ラインコメント

コード1行に対してコメントを挿入することをラインコメントと呼びます。コメントを残したい行をクリックすると+マークが表示されるのでクリックします。コメント欄にコメントを入力して「Comment on this line」をクリックで送信されます。

ラインコメントも通常のIssueコメントと同様にNotificationが送られます。返信したい時は「Add a line note」をクリックします。ブランチ上で修正をしてリモートリポジトリにpushをすればPull Requestも最新の内容に上書きされます。ラインコメントも消えます。ラインコメントはConversationタブ確認することができます。

### マージ後の処理
masterブランチをチェックアウトしてからpull（GitHub上のリモートリポジトリからコミットをダウンロードしてローカルリポジトリに反映させること）をします。マージをした後はブランチは必要ないので「Delate branch」をクリックしてブランチを消去します。マージしてから処理を取り消したい場合は「Revert」をクリックします。

## ブランチモデル
ブランチの作成方法として「Git Flow」と「GitHub Flow」という有名なブランチモデルがあります。

### Git Flow
Git FlowはVincent Driessen氏が「[A successful Git branching model](http://nvie.com/posts/a-successful-git-branching-model/)（[日本語訳](http://keijinsonyaban.blogspot.jp/2010/10/successful-git-branching-model.html)）」で提唱したブランチモデルです。

Git Flowでは5つのブランチを作成して開発します。

1. develop
1. feature
1. release
1. master
1. hotfix

開発はdevelopブランチとfeatureブランチでおこないます。メインのブランチはdevelopブランチになりますがこのブランチでpushすることはほとんどありません。featureブランチを作り、このブランチからdevelopブランチへPull Requestを送ります。Pull Requestを送られたら開発者はコードレビューをおこない、修正が必要な場合はfeatureブランチに修正をpush、修正済みのコードが新しいPull Requestとして使用されます。

開発が終盤に近づいたらreleaseブランチに分岐します。このブランチではリリースに向けてのREADMEの修正やバグフィックスなどをおこないます。

リリースが終わったらreleaseブランチからmasterブランチへマージしてリリースのバージョンのタグをつけます。masterブランチはこのリリース作業の時にしか更新されません。同時にreleaseブランチからdevelopブランチにもマージします（タグは不要）。これでdevelopブランチは開発を続けることができるようになりました。

リリース後に緊急度の高いバグ修正などがあった場合はhotfixブランチを使ってリリースします。リリース後はreleaseブランチと同様にhotfixブランチからmasterブランチへタグをつけてマージ、developブランチもマージします。

### GitHub Flow
GitHub FlowはGitHubで働いているScott Chacon氏が「[GitHub Flow](http://scottchacon.com/2011/08/31/github-flow.html)（[日本語訳](https://gist.github.com/Gab-km/3705015)）」で提唱したブランチモデルです。

GitHub Flowはとてもシンプルなブランチ構成でmasterブランチとトピックブランチの2つからなっています。

masterブランチは大元のブランチで、このブランチにマージされたらすべてリリースされます。

開発で使用されるのはトピックブランチと呼ばれるブランチです。説明的な名前をつけたブランチを作成して、レビューしてもらいたいタイミングやmasterブランチに取り込んでもらいたいタイミングでPull Requestを送ります。

## GitHubのコミュニケーション
文字だけでは誤解をまねく可能性があるので、GitHubでは絵文字や略語がよく使われます。

### emoticon
emoticon（エモティコン）とはいわゆる絵文字のことです。GitHubではemoticonの名称を`:`コロンで囲むことで絵文字を表示することができます。

```
:smile: // 笑顔
:innocent: // 天使
:+1: // いいね！
:clap: // 拍手
```

コロンに続けて1文字目を入力すると候補が表示されます。使える絵文字は[EMOJI CHEAT SHEET](http://www.emoji-cheat-sheet.com/)から確認することができます。絵文字をクリックするとクリップボードにコピーされます。

### LTTM
[LTTM](https://chrome.google.com/webstore/detail/lttm/jdidcgkdggndpodjbipodfefnpgjooeh?hl=ja)はChromeの拡張機能で寿司ゆきや地獄のミサワのような画像を貼り付けられます。寿司ゆきは`!s`から、地獄のミサワは`!m`を入力すると候補が表示されます。

### 略語

* 「LGTM」はLooks good to meの略で「良さそうに見えます」のようなニュアンスでレビューの終了や承認を表す場合もある
* 「IMO」はIn my opinionの略で「私が思おうに」という意味
* 「AFAIK」はAs far as I knowの略で「わたしの知る限りでは」という意味
* 「IMHO」はIMOにHumble（控えめ、謙虚な）を加えた「つまらない意見ですが」のようなニュアンスで、同じ略称でIn My Honest Opinionの略の「率直に言うと」もあるので文脈によって解釈します
* 「NP」は	No problemの略で「気にしないで、どういたしまして」のようなニュアンス
* 「Nitpick」と「NITS」はあら探しをするという意味の動詞で小さなことを指摘するという意味
* 「WIP」はWork In Progressの略で「まだ作業中なので細かいツッコミは待ってね」のようなニュアンス
* 「MUST」は「明らかに間違えているので必ず直しましょう」という意味
* 「SHOULD」は「深刻な間違いではないですが直したほうがいいでしょう」という意味
* 「ETA」はEstimated time of arrivalの略で「作業の完了予定時刻」のこと
* 「PTAL」はPlease take another lookの略で「再度ご確認ください」という意味
* 「e.g.」はFor exampleの略で「例えば」という意味
* 「cf.」は「参照」という意味

[Git - 英語のコメントや issue で頻出する略語の意味 (FYI, AFAIK, ...) - Qiita](http://qiita.com/uasi/items/86c3a09d17792ab62dfe)

大まかな方向性が分かるくらい（例えば50%くらい）で「WIP」とつけてPull Requestをする方法があります。仕様や要件からズレていないか確認できますし、間違っていた場合も修正コストが低くてすむようになります。

## cloneからのPull Request
AさんとBさんがあるリモートリポジトリをforkし、並行して作業をすると仮定します。ブランチモデルはGitHub Flowを採用します。

1. masterブランチからトピックブランチを分岐させて開発用のdevelopブランチとします
1. developブランチからAさん用にdevelop_aブランチ、Bさん用にdevelop_bブランチを作成します
1. AさんとBさんはリモートリポジトリをcloneし、それぞれのブランチで開発をおこないます
1. Aさんは修正・追加した内容をステージングエリアに移動させてから、develop_aブランチにコミットします
1. コミットした内容をリモートリポジトリのdevelop_aブランチへpushします（これでリモートとローカルの両方に反映されました）
1. リモートリポジトリのdevelopブランチにdevelop_aブランチの内容を反映させるためにPull Requestをします
1. コードレビューをおこない承認されたらPull Requestをマージします（これでdevelopブランチに反映されました）
1. Bさんはcheckoutをおこないdevelop_bブランチからdevelopブランチに切り替えます
1. pullをおこない更新されたdevelopブランチ（リモートリポジトリ）の情報をローカルリポジトリへ反映させます
1. checkoutをおこないdevelop_bブランチに切り替えます
1. 更新されたdevelopブランチの情報をdevelop_bブランチにマージをして反映させます
1. コンフリクトを起こした場合は、あとからpullをしたBさんが解決します
1. 再び開発を続けます


## forkからのPull Request
オープンソースプロジェクトなど、直接コミットする権限をもっていない場合はfork&cloneモデルを使います。以下はSourceTreeを使用した場合の手順です。注意点として、

* fork元はコピーしたい（またはした）リモートリポジトリのことです
* forkしたときにできるmasterブランチで開発はしません
* ブランチを新規作成してから開発をおこないます
* fork元の変更をmasterブランチで追跡する必要があります

### forkして追跡する

1. forkしたいリポジトリのページで「fork」ボタンを押します（自分のリモートリポジトリとしてコピーされる）
2. masterブランチはfork元の状態を保っておくので、新しくブランチ（仮にdevelopブランチとする）を作成します（「ブランチ」を右クリックで「分岐を追加…」か、メニューの「ブランチ」を選択する）
3. fork元のforkURLをコピーします
4. 「リモート」を右クリックして「リモートを追加…」をクリックします
5. 「リモートの名前」を「upstream」、URLはコピーしてきたURLをペーストします
6. 「upstream」を右クリックして「upstreamからフェッチ」を選択します（upstream/masterが生成される）
7. masterブランチを右クリックして「リモートブランチを追跡」から「upstream/master」を選択します（これでfork元の変更が随時反映される）

### Pull Request

1. developブランチからdevelop_testブランチを作成します
2. develp_testブランチをチェックアウトした状態で作業を進めます
3. developブランチをチェックアウトしてから、develop_testブランチを右クリックして「現在のブランチにdevelop_testブランチをマージ」を選択します（作業内容がdevelopブランチに反映されました）
4. masterブランチを右クリックして「現在の変更をmasterにリベース」を選択します
5. developブランチでpushします（これがPull Requestの元になるブランチになります）
6. 自分のGitHubページから、Pull Requestしたいブランチを選択してから左にあるアイコンをクリックします
7. タイトルと説明を入力したら「Create pull request」ボタンをクリックします
8. Pull Requestがマージされてfork元が更新されたら、masterブランチにチェックアウトしてからpullします（これでfork元とmasterブランチは同じ状態になります）
9. developブランチにチェックアウトしてから、masterブランチとマージします

## GitHubのテクニック

### ショートカット
GitHubをブラウザで表示している時にキーボードの?を押すとその画面で使用できるショートカットが表示されます。

### Gist
GistはGitHubの機能の１つでコードを共有することができます。ディレクトリを作ることはできませんが、バージョン管理やシンタックスハイライト、シークレットモードや複数のファイルで保存することができます。

シークレットモードは検索エンジンにクロールされない、Gist一覧に表示されなくなる特徴があります。ただし、URLが分かれば見れてしまうので注意しましょう。

### ホワイトスペースの差分を表示しない
diffのURLの末尾に`?w=1`を付け足すとホワイトスペース（空白文字、タブ、改行文字）の差分を表示しなくなります。HTMLなどホワイトスペース（インデントなど）が頻繁に変更される言語で特に有効な機能です。

## .gitignoreファイルでバージョン管理しないファイルを指定する
OSが自動で作成するファイルなど、共有する必要のないファイルは.gitignoreというファイルをプロジェクトトップの階層に保存することで指定できます。

homebrew（ホームブリューまたはホームブルー）を使用している場合にはgiboという.gitignoreを自動で生成してくれるツールがあります。homebrewでgiboをインストールするには、

```bash
brew install gibo
```

以下のようにOSやエディタ名を入力します。

```bash
gibo OSX Windows SublineText Vim Emacs >> .gitignore
```

## 参考リンク
* [GitHub Cheat Sheet（日本語訳）](https://github.com/jposts/github-cheat-sheet)
* [Web制作者のためのGitHubの教科書](http://www.amazon.co.jp/Web%E5%88%B6%E4%BD%9C%E8%80%85%E3%81%AE%E3%81%9F%E3%82%81%E3%81%AEGitHub%E3%81%AE%E6%95%99%E7%A7%91%E6%9B%B8-%E3%83%81%E3%83%BC%E3%83%A0%E3%81%AE%E5%8A%B9%E7%8E%87%E3%82%92%E6%9C%80%E5%A4%A7%E5%8C%96%E3%81%99%E3%82%8B%E5%85%B1%E5%90%8C%E9%96%8B%E7%99%BA%E3%83%84%E3%83%BC%E3%83%AB-%E5%A1%A9%E8%B0%B7-%E5%95%93-ebook/dp/B00QPSXY1I/ref=sr_1_3?s=books&ie=UTF8&qid=1453903533&sr=1-3&keywords=github)