1. セミナーノート作成の手引き¶

1.3.1. レポジトリ¶

Git でファイル更新履歴を管理しているディレクトリ (フォルダ) を Git レポジトリといいます. 自分のPC内のディレクトリがGitで管理されている場合, それを ローカルレポジトリ と いいます. それ以外のレポジトリは リモートレポジトリ です. 以下では便宜上 GitHub に保存されているレポジトリをリモートレポジトリと呼びます.

1.3.2. フォーク¶

あるプロジェクトのファイルと更新履歴は (普通は) 1つのリモートレポジトリが中央管理し ています. この中央管理レポジトリを便宜的に upstream レポジトリと呼びましょう. upstream レポジトリの管理者をメンテナ (maitainer) と呼びます.

プロジェクトの開発に貢献しようとする人 (貢献者, contributor) はまず upstream を フォーク します. フォークとは, 他の人のアカウントで管理されているリモートレポジトリ をコピーし, 自分の管理下にあるリモートレポジトリを作る作業です. 次に説明する クローン をサーバー上で行うということでもあります.

GitHub ではウェブのインターフェースでフォークを行います. セミナーのレポジトリ

https://github.com/rokkopy/qe-seminar

にアクセスし, Fork ボタンを押してみましょう. (下図参照)

1.3.3. クローン¶

フォークを行なった結果, 自分が管理しているリモートレポジトリとして upstream の コピーが作成されました.

このリモートレポジトリを便宜的に origin レポジトリと呼びましょう. 今後の作業は,

• origin を更新する (プッシュ)
• origin -> upstream に更新を反映するよう申請する (プルリクエスト)

という2段階の作業によって行います.

作業の第一段階を進めるために, origin レポジトリを手元のPCにコピーしましょう. Git ではレポジトリのダウンロード (コピー) をクローンといいます. 現在公開されている最新版のファイルだけでなく, 過去の履歴も含めてまるごとコピーされます.

適当なディレクトリで次のコマンド (git@ ... 以下は上図の赤枠内を参照):

$ git clone git@github.com:[YOUR USERNAME]/qe-seminar.git

を実行すると, カレントディレクトリに qe-seminar というディレクトリ (ローカルレポジ トリ) が作成されます. このディレクトリの名前は変更しても問題ありません.

1.3.4. add & commit¶

これで, プロジェクトに手を加える準備が整いました. Git レポジトリ内では,

• ファイルの追加・編集
• $ git add コマンドの実行 (変更したファイルを git に記録するように指示)
• $ git commit コマンドの実行 (変更を履歴として残す)

を繰り返します. 作業中のファイルが保存されるローカルレポジトリでは, 変更履歴は細かく残しておくほうがよいでしょう. リモートに反映させるときには あまり細かい履歴が残ると困るケースもあるので (逡巡が見えてしまう ... ), ローカルの履歴を書き換える操作が可能です. 当面そのような履歴の美しさにこだわる必要はないでしょう.

git add はコミットに含める (インデックス) するファイルとして登録する操作です. git commit はインデックスされたファイルについて変更を履歴として保存する操作です. add されていないファイル (例えば自分のためのメモみたいなファイルとか) は無視して, 本当に必要な変更だけを記録することができます.

コミットには必ずメッセージが要求されます. メッセージを入力する簡単な方法は,

$ git commit -m "Message Here"

とやることです. どんな変更を記録したいかが分かる簡潔なコメントを書きましょう.

Git のコマンドをまったく触ったことがないという方は, まず手始めに tryGit の15分コースを実践してみてください.

https://try.github.io/levels/1/challenges/1

また, Atlassian Git チュートリアル 「Gitの基本」 に目を通しておいてください.

1.3.5. プル¶

もしかすると, 自分が作業をしている間にも他の人が作業して upstream (プロジェクトの中心となるリモートレポジトリ) が更新されているかもしれません. upstream の更新をこまめにチェックするというのは大切なことです.

クローンしただけでは, upstream からフォークしたものだという情報が記録されていませんので, シェルコマンド:

$ git remote add upstream https://github.com/rokkopy/qe-seminar.git

