Git 講習会 発展編

docs/.vitepress/config.mts

@@ -38,6 +38,22 @@ export default defineConfig({
             { text: 'おまけ13: VSCode以外のGUI操作', link: '/basic/github-desktop' }
           ]
         }
+      ],
+      'advanced': [
+        {
+          text: '発展編',
+          items: [
+            { text: '目次', link: '/advanced/'},
+            { text: '0. 導入', link: '/advanced/0-intro'},
+            { text: '1. Git と GitHub', link: '/advanced/1-git-n-github'},
+            { text: '2. プロジェクト', link: '/advanced/2-project/'},
+            { text: '3. コミットの作法', link: '/advanced/3-commit/'},
+            { text: '4. Git CLI', link: '/advanced/4-cli/', items: [
+              { text: 'Git の仕組み', link: '/advanced/4-cli/system'},
+            ]},
+            { text: '終わりに (まだ）', link: '/advanced/conclusion'},
+          ]
+        }
       ]
     },
 

docs/advanced/0-intro.md

@@ -0,0 +1,23 @@
+# 0. Introduction
+
+## 自己紹介
+
+- たけ :@Takeno_hito: @Takeno_hito
+- 22B プログラマー? SysAd班員
+- Logical Room のプランナー
+
+## 講習会の目的
+
+前期に実施された Git 講習会を受講している事を前提にして、主にプログラマー向けにより実践的な使い方を学ぶ。
+
+::: warning
+本講習会は主にプログラマー（＝コードを書いている）向けのものです。
+そうでない場合は、前期にlogicaさんが実施したGit講習会の内容を理解していれば十二分だと思います。（もちろん受講は大歓迎です）
+:::
+
+## 講習会概要
+
+1. Git と GitHub/Gitea が別物であるという事を理解する
+2. Git CLI を使って、Git がどのように動いているかを理解すると同時に、Git CLI で操作できるようにする
+3. rebase, cherry-pick など Git に関する新たなサブコマンドを理解する
+4. Git の実用的な使い方を理解する

docs/advanced/1-git-n-github.md

@@ -0,0 +1,42 @@
+# 1. Git と GitHub と Gitea...?
+
+Git, GitHub, Gitea を混同する者がたまに居るので、これらの違いを以下に解説する。
+
+- Git
+  - コードのバージョン管理（ソースコードの編集履歴の記録）をするソフト
+  - サーバー上に保管されている「リモートリポジトリ」
+  - 各自のPCに保管されている「ローカルリポジトリ」
+  - ローカルリポジトリを編集して、リモートリポジトリと同期をとる形で作業する
+- GitHub
+  - Git を使用した **Web サービス**
+  - リモートリポジトリを保管する以外にも、チーム開発に便利な機能を提供してくれている
+- Gitea
+  - Git を使用した、セルフホスト型（自分でサーバーを持つ）の **ウェブサービス**
+  - リモートリポジトリを保管する以外にも、チーム開発に便利な機能が実装されている
+  - traP の場合は、traP のサーバーに Gitea を置いて運用している
+
+### Git/GitHub の違いクイズ
+
+1. `commit` は Git の機能か、GitHub の機能か？
+2. `merge` は Git の機能か、GitHub の機能か？
+3. `pull` は Git の機能か、GitHub の機能か？
+4. `issue` は Git の機能か、GitHub の機能か？
+
+:::spoiler Answer （クリックで展開）
+
+1. commit は Git の機能。
+2. merge は Git の機能。GitHub の機能とも言えなくもないが、本質的には GitHub が Git のマージをする機能だという事を忘れないように。
+3. pull は Git の機能。Pull Request が GitHub の機能。もともとは、大本のリポジトリを持つ側に対して「自分のリポジトリ内のブランチをpull して統合してください」とrequest を出す、という所から Pull Request という名前がついている。
+4. issue は GitHub の機能。Git に issue 機能はない。
+:::
+
+:::info
+**おまけ：Gitea と GitHub の使い分け**
+
+Gitea と GitHub 、これらはどちらも Git のホスティングをしているが、大きく違うのは GitHub は **GitHub** のサーバー上にコードを保管していることに対して、Gitea は**自分が所有する**サーバー上にコードを保管していること。
+そのため、GitHub には OSS（オープンソースソフトウェア）が置かれて、Gitea にはセキュリティ上の問題から非公開のファイルを置いている、という事が多い。
+（GitHub の会社向けプランみたいなものも存在していてそれを使う企業・団体も存在するし、またはGitea/GitHub 以外のソフト・サービスを使っている企業・団体も存在する。）
+
+traP の場合は traQ のような traP が作った webサービスそのものは GitHub 上で公開され、サーバーの設定ファイル（プロビジョニングコード）や、Gitea と連携している Showcase で動かすコードは Gitea 上に置かれている、という事が多いらしい。
+また、2022年に新規に立ち上げられたプロジェクトはすべて Gitea 上に置かれている。
+:::

