Git: Add linguist-generated in .gitattributes

Author: ma91n

documents/forGitBranch/git_branch_standards.md

@@ -625,11 +625,7 @@ refactor: Lintエラーの修正 💄
 
 :::
 
-# 推奨設定
-
-GitやGitHub/GitLabの推奨設定をまとめる。本規約にあるGitブランチ運用は、以下の設定が行われている前提で説明している箇所がある。
-
-## git config推奨設定
+# git config推奨設定
 
 `git config` の推奨設定を紹介する。特にGitワークフローの設定が重要である。
 
@@ -664,15 +660,15 @@ git config --global alias.br branch
 - `fetch.prune`: リモートリポジトリで削除されたブランチを削除する
   :::
 
-## git-secrets
+# git-secrets
 
 [git-secrets](https://github.com/awslabs/git-secrets)を用いることで、ユーザーパスワードや AWS アクセスキーなどの機密情報が含まれる可能性のあるコードなどをGit リポジトリに追加されないようにできる。
 
 本規約の推奨は以下。
 
 - チームメンバー全員にgit-secretsを導入する
 
-## コミットフックでテスト実行は行わない
+# コミットフックでテスト実行は行わない
 
 [git hooks](https://git-scm.com/book/ja/v2/Git-%E3%81%AE%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%9E%E3%82%A4%E3%82%BA-Git-%E3%83%95%E3%83%83%E3%82%AF) を用いて、コミットやプッシュ時に単体テスト実行などのカスタム処理を追加することができる。これを用いると、ローカルでの動作検証などを未実施な状態でレビュー依頼をしてしまうといった状況を未然に防ぎ、開発フローを強制的に適用することができる。
 
@@ -689,7 +685,9 @@ git config --global alias.br branch
 実行時間が短いフォーマットであれば、git hooksで実行させると便利なことが多く（CIで違反に気づいて対応する手戻りが減るためである）、必要に応じて導入しても良い。
 :::
 
-## .gitattribute
+# .gitattributes
+
+## eol
 
 チーム開発において開発環境がWindows/Macなど複数存在することは少なくなく、また、Gitリポジトリ上の改行コードは統一した方が余計な差分が生じず扱いやすくなる。このときよく用いるのが、 `core.autocrlf` という設定である。
 
@@ -738,13 +736,53 @@ testdata/eol/input1.cs: eol: crlf
 
 :::
 
-## .gitignore
+## linguist-generated
+
+自動生成で変更が発生し、かつ大量の変更が頻繁に発生する場合には、レビュワーが毎回レビューをすることは効率的でない。
+
+`.gitattributes` で `linguist-generated=true` の設定を行うことで、差分をデフォルトで表示させず、プルリクエストの可視性を向上させることができる。
+
+```sh .gitattributes
+# 自動生成されたHTMLファイルの差分を無視する
+/path/to/generated/*.html linguist-generated=true
+```
+
+上記の設定で `/path/to/generated/main.html` をコミットすると、差分が以下のように非表示となる（Load diffをクリックすることで差分表示は可能）。
+
+![プルリクエストのFile changedでmain.htmlの差分がLoad diffと表示](no_diff.png)
+
+本規約の推奨は以下の通り。
+
+- ツールなどによる生成ファイルをレビュー対象外とする場合は、`linguist-generated=true` を設定し、レビュアーの負荷を下げる
+- レビュアーは差分が省略された場合は、レビュー対象外としてファイルの中身の確認は任意とする
+
+::: tip 生成コードをレビュー対象としたい場合
+
+GitHubでは、[言語毎に生成ファイルと判定する処理](https://github.com/github-linguist/linguist/blob/v9.0.0/lib/linguist/generated.rb)があり、例えツールで作成されたファイルであっても、レビュー確認を必須としたい場合には、クリックする手間が増える分、逆に非効率になる。
+
+例えば、Javaなど複数の言語では3行目までに `Generated by the protocol buffer compiler.  DO NOT EDIT!` が含まれていると[Protocol Bufferの生成コードとみなされる](https://github.com/github-linguist/linguist/blob/63cfd70d54ee8f76c41a73fe56689ed8229c9622/lib/linguist/generated.rb#L348-L359)。
+
+もし、明示的に差分を表示させたい場合、`linguist-generated=false` を設定する必要がある。
+
+```sh .gitattributes
+# 以下はコード生成されたファイルだが、レビュー対象としたいためlinguist-generated=falseを設定し、差分を表示させる
+/path/to/generated/*.java linguist-generated=false
+```
+
+:::
+
+参考:
+
+- [変更したファイルの GitHub での表示方法をカスタマイズする - GitHub Docs](https://docs.github.com/ja/repositories/working-with-files/managing-files/customizing-how-changed-files-appear-on-github)
+- [GitHubでファイル差分が表示されない！？レビューを快適にするための差分の非表示ロジックを解説](https://zenn.dev/hacobell_dev/articles/show-diff-in-github)
+
+# .gitignore
 
 Gitで管理したくないファイル名のルールを定義する`.gitignore`ファイルも入れる。ウェブフロントエンドであれば新規プロジェクトを作成すると大抵作成されるのでそれを登録すれば良いが、もしない場合、あるいは複数の言語を使っている場合などは[GitHubが提供するテンプレート](https://github.com/github/gitignore)を元に作成すると良い。GlobalフォルダにはWindows/macOSのOS固有設定や、エディタ設定などもある。
 
 環境設定を`.env`で行うのが一般的になってきているが、`.env.local`、`.env.dev.local`といった`.local`がついたファイルはクレデンシャルなどの機微な情報を扱うファイルとして定着しているため、 `*.local`も追加すると良い。
 
-## 個人用のファイルをGit管理対象外とする
+# 個人用のファイルをGit管理対象外とする
 
 `.gitignore` を用いると、チームでGit対象外とするファイルを一律で設定できる。
 
@@ -759,7 +797,7 @@ Gitで管理したくないファイル名のルールを定義する`.gitignore
 
 - [個人的Gitおすすめtips 7選 #GitHub - Qiita](https://qiita.com/hichika/items/f3c980dd069df0f3a56e)
 
-## Pull Request / Merge Request テンプレート
+# Pull Request / Merge Request テンプレート
 
 GitHubやGitLabでは、プルリクエスト作成時のテンプレートを作ることができる。チームでプルリクエストで書いてほしいことを明示的にすることで、レビュー効率の向上や障害調査に役立てることができる。
 
@@ -784,15 +822,15 @@ GitHubでは `.github/PULL_REQUEST_TEMPLATE.md` に記載する。（GitLabで
 - [ ] 今回のPRでは未対応の残課題があればIssueに起票した
 ```
 
-## GitHub推奨設定
+# GitHub推奨設定
 
 業務利用でのチーム開発を想定しており、リポジトリは以下の条件を満たす前提とする。
 
 - プライベートリポジトリ
 - Organization配下に作成
 - Teamsプラン以上の有料契約（※プロテクトブランチの機能などを利用するために必要）
 
-### General
+## General
 
 | Category      | Item                                                             | Value        | Memo                                                                                       |
 | ------------- | ---------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
@@ -805,7 +843,7 @@ GitHubでは `.github/PULL_REQUEST_TEMPLATE.md` に記載する。（GitLabで
 |               | Automatically delete head branches                               | ✅️          | マージ後にfeature branchを削除するため有効にする                                           |
 | Pushes        | Limit how many branches and tags can be updated in a single push | 5            | git push origin –mirrorで誤ってリモートブランチを破壊しないようにする。推奨値の5を設定する |
 
-### Access
+## Access
 
 | Category                | Item          | Value      | Memo  |
 | ----------------------- | ------------- | ---------- | ----- |
@@ -818,9 +856,9 @@ GitHubでは `.github/PULL_REQUEST_TEMPLATE.md` に記載する。（GitLabで
 - 「Admin」権限は、マネージャークラスに対して合計2~3名を付与し、属人化しないようにする
   - 1名でも、4名以上でもNGとする
 
-### Code and automation
+## Code and automation
 
-#### Branches
+### Branches
 
 Branch protection rules にdevelop, mainなど永続的なブランチに保護設定を追加する。
 
@@ -843,28 +881,28 @@ developブランチに対し「require linear history」を選択することを
 
 [^1]: https://zenn.dev/daku10/articles/github-merge-guardian
 
-#### Tags
+### Tags
 
 | Category | Item         | Value                | Memo                                                     |
 | -------- | ------------ | -------------------- | -------------------------------------------------------- |
 |          | Protect tags | v[0-9]+.[0-9]+.[0-9] | セマンティックバージョニングに則ったタグのみ、削除を防ぐ |
 
-#### GitHub Actions
+### GitHub Actions
 
 | Category            | Item                                                                                                                                | Value | Memo |
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----- | ---- |
 | Actions permissions | Allow asset-taskforce, and select non-asset-taskforce, actions and reusable workflows > Allow actions created by GitHub             | ✅️   |      |
 |                     | Allow asset-taskforce, and select non-asset-taskforce, actions and reusable workflows > Allow actions Marketplace verified creators | ✅️   |      |
 
-#### Code security and analysis
+### Code security and analysis
 
 | Category   | Item                        | Value | Memo                                       |
 | ---------- | --------------------------- | ----- | ------------------------------------------ |
 | Dependabot | Dependabot alerts           | ✅️   | 依存パッケージのアップデートを検知するため |
 |            | Dependabot security updates | ✅️   |                                            |
 |            | Dependabot version updates  | ✅️   |                                            |
 
-## GitLab推奨設定
+# GitLab推奨設定
 
 - GitHubの「Automatically delete head branches」
   - マージリクエストから「Delete source branch」オプションを有効にすることが該当