を実行して, upstream の情報をローカルレポジトリに追加しましょう. このようにしてから, 作業中の変更をコミットし,

$ git pull upstream

を実行してください. upstream の更新をローカルレポジトリに反映することができます.

注意. プルというのはリモートのダウンロード (fetch) + マージ (merge) を同時に やるコマンドです. 他の人が更新したファイルと同じファイルを自分も更新していた場合には, コンフリクト が発生し, マージが失敗します. 失敗の状況を確認するために:

$ git status

コマンドを実行し (このコマンドはレポジトリの状態を確認するために頻繁に使います), コンフリクトが発生しているファイルを認識しましょう.

次のような部分があるはずです.:

<<<<<<< HEAD
<div id="footer">contact : email.support@github.com</div>
=======
<div id="footer">
  please contact us at support@github.com
</div>
>>>>>>> upstream/master

======= の上部が手元にあったコードで, 下部が upstream にあったコードです. どちらのコードを残すべきかを検討し, コンフリクトを解消してください. コンフリクト 解消のために使えるツールの解説を含め, 詳細は Pro Git 「ブランチとマージの基本」 を参照してください.

コンフリクトが解消されたら, それを Git に伝えるために, git add と git commit を 行います.

1.3.6. プッシュ¶

たくさんの試行錯誤と推敲, たくさんの git add と git commit を 繰り返した結果, ローカルの内容をインターネットに公開してよいレベルに達しました. このとき, いきなり upstream に公開するのではなく, 一度 origin レポジトリ (自分が 管理しているリモートレポジトリ) に公開するという手順を取ります. (フォーク型のワークフロー を採用していることを思い出してください).

この段階で使うコマンドが git push です. git pull を実行して, あなたの 作業が upstream の最新版の成果に基づくものであることをもう一度確認してください. その後,

$ git push origin master

を実行します. これで, origin = upstream + あなたによる更新 という状態になりました. 要するに, プッシュ というのは, 手元の更新をリモートレポジトリに反映させる作業です.

補足. upstream は git remote add upstream ADDRESS とやりましたが, origin についてはクローンした時点で自動的に追加されていますので, このような操作は不要です. どのようなリモートレポジトリが登録されているか心配な人は, 次のコマンドの結果を確認してください ($ に続く行が入力してほしい行, それ以外はコマンドの出力):

$ git remote show
origin
upstream
$ git remote show upstream
* remote upstream
Fetch URL: https://github.com/rokkopy/qe-seminar.git
Push  URL: https://github.com/rokkopy/qe-seminar.git
HEAD branch: master
Remote branches:
gh-pages tracked
master   tracked
Local ref configured for 'git push':
master pushes to master (up to date)

最後の部分は異なるかもしれませんが, だいたい上のような出力になるはずです.

1.3.7. プルリクエスト¶

今, origin は upstream よりも一歩先に進んだ状態になっています. このとき, メンテナに 対して origin の情報を upstream に反映させるように促す行為が プルリクエスト と呼ばれるものです.

これは, GitHub の origin のサイトにレポジトリページか upstream のレポジトリページ に行けばこれまでなかったボタンが現れているはずです.

ボタンを押し, 修正に関するコメントを書いた上でプルリクエストを発行してください. メンテナーに通知され, コードレビューの後に問題がなければ upstream が更新 (マージ) されるでしょう. 問題があれば, GitHub 上でディスカッションを行い, マージ可能なレベルに達するまで必要な修正を施します.

1.3.8. おまけ: ビルド¶

このセミナーのビルド済みのノートは Github Pages で公開されています. これには Travis CI というサービスを利用しており, qe-smemina/master に対するプルリクエストがマージされた時点で, 自動的にビルド・公開されます. したがって, ノート作成者はプルリクエストを送って,コードレビュー後にマージをすればよく, サイトの公開に関する作業を気にする必要はありません.

1.3.9. まだ書いていないこと¶

• ブランチについて
• git rebase による履歴の修正
• マージコンフリクトの解消
• github pages に origin の内容をホストする方法

1.3.10. リンク集¶

1.4.1. リンク¶

• http://sphinx-doc.org/rest.html