docs/advanced/2-project/index.md

@@ -0,0 +1,93 @@
+## 2. Git 運用のすすめ
+
+### merge conflict
+
+[![](https://mermaid.ink/img/pako:eNp1kdtKxDAQhl9lGCi5qYi3uRB6kG11BU8XuvQm26RtsElKTMWl9N1Nu8qWPQQCmZkv_z_JDFgaLpBiEAxSS0dhANKaei2-RUsoEC62fU1CIK4RSuwzFetbR2CEMQgKDfOqpVtZ1jX_MUBplJIOJKcF5l66wENta5kuG6jkz_XN4kYjyk_TO1BM6vNCURTB1S0kSbKUWxJxHE_E-8emQHC7TtAsX2Vrv9_OOB13cGqVpuklK9_FRDw9v1wifGki8vuHk2bAsdoT2V3k9TFEJax_NvejGCatAucPL5D649-XTy6jR1nvzOtOl0id7UWIfceZE6lktWUKacXaL5_tmN4Yc4gFl87Yx_2456mPvybcljY?type=png)](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNp1kdtKxDAQhl9lGCi5qYi3uRB6kG11BU8XuvQm26RtsElKTMWl9N1Nu8qWPQQCmZkv_z_JDFgaLpBiEAxSS0dhANKaei2-RUsoEC62fU1CIK4RSuwzFetbR2CEMQgKDfOqpVtZ1jX_MUBplJIOJKcF5l66wENta5kuG6jkz_XN4kYjyk_TO1BM6vNCURTB1S0kSbKUWxJxHE_E-8emQHC7TtAsX2Vrv9_OOB13cGqVpuklK9_FRDw9v1wifGki8vuHk2bAsdoT2V3k9TFEJax_NvejGCatAucPL5D649-XTy6jR1nvzOtOl0id7UWIfceZE6lktWUKacXaL5_tmN4Yc4gFl87Yx_2456mPvybcljY)
+
+merge を行う際、たまにコンフリクトが発生する。例えば、上図のようなコミット図で fix/1 -> main にマージを行う際に、 `AAA` を `CCC` に変更するコミットと、同じ `AAA` を `DDD` に変更するコミットが違うブランチで存在したときに、 Git は自分ではマージせずに一回中断する。
+
+GitHub などで PR をマージする時にコンフリクトが発生すると、一度作業ブランチにマージする必要がある。これは、コンフリクトを正しく解消できているかレビュワーが確認したいからである。
+
+[![](https://mermaid.ink/img/pako:eNp1kt9rgzAQx_-VIyC-OMZe8zCwCq1bB1u3h634kuqpYZpIGrsV8X_fqSu1vwKBXO5z3y-XS8sSnSLjzHFaqaTl0IJb6nyJOyxdDm6KmyZ3PXBtgRWON5loSutCB53jxAqGlUs7N6IuDjFAoqtKWpApj1lE0jE75jZGqKSATP7eP0wqCky-dWOhElJdF_J9H-4eIQiCqdyUmM1mPfH5tT4hDtLnlpfaYRje0ibbnnh9W90iKNUT0dPzlKjQ5Dh0BXZfI19E88WS9sdYZHCryx2SkMpKmdBLgRU5JVa4k_hztY_TJxoNht7OHJjHKEl0SkNu-4qYDaOMGafj_zB7i45Q0Vj9vlcJ49Y06LGmToXFUIrciIrxTJRbuq2FWmt9jDGVVpuX8SMN_6n7A4UqslA?type=png)](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNp1kt9rgzAQx_-VIyC-OMZe8zCwCq1bB1u3h634kuqpYZpIGrsV8X_fqSu1vwKBXO5z3y-XS8sSnSLjzHFaqaTl0IJb6nyJOyxdDm6KmyZ3PXBtgRWON5loSutCB53jxAqGlUs7N6IuDjFAoqtKWpApj1lE0jE75jZGqKSATP7eP0wqCky-dWOhElJdF_J9H-4eIQiCqdyUmM1mPfH5tT4hDtLnlpfaYRje0ibbnnh9W90iKNUT0dPzlKjQ5Dh0BXZfI19E88WS9sdYZHCryx2SkMpKmdBLgRU5JVa4k_hztY_TJxoNht7OHJjHKEl0SkNu-4qYDaOMGafj_zB7i45Q0Vj9vlcJ49Y06LGmToXFUIrciIrxTJRbuq2FWmt9jDGVVpuX8SMN_6n7A4UqslA)
+
+（作業者が `main` ブランチを `fix/1` ブランチにマージして、 `review` タグがついたコミットをレビュワーが確認し、その後 main にマージされる。という流れを表したのが上図）
+
+コンフリクト解消は意外と面倒くさいので、演習用のリポジトリを使いながら実際に解消して学ぶと良いだろう。
+
+:::success
+**演習**
+前提：`ex_rebase` ブランチがマージされてる状態にする（`ex_rebase`、`ex_conflict` ブランチ間でコンフリクトが発生している。）
+
+1. `ex_conflict` を master にマージしたいので、PR を立てる。この時に、コンフリクトが発生していると Gitea に怒られるので手元で修正する。
+2. `ex_conflict` ブランチにチェックアウトし、`master` ブランチをマージする。
+3. コンフリクト通知が出るので、エディターを使って編集する (vim じゃなくて良い）。
+4. 以下のように `<<<<<<<HEAD` と `>>>>>>> master` で囲まれている部分がコンフリクトしている場所なので、2つを見比べながら適用していく。
+  この時、「**どちらがどんな変更をしたのか**」を確認しながら、どちらも適用できるように編集を進めていくこと。
+```
+<<<<<<< HEAD
+本サークルは、名称を **『東京医科歯科工業大学デジタル創作同好会traP ..... とする。
+=======
+本サークルは、名称を **『東京工業大学デジタル創作同好会traP』... とする
+>>>>>>> master
+```
+
+5. キャンパス名の修正で困ったかもしれない。どちらも違うものに編集しようとしている。ここでは、「すずかけ台」への移行を採用する。
+6. 修正が完了したら、マージコミットを作成する。
+
+:::
+
+### .gitignore
+
+gitignore は git の管理下に新たに置きたくないファイルを指定するファイル。
+注意して欲しいのは、既に git の管理下に置かれたファイルは、gitignore に追加しても変更は追跡されるという事（1敗）。具体的な記述方法は割愛するので各自調べること。（`*` によるワイルドカード指定などができる。）
+主にビルド時・実行時に生成されるファイル・キャッシュ・バイナリファイルや、ライブラリ、また個人情報や認証情報が含まれるファイルが gitignore に置かれる事が多い。
+
+[gitignore.io](https://www.toptal.com/developers/gitignore) を使うと、リポジトリを制作する時に必要なファイルを自動で生成してくれるので便利。
+
+### branch protection
+
+文字通りブランチの保護に関する設定。例えば、間違えて master にコミットしても push する際に拒否されるので他の作業者に影響を及ぼさなくなる事ができる。
+
+GitHub でできるプロテクションはこんな感じ。Gitea にも同様の設定が存在する。
+
+![](https://i.imgur.com/6Oo1nPc.png)
+
+自分が普段つけている設定は、大体
+- マージ前に main への PR を必須にする
+- main へのレビュワーの Approve を必須にする
+- main への直接の commit を禁止する
+
+の3つ。
+
+### issue/PR の作り方
+
+GitHub、Gitea 共に issue, PR の機能が搭載されているが、運用の仕方は様々あるし、あまり提示されていない事も多い。ここでは自分が今までやってきて、他のところでも traP でも大体そうっぽそうという話をする。
+
+#### issue を建てるとき
+
+1. まずはじめに、その issue は大きくならないかをよく考える。小さく分割できるなら分割した方がよい。
+    - **非常に重要**。これをしないと、大きい PR が完成してレビュワーが泣く。
+    - 過大な issue を切り分けるのはプロジェクトリーダーの仕事に関わる部分だと思っているので、ちょっと気をつけるくらいでも良いと思う。
+3. issue タイトルは簡潔に、明確にする。
+4. タイトルに書いてない話を本文に書く。（具体的な仕様・要件とか、バグ内容とか。）
+    - タスクが複数ある場合は、チェックボックス `- [ ]` を使うのがおすすめ。
+      進行状況が issue 一覧からも分かるようになりかなり便利。（GitHub, Gitea 共通）
+      ![](https://i.imgur.com/J2s8Wxj.png)
+      ![](https://i.imgur.com/WuT5CUx.png)
+6. タグ・ラベルをつける（enhancement, bug とか。説明文が下に書いてあるので読んでそれっぽそうな物を選ぶ。）
+
+#### issue に取り掛かるとき
+
+**必ず** issue の Assingees に自分を設定する。これを設定しないと、作業が重複して悲しい事になる。
+
+参考: https://docs.github.com/ja/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue
+
+#### PR を建てるとき
+
+1. 何をしたかを簡潔に書く。issue と対応した名前でなくても良い。
+2. 本文には何をしたかを書く。PR の diff やコミット一覧を見ながら書くこと。
+    - たくさんあれば箇条書きを使うと良い。
+3. 対応する issue の番号を書く。例えば130番ならば `resolve: #130` と書くだけで良い。
+    - これを書くと、PR がマージされた時に自動的に issue がクローズされて、作業が楽になる。
+    - issue がクローズされたくないなら、単に `#130` と書けば十分。
+4. issue と同様にしてラベルをつける。

docs/advanced/3-commit/index.md

@@ -0,0 +1,60 @@
+### Git Flow
+
+Git Flow は Git を利用した開発方針の一つ。`master` `develop` `hotfix` `feature` `release` のブランチを作って、各ブランチに以下のような役割をもたせて運用する。マージする前の PR はあまりなく、master にマージする前にバグがないかチェックする。
+具体的な運用の仕方についてはここでは扱わない。
+
+- `master` はリリースされているもの
+- `develop` はリリース前のもの
+- `feature` は個々が作業するブランチ
+- `hotfix` は緊急修正を行う作業ブランチ
+- `release` はリリース作業を行うブランチ。（develop -> master)
+
+![](https://i.imgur.com/Vfn2zGH.png)
+
+
+### GitHub Flow
+
+`master` と作業ブランチのみが存在し、`master` にマージする前に PR を立ててレビューを行ってからマージする形式。`master` にマージされるたびに、即時リリースされる。
+
+実際に運用する際には、どちらも運用しやすいように形を変えることが多い。例えば traQ の場合は GitHub Flow のような形だが、リリースはマージされる度には行わずに、リリースコミットを打ったタイミングでリリースをする。
+
+### コミットの付け方・ブランチの付け方
+
+作業する時のコミットやブランチの切り方、メッセージの書き方について。
+
+まず前提として、リーダーの人がルールを決めていたらそのルールに従うべきである。
+
+#### ブランチ
+
+ブランチは、1 issue に対して 1つのブランチを意識する事。issue が終わる度に PR を出したい。ブランチの名前は、issue の名前を英語にすれば良い。全員東工大生なのできれいな英語を無理に意識する必要はない。
+
+#### コミット
+
+コミットはできるだけこまめにしよう。push する前に先述の rebase 等を使用すれば良いだけ。変更したい所がうまく変更できて、ビルドも成功すればすぐにコミットする事。
+コミットメッセージの付け方については、コミットの頻度が非常に細かくなればそこまで困ることはなくなると思う。(Todo)〇〇した、という形で書けば割とよくなる。日本語でも英語でも良いと思うが、ルールが存在すればそれに従うこと。
+
+また、コミットにプレフィックスをつける事を個人的にはおすすめする。
+
+[Angular](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#type) を見ながら、コミットにプレフィックスをつけるとコミット一覧を見た時にどのような変更なのか非常に分かりやすくなる。
+
+具体的にはこんな感じ。([リポジトリのURL](https://github.com/afes-website/cappuccino-app/commits/develop))
+![](https://md.trap.jp/uploads/upload_343a20d33c2c280e0c1b6f2e4efdbd6d.png)
+
+もうひとつの選択肢として、コミットメッセージの先頭に絵文字をつける方法もある。
+
+[gitmoji](https://gitmoji.dev/) を見ながら、コミットに絵文字をつけると見た目は良くなる（ただ、これを知らない人が見ると全くわからない気がする…）。
+
+こっちはこんな感じ。カラフルでちょっと見栄えは良い。（[リポジトリ](https://github.com/traPtitech/traPortfolio/commits/main)）
+
+![](https://md.trap.jp/uploads/upload_c3ea1d69be3dcfe38450395387d18d7a.png)
+
+### やってはいけないこと
+
+- 巨大なバイナリファイルのコミット
+  - 特に zip ファイル。そのままコミットすると、他のgit操作に支障が出る。Git LFS を用いるなりそもそも巨大なzipファイルを扱わないなり回避するべき。
+  - GitHub は特に制限があって、超えると利用停止とかが発生するので要注意（これで後輩が利用を停止させられていた。）
+- コードのコメントアウト
+  - 特段の理由がなければ避けるべき。過去のコミットを漁れば見れる。
+- force-push
+  - バージョン管理のデータそのものを一部吹き飛ばす訳なので、無闇にやって良いものではない。
+  - 特に、masterブランチなどではしない方が良い（他の人の作業進捗にまで影響が出る為）。