🔰

布教Git(hub と VSCode)

2022/12/01に公開約13,400字

「『名前を付けて保存』→『改訂版, 新改訂版, 最終決定版2.docx』」な皆様,いかがお過ごしでしょうか

はじめましての方は初めまして,かさいさん (@streamwest1629)です.今回は Github と VSCode を布教すべく,何から始めたらいいのかをまとめていけたらと思います.

CLI vs GUI

Git を扱うにあたって,初学者が最初に腐心する所と言えば,やはりコマンドラインで実行しなければいけないところだと私は思います.そもそもどういう概念があるのかすらもわからないまま,コマンドを理解しろと言われても難しすぎます(私はできません).

別に Git に限った話ではないのですが,何かを学ぼうとするとき,同時に複数の概念を学ぼうとすると得てして頓挫しがちです.なので,この記事では git コマンドを極力使わない形で進めていきます.各種コマンドについてはそれぞれ必要に迫られたときに調べてください.

必要なもの

Github アカウント

https://github.co.jp/

Git でソースコードをオンライン上で管理するためのサービスの一つです.ユーザー名とメールアドレス,パスワードで登録できます.この時,ユーザー名に関しては後から変えることが困難なので命名には細心の注意を払ってください.

私のおすすめは以下の通りです.

  • 大文字を入れない (URLとして機能するので大文字小文字を混ぜても仕方がない)
  • わかりやすい名前にする (長い名前にすると手入力したときにめんどくさくなる)
  • 厨二な名前にしない(一番大事) (後から変えられるけどすごく面倒)

VSCode

https://code.visualstudio.com/

とても便利なコードエディタです.単体でもそこそこには使えるのですが,拡張機能を導入することで神々しいまでに優秀なツールに変わります. いかにもなデザインでカッコいい ので早速インストールしてモチベーションを上げていきましょう.

VSCode をインストールしていく際に,「PAtHに追加する」などの追加タスクを選択できるのですが,すべてチェックしておくことをお勧めします.

GitLens & Git Graph

今回使用する VSCode の拡張機能です.Git 周りの使いやすさが各段に向上します.VSCode の Extensions から検索窓に git と検索すればすぐに出てくると思うので,これをインストールします.

(コラム)おすすめの VSCode 拡張

今回は直接使いませんが,おすすめの VSCode 拡張があるので紹介します.

  • Material Icon Theme エクスプローラでその名前に応じてアイコンをつけてくれます.しかも, ファイルだけでなくフォルダにも その名前に応じてアイコンを振ってくれるのでファイル探しをする際にも視認性が向上します.
  • Dracula Official Dracula をモチーフにしたダークテーマです.Dracula Theme は多くのソフトウェアでも使用されているので,統一感が増して,他のソフトウェアに移ったとしても同様にDracula Theme があれば実家のような安心感が得られるかもしれません(知らんけど).コードの可読性も高いです(個人の感想です).
  • EditorConfig for VS Code 複数のOSやコードエディタで開発していく際に,改行記号やインデントをどのようにするかを規定するためのツールです.ソースコードを置いておくディレクトリに .editorconfig ファイルを置いて各種フォーマットを指定してあげることで改行記号 CRLFLF の混在などを防止してくれます.詳しくはEditorConfigやこの人の記事を読んでください.
  • Open in New Window VSCode内のエクスプローラーのフォルダを右クリックして Open in New Window を押すと,そのフォルダを VSCode で開くことができます(他と比べてインストール数が少ないですが気にしないでください).

Git(ソフトウェア)

Git のローカルで動くソフトウェアです(実体はコマンドラインツールでいいのかな?).インストールすることで,git コマンドが使えるようになったり,VSCode で Git を使う準備が整います.

とりあえず,プロフィール書こう

はじめましてをちゃんと言える人は,言えない人よりかはたぶんまともな人です.ということで, Github のプロフィールを書きましょう.

Github上でリポジトリを作成

まずはじめに, Github で Repository を作成します. Repository (リポジトリ)は,ファイルやディレクトリを Git 上で管理する際の一単位で,基本的に複数 Repository 間で履歴は共有されません.通常,プロジェクト単位やプロダクト単位となっていることが多い(気がする)ので,プロジェクトと言い換えてもいいかもしれません.

右上の ボタンの New repository から作成します.

次に,リポジトリ名を指定します.Github のユーザー名同様慎重に決めたり,外部公開しないために Private にしたり,色々と考えることがあるのですが,今回は Github に載せるプロフィールなのでちゃんとルールがあります.

ユーザー名と同一名のパブリックリポジトリ を作ってください.下に例を示します(私はすでに作ってしまっているのでエラーになってしまいますが気にしないでください).

拡大図を乗せましたが,確かに ✨special ✨ repository のようです. README.md がプロフィールとして表示されます.

