====================================
Github の使い方
====================================

Github とは
===========================

Git がファイルリポジトリを操作するためのコマンド群であることは述べましたが，
``git init``,  ``git add``, ``git commit`` といった流れは，
あくまで *自分の手元の計算機に* バックアップを取るための操作で，
外部へ記録を移管したりしているわけではありません．つまり自分の計算機が
壊れてしまった場合，全ての変更記録が失われることになります．
そのようなことになる前に，リモート操作で外部に保存をしましょうというのが
ここで述べる趣旨になります．
このようなリモート操作は現在は，Web アクセスを介して行われるのが今風の使い方です．
これをホスティングサービスとして実施してくれている最大手が *GitHub* と呼ばれる
Webサービスです．

まずは，

https://github.com

をアクセスしてください．


.. note::

   なお，Github ヘルプの公式ドキュメントはこちらから読めます

   https://help.github.com/ja/github/getting-started-with-github



導入
===========================

とりあえず， `GitHub` のアカウントを手に入れましょう．
まだアカウントを持っていない人は sign up を選択してください．
そうでない場合は， sign in をしてログインしてください．

以下では sign up の流れについて説明します．
必要なものは有効な *メールアドレス* になります．以降リポジトリ変更などのお知らせは，
このメールアドレスに来ます．
学校のメールアドレスもしくは gmail 等のメールアドレスを指定すると良いでしょう．
下記のようにユーザー名とメールアドレスを適宜設定してください．

.. image:: githubjoin1.png

次に料金プランを聞かれますが，ここでは無料のプランを選ぶで問題ありません．

.. image:: githubjoin2.png

最後に嗜好などを聞かれますが適宜答えて ’Submit’ ボタンを押してもらって大丈夫です．
GitHub から確認のメールがくるので，そのリンクを踏んで登録作業終了になります．
あとは，リモートリポジトリが簡単に作れるようになります．
最後に下のような画面にたどり着けば アカウント作成は終了です．

.. image:: githubjoin4.png

   


基本的な使い方
=============================


既存のローカルリポジトリを GitHub に登録する場合
--------------------------------------------------------------------------------------------

さて，それでは，先ほどの例題を使って `GitHub` を使ってみましょう
とりあえず，手元の計算機で作業している Git のリポジトリをローカルリポジトリと定義しておきます．
また，バックアップとして保存を行いたい `GitHub` 上のリポジトリをリモートリポジトリとします．

.. image:: githubjoin4.png

の "Start a Project" を選んでみてください．リモートリポジトリの作成画面に遷移します．
ここでは，HelloPython という名前のプロジェクトとしましょう．

.. image:: createproj2.png

名前をいれたら， "Create repository" ボタンを押します．

しばらく待つと下記のような画面に遷移します．
ここでは https 通信を使います．（ssh 通信を使いたい場合はおまけを参照のこと）

.. image:: createproj3.png

すると，ローカルリポジトリと GitHub 上のリモートリポジトリとをどのように紐付ければよいかが出ていることがわかります．

* "... or create new repository on the command line"

  これは新しくローカルリポジトリを始めるやり方です．
  下記，1.〜3. でローカルリポジトリを作成し，それを 4., 5. の手続きで紐付けてアップロードするというやり方になります．
  
  1. ``README.md`` と呼ばれるファイルを(エディタなどで)作成します（しなくてもできますが）．
  2. ``git init`` でフォルダをリポジトリ登録し，
  3. ``git add`` , ``git commit`` を行い，作業している計算機のローカルリポジトリを更新します．
  4. 最後の2行は，作業しているローカルリポジトリと GitHub 上のリポジトリ（リモート先）を紐付ける作業(``git remote``)と
  5. GitHub へのアップロード作業 ``git push`` を行っています．

* "... or push an exisiting repository from the command line"

  このやり方は既存のローカルリポジトリをリモート側に登録するやり方です．
  すでに ``git commit`` 作業が行われていることが前提になります．

  1. 紐付け作業の ``git remote`` と，
  2. アップロード作業の ``git push`` が記載されています．


前述の Git の項では， ``git commit`` まで行っているので，
後者の作業がメインとなります．
ただし Github では ``REAME.md`` を作成しておくのがお作法なので，
このファイルを追加した上で， ``git add``, ``git committ``
(ここまでがローカルリポジトリでの git 登録作業) し，
GitHub への紐付け ``git remote`` と，アップロード ``git push`` を
行ってみます．

Jupyter のターミナルへ戻って， ``~/sf_share/ProjectHoge`` へ移動して
ください．

.. code-block:: sh

   $ cd ~/sf_share/ProjectHoge
   $ echo "# HelloPython" >> README.md

で， ``README.md`` を作成します．

ここで， ``git status`` をとると ``REAME.md`` が追跡されていないファイルとなりますので，

.. code-block:: sh

   $ git add README.md
   $ git commit -m 'Add README.md'

をして，ローカルリポジトリでの登録作業を行います． 


こんな感じになります．

.. image:: gitremote0.png

次に ``git remote`` で，ローカルリポジトリを リモート側の ``HelloPython`` プロジェクトに紐付けます．

.. code-block:: sh

   $ git remote add origin git@github.com:HogeHogeFooBar2018/HelloPython.git
   $ git push -u origin master

なお，この最初の紐付け作業が終わってしまえば，どこに紐付いているかは git さんの管理化に置かれるので，

.. code-block:: sh

   $ git push

だけで，バックアップはできるようになります．


うまく通信が行えれば，こんな感じになります．

