| name | git-safety |
| description | Git workflow safety procedures: diagnose why git add fails (3-layer gitignore system), recover from pre-commit hook failures (NEVER amend after hook failure), validate git add -A risks, and manage auto-generated directories. Use when git add fails, pre-commit hook fails, user attempts broad git add, gitignore issues arise, or git commit workflow encounters errors. |
| version | 1.0.0 |
Git Safety Guide
Git 操作時の安全手順ガイド。
高頻度エラー注意: 「hook 失敗後の --amend 使用」と「git add -A の無差別使用」に特に注意。
コミット前チェック（必須）
-
git status で状態確認
- 必ず
-uall フラグは使わない（大規模リポジトリでメモリ問題の原因）
- untracked files と staged files を確認
-
.gitignore 対象ファイルの確認
git add 前に対象ファイルが無視されていないか確認- 無視設定は3箇所に存在する（優先度順）:
.gitignore（リポジトリ内、コミット対象）.git/info/exclude（リポジトリ内、コミット対象外）~/.config/git/ignore（グローバル設定）
- 確認コマンド:
git check-ignore -v <filepath>
- 出力例:
.gitignore:3:*.log debug.log → .gitignore の3行目のルールでマッチ
-
無視されたファイルを追加する必要がある場合
- ユーザーに確認を取る
git add -f は原則禁止（秘密情報や生成物の誤コミット防止）- 正当な理由がある場合のみ
.gitignore の修正を提案する
- 生成物（
node_modules、dist、build）は基本コミットしない
-
git add -A / git add . のリスク
- 意図しないファイル（
.env、node_modules、ビルド成果物等）を追加する恐れ
- 可能な限り
git add <specific-files> で明示的に追加
- 使用する場合は
git status で追加対象を事前確認
エラー時の対応
| エラーメッセージ | 原因 | 対応 |
|---|
The following paths are ignored by one of your .gitignore files | 無視設定で除外 | 下記の診断手順を実行 |
fatal: pathspec did not match any files | ファイルが存在しない | パスを再確認 |
Changes not staged for commit | add 忘れ | git add してから commit |
「なぜ add できないか」診断手順
git check-ignore -v <filepath>
pre-commit hook 失敗時の対応
| 状況 | 正しい対応 | 禁止事項 |
|---|
| hook 失敗後 | 修正 → git add → 新規 commit | --amend は絶対禁止 |
| lint エラー | 自動修正可能なら --fix | 手動修正後に再 add 忘れ |
| test 失敗 | テスト修正 or 実装修正 | --no-verify でスキップ |
重要: hook 失敗時、コミットは実行されていない。--amend すると直前の別コミットを破壊する。
リカバリー手順:
- hook のエラー出力を確認
- 指摘された問題を修正
git status で状態確認git add <修正したファイル>- 新しいコミットを作成（同じメッセージでも可）
自動生成ディレクトリの扱い
以下のパターンはコミット対象外（.gitignore に追加推奨）:
| ディレクトリ | 用途 | 対応 |
|---|
.codex-collab/ | Codex 連携ログ | .gitignore に追加 |
docs/requirements/.work/ | 要件定義中間成果物 | すでに gitignore 対象 |
node_modules/, dist/, build/ | ビルド成果物 | .gitignore に追加 |
確認コマンド:
git check-ignore -v <directory>