Add a README file はこれから編集するものですが,最初からファイルとして作成して損するものでもないのでつけときましょう.他は既定のまま Create repository に進んでください.

これで Github 上にリポジトリができました.次は作成したリポジトリをローカルで編集できるようにします.

ローカルでリポジトリを編集する

次に, Github 上で作ったリポジトリをローカルに引っ張ってきます.

VSCode を開いて Open Directory(または Open Folder)でリポジトリを作成するディレクトリを開きます.開いたら Terminal を開きます. Terminal が何を指しているのかは各種 OS や環境によって Powershell やコマンドプロンプト, zsh, Git Bash だったり様々ですが,コマンドを入力して実行するツールです.どこにあるかがわからない方は Ctrl + Shift + @ で開くことができます.

次に,リポジトリを Github から落とすためにコマンドを入力します.

> git clone [リポジトリのURL].git

[リポジトリのURL] には,各人が作ったリポジトリの URL を指定します(例: https://github.com/streamwest-1629/streamwest-1629).

最後に .git を入れるのがミソです.入れなくても動くかもしれませんが,入れれば確実に動くと思います.

コマンドを実行すると,リポジトリと同名のディレクトリが作成されると思います.そのディレクトリが今回編集するリポジトリになるので,次は VSCode でこのディレクトリを開いてください.
先ほど Githubでリポジトリを作成した際に Add a README file チェックボックスにチェックを付けた人は README.md が入っていると思います.ない人も作って早速テンション爆上がりのおしゃれなプロフィールを作っていきましょう.インターネットに公開する情報ですので,自分の実績や Twitter をはじめとする SNS アカウントへのリンクなどを書いておくといいかもしれません.

.md ファイルは Markdown と呼ばれ,見出しや太字,リンクなどのシンプルな HTML のアイテムを簡単に書くことができます.

書き方については,この記事が参考になるかと思います.余裕のある方は shields.io などを使ってイカした Badge をつけてもいいでしょう.

ところで, VSCode はファイルの自動保存機能があります.左下の歯車マークから Settings を選び,設定しておきましょう.検索窓から検索することですぐ見つかると思います.おすすめは onFocusChange です.

変更をGithub上のリポジトリに反映する

さて,変更が終わった方も終わっていない方も,切りのいいところで一度作業を切り上げて変更を Github にあげてしまいましょう.

ファイル名は違うと思いますが,大体こんな感じになっていると思います.これは変更したファイルでの一覧で,ファイルの変更差分などを確認することができます.

ファイルの + ボタンにカーソルを持っていくと, Stage Changes という説明が出てくると思います.これをクリックします.するとこのように, Staged Changes にファイルが移動すると思います.

次に,変更内容を上のテキストボックスに記載して,Commit を押します.

するとおそらく,もしかしたら,このようなエラー文で失敗するかもしれません.

Git は各変更(これを Commit といいます)毎にその変更内容を示すメッセージと,変更者を示す名前とメールアドレスの情報を残すので,名前とメールアドレスを事前に設定しないといけません.

もう一度ターミナルを開き,以下のようなコマンドで自分の名前とメールアドレスを設定してください.

> git config user.name "ユーザー名"
> git config user.email "メールアドレス"

設定が完了したらもう一度 Commit ボタンを押して変更を保存します.今回の場合,設定した名前とメールアドレスは リポジトリ単位 で有効で,別のリポジトリの場合は再度設定しなおす必要があります. --global オプションを付けてグローバル設定に書き込むこともできますが,リポジトリ別に別の設定(個人用メールアドレスと組織用メールアドレスなど)を与える可能性もあるのでおすすめしません.

変更が完了したら,以下のようなボタンが出てくるので,これを押してください.もしかしたら Github へのログインが必要かもしれませんが,サクッと済ませて次に進んでください.

ちなみに,終わった変更については先ほどから触っている SOURCE CONTROL の下にある COMMITS を開くと出てきます.

これで変更の保存が Github 上でも完了しました.実際に Github のリポジトリのページ(今回の場合は自分のプロフィールページでもわかるかもしれない)に行って変更されたことを実際に確認してみてください.


これでファイルを保存して,変更をGithub上のリポジトリ(ローカルに対してリモートと言ったりする)に反映(Push) するまでの一連の流れを確認しましたが,このままだとチーム開発や大規模な開発を行ったときに不都合が生じます.

どういうことかといえば「変更を誰も確認していない」ということです.先ほどのプロフィールの編集の例でいえば「今さっき行った変更に誤字や脱字は入っていませんか?」という問題です.これは高々自己紹介のためのドキュメントなのでサクッと直せばいいだけですが,これが複数人でチーム開発していたりすればそれはバグやビルドエラーの原因になります.
また,往々にして,「同時に複数の機能を開発したい」というニーズはあるのですが, CLI と Git を同時に学ぼうとしても頓挫するように,規模が大きくなればなるほどろくな結果にならない ことがほとんどです.

これらの問題を解決するために,課題の管理から変更の承認までのプロセス(筆者の場合)を次の章で実際に行っていきます.

Issue ベースの変更

この章ではレクリエーション的に Issue ベースの変更を複数人で行うための方法について書き残していきます(本来の執筆目的から考えればここが本題だったりします).個人で行う場合と被る話があるかと思いますが,そこらへんはいい感じに聞き流してもらえればと思います.

はじめに,この章では Issue とブランチという概念が出てくるのでその説明を先に行います.

Issue は,開発中のバグや新機能を追加したいときにそれらを管理するための仕組みです.誤解を恐れずに言えば,複数人で管理する TODO リストのようなものです.この Issue の中で,テキストチャットのように話し合うこともできます.

ブランチは,特定の問題を解決するためにコードの変更を管理しやすくする仕組みです.具体的には大本となるソースコードから必要な所だけ変更を加えて元に戻す,という作業をスムーズに行うことができます.

使用するリポジトリを共有する(複数人で行う場合だけ)

まずはじめに,複数人で編集できるようにリポジトリを共有してください.パブリックリポジトリであれば基本的にその必要はありませんが,プライベートリポジトリである場合には共有を行ってください.ここでは本題ではないので割愛させていただきます.

共有したリポジトリは各人がそれぞれローカルにおとしてください.

Issue を作成する

Issue を作成します. Github のリポジトリページに行き,「Issues」から「Create issue」を選択します.

Issue の内容を書いて「Submit new issue」で Issue を作成します.

これで Issue が作成され,Open な状態になりました.さて,この Issue に対応するブランチを作成します.一番簡単な方法はこの右下にある「Create branch」からブランチを作成する方法です.命名規則もある程度整って,ブランチ名も意識して開発しないので私は常用していますが,残念ながら2022年11月現在 beta 版の機能となっており,まだないかもしれません.

この方法を選択した方は,出てきたコマンドをそのまま VSCode のターミナルに張り付けて実行をしてください.

この方法を使えなかった人は,ブランチをローカルから作っていきます.VSCode の Git を操作する画面から「BRANCHES」にカーソルを運ぶと「+」ボタンが出てきます.押すと作成するブランチ名を指定するテキストボックスが出てくるのでそれで作成します.

この方法だと,ローカルにはブランチができますが,リモートには反映されません.「SOURCE CONTROL」を開くと「Publish Branch」ボタンができているのでそれを押すとリモートにも同名のブランチが作成されます.


また,どちらの場合においても, 「ブランチを作成したが,現在のブランチが作成したブランチになっているか」 を必ず確認してください.確認はVSCode の Git を操作する画面から「BRANCHES」を開くとブランチの一覧が出てくると思います.

チェックマークのついているブランチが現在のブランチです.新しく作成したブランチにチェックマークがついていれば問題ありません.ついていない場合にはブランチにカーソルを運んで一番左側にある「↪」マークのボタンを押すとそのブランチに移動(チェックアウト)できます.

変更を加える

各々の Issue を解決するための変更を加えてコミットをするのを繰り返してください.複数個のコミットであっても問題ありません(複数個のコミットがあることを前提に作られているので気にせず).

ただ,自分の変更範囲がどこであるかは常に忘れないようにしてください.チーム開発である場合,別の人が同じ場所に変更を加えているかもしれないので,競合(コンフリクト)が発生するのを防ぐためにも,自分の変更箇所がどこで,どのファイルを変更するかは気にしておきましょう.

プルリクエストを作る

変更が完了したら,コミットを作りPushしてリモートリポジトリに変更を反映してください.続いて,プルリクエストを作ります.
Github でリポジトリのページからブランチの一覧へ移動し,New Pull request でプルリクエストを作成します.

この際,タイトルとコメントは後から見てもわかりやすい名前にしておいたほうが良いです.特に,組織で行う場合にはどのような変更をなぜ加えたのかを書いておくと理想的です.

個人で行う場合

個人で行う場合にはここでチェックをしてほしいですが,自分で自分の書いたものをチェックしても仕方がないのでそのまま merge を押してもとりあえず構いません.ここで Github Actions を用いた自動テストを組んだりするのが CI (継続的インテグレーション)と呼ばれるもので一人でもプルリクエストをする意味が出てくるのでぜひ調べてみてください.

組織で行う場合

組織で行う場合には,Assignee に自分を,Reviewer にレビューをする方を指定してください.もしこれを何かの研修として行っているならば,全員が Assignee となり,全員が Reviewer となるような調整を事前に行うべきでしょう.

Reviewer となった人はプルリクエストで加えられた変更を Github のプルリクエストのページからレビューしてください. File Changed タブからその変更差分を確認することができます.

左の行数の所にカーソルを持っていくと + ボタンが出てくるので,それをクリックするとその行に対してコメントを残すことができます(下にドラッグすることで複数行選択することもできます).

レビューを行ったら(修正箇所がない場合も含む),右上にある Finish Reviewed でレビューが完了したことをコメントにします.

ラジオボタンで選択するボタンが出てきますが,それぞれ以下のような意味です.

  • Comment ... 普通のフィードバックで,レビュワーとしては承認していない意味合いになる.
  • Approve ... レビュワーとしては承認する.
  • Request Changes ... フィードバックだけど,コメントした内容については必ず直すような指示の意味合いになる.

プルリクエストにつけたコメントに応じて,それぞれ選択し, Submit Review でレビューを一度完了します.

レビューされた人はコメントに応じて修正を行うか,問題がなかった場合はマージを行います.修正は今まで通りローカルで変更を行ってコミットを作りプッシュで行います.

修正が終わった場合にはプルリクエストページの Reviewer の名前の隣にあるで、🔄ボタンを押すことで再レビューを依頼することができます(これだけスクリーンショットを用意できなかったのは申し訳ないです).レビューで問題がなくなりマージが完了するまでこれを繰り返してください.


これで作業は以上になります.

エトセトラ

GUI などで隠されていたけれど割とよく使用する Git コマンドとそれに対応する Git Lens などを用いた実行方法

最初の事前準備の方で,Git Lens を拡張機能に追加してもらうように書いたのですが,それを実際に使っていく場面が少なかったのでそれぞれコマンドの内容と Git Lens を用いる方法について確認したいと思います.

リモートリポジトリにあるコミット情報を取得する (git fetch)

git は google ドライブみたいに自動同期のような機能はありません.そのため,主導でデータを取得するためのコマンドを実行します.また,後述しますがこれはあくまでコミット情報を取得するコマンドでローカルリポジトリのファイルに反映するのは別のコマンドがあります.

> git fetch origin

これ以外のコマンドでも何度か出てくるのですが, origin は github.com のリポジトリなど参照するリモートリポジトリのローカルにおける名前です.複数ある場合も想定されているのですが,(少なくとも私は)使ったことがないので大体のケースにおいてデフォルトの名前である origin で問題ないと思います.

何を言っているのかわかりにくいので,代替の方法について見ていきます.この操作は Git Lens と Git Graph で行うことができますが,直感的にわかりやすくするのと, Git Lens を用いる方法についてはすでにどこかに書いた気がする(間違っていたらごめんなさい)ので,Git Graph を使います.

リモートリポジトリにあるコミット情報をローカルリポジトリに反映する (git pull)

リモートリポジトリにあるコミット情報をローカルリポジトリのファイルに反映します.

> git pull origin (ブランチ名)

実のところ,これは git fetchgit merge が実行されています.つまり. git fetch でリモートリポジトリにコミット情報を取得した後,ローカルリポジトリにリモートリポジトリのコミットをマージしているわけです.

と書いたものの,自分でもしっくりこないので代替の方法について見ていきます.次は Git Lens を用いますが,やはり直感的にわかりやすいので Git Graphを開いておいてください.

Github にあげてはいけないもの

私の知っている限り,以下の2系統のファイルはあげてはいけません.ちゃんと .gitignore でファイルを除外しましょう.

  • API トークンなどセキュリティに直接関わるもの
    理由はあえて書く必要はないと思います.どこで悪用されるかわからないので出さないようにしてください.
  • 大容量のバイナリファイル(他の人が許しても私は許さない)
    リポジトリをダウンロードする際に重くなってしまうというのと,そもそもコードを管理するツールでバイナリファイル,それも容量の大きなものを管理しないでください.ただ,一概にバッサリ否定できるわけでもなく Git LFS という,そういうファイルを管理するための仕組みも Github 内では提供されているのですが,Github のプライベートリポジトリの合計容量が個人の無償アカウントは 1GB , Organizationアカウントは 500MB しか割り当てられていません. Github で無料で無制限にリポジトリを作れることに感謝してください.

素朴な疑問(気が向いたら書き足します)

  • Q. ブランチやリポジトリは安直に新規作成してもいいのか
    • A1. ブランチは安直に新規作成してもいいと思いますし,私は Issue 毎に使い捨てしてしまいます.その代わり,残しておくと管理しにくいので使い終わったブランチは削除した方がいいです.
    • A2. リポジトリはそれぞれ考え方があるので一概に答えを出せませんが,概ね 1 プロジェクトまたは 1 プロダクト毎に 1 個リポジトリがあるのがいいかなというのが私の所感です.

Discussion

ログインするとコメントできます