.. image:: gitremote1.png

最後に GitHub リポジトリの web ページをリロードすると，このような感じになります．
   
.. image:: gitremote2.png

これで，リポジトリがアップロードされ，バックアップ完了です．

このリポジトリは，紐付けは済んでいるので，あとはファイル変更，
``git add``, ``git commit``, ``git push`` のループを回していけばOKです．



リモートリポジトリとの同期
--------------------------------------------------------------------------------------------

リモートリポジトリの方が更新が進んでいる場合は，
（複数サイトで更新作業を行っているとしばしば起こる）
最新版に更新したいことが多くなります．この場合紐付けが終わっているのであれば
``git pull`` を行うことで，同期がとれます．
ただし，リモートの更新で現在の編集作業が上書きされる可能性があるので，
作業開始前に確認することが重要です．
``git pull`` 自体は非常に簡単で，紐付けが終わっているリポジトリであれば

.. code-block:: sh

   $ git pull

を行うことで，最新の状態に保つことができるようになります．



Github 上のリモートリポジトリを複製して使う
--------------------------------------------------------------------------------------------

次に，リモートリポジトリを複製 (``git clone``) してから使う方法を考えます．
これは，別の計算機でクローンを行ってから開発したい場合などに用います．
*課題での使い方はこれが該当します．*


先ほどの HelloPython プロジェクトをクローンして，ローカルマシン上の
別ディレクトトリに複製してみましょう．

リポジトリ画面の右上に "Clone or download" ボタンがあります．
これを押すと，リモートリポジトリ名がでてくるので，この文字列を
コピーします．

次に Jupyter の端末での作業に移ります．
``~/sf_share/`` 上に ``HelloPython`` プロジェクトを展開してみます．
これには ``git clone`` を用います．
``git clone`` の引数にはコピーしたリモートリポジトリの文字列を与えます．

.. code-block:: sh

   $ cd ~/sf_share
   $ git clone git@github.com:HogeHogeFooBar2018/HelloPython.git

のようにすれば，複製ができます．
あとは，このフォルダでいじり， ``git add``, ``git commit``, ``git push`` のサイクルを回せばOKということになります．




おまけ: SSH による通信の設定
======================================================

Github は，通信において `https` プロトコルと `ssh` プロトコルが
利用できます．
特にリモートリポジトリにコードをアップロードする (`git push` する) 場合
`https` プロトコルだと，常にアカウント名とパスワードを聞かれます．
これが煩わしい場合には， `ssh` を使用することを考えます．
`ssh` 通信では，開発を行っているホストの信用情報が必要になるので，
開発を行っているホストの公開鍵を GitHub 側に登録する必要があります．


使用端末の公開鍵作成
------------------------------------------------------

まず，ssh を利用するには，使用端末で SSH の公開鍵を作成する必要があります．
GitHub は，公開鍵暗号としては RSA, DSA, ECDSA, ED25519 などを受け付けますが，
標準の RSA 公開鍵は，2048 bit長の鍵だと脆弱なので，もっと長い鍵を使うか，
ED25519 といった鍵を使いましょう．ここでは ED25519 による登録を行います．

使用端末での Jupyter で，ターミナルを開いてください．
この端末上で鍵を生成します．
鍵を生成するには，以下のようなコマンドを投入します．

.. code-block:: sh

    ssh-keygen -t ed25519 -C 'shouno@uec.ac.jp '

最後の -C オプションの引数は自身のメールアドレスを入れてください．

鍵の生成中に，どこに鍵を置くか（標準は ~/.ssh）と，アクセスするための
パスフレーズを聞かれます．
鍵の置き場所は標準のままで，パスフレーズは適当なパスワードを入れてください．

.. image:: sshkeygen1.png

鍵生成が終われば，ホームディレクトリ (~/) に ``.ssh`` フォルダが生成され，
そこに秘密鍵ファイル ``~/.ssh/id_ed25519`` と公開鍵ファイル ``~/.ssh/id_ed25519.pub`` がペアで生成されているはずです．
``cat`` コマンドなどで確認することができます．

.. image:: sshkeygen3.png


Github への SSH 公開鍵の登録
------------------------------------------------------

次に公開鍵 `~/.ssh/id_ed25519.pub` の内容を github へ登録します．

まず， GitHub に前に設定したアカウントでサインインします．
次に画面右上にあるアイコン(＋の隣にある奴)
から `Setting` を選びます．

.. image:: githubsetting2.png
           
           
続いて，左の Personal Settings 欄のなかの "SSH and GPG Keys" を選択します．
すると下のようなページに遷移します．

.. image:: githubsshregister1.png

あとは，"New SSH Key" ボタンを押して，出て来る画面に
先ほどの公開鍵となんらかのタイトルをつければ終了です．

.. image:: githubsshregister2.png

鍵を登録するとこんな感じになります．
``~/.ssh/ed25519.pub`` を記載し "Add SSH Key" ボタンを押して登録します．

.. image:: githubsshregister3.png

鍵のタイトルは適当でよいです．   

最後にきちんと通信出来るかどうかを確認したければ

.. code-block:: sh
   
   ssh -T git@github.com

を実行してみてください．途中，github を知っているホストに登録するか？という
質問と，パスフレーズを聞かれるので，前者は ``yes`` 後者は，鍵生成したときの
パスフレーズをいれることで，通信が行われます

うまく通信ができていれば 

''Hi xxxxxxxx! You've successfully authenticated, but Github ...''

というメッセージを受け取るはずです．