Reference

トラブルシューティング

よくあるエラー・つまずきの「症状 → 原因 → 対処」を集めました。32項目を8カテゴリに整理しています。 検索ボックスにエラーメッセージの一部を貼り付けると素早く見つかります。

🔌始められない・接続できない

🚨fatal: not a git repository (or any of the parent directories): .git
原因:今いるフォルダはGitリポジトリ（.git/ がある場所）ではありません。
対処:そのフォルダで管理を始めたいなら git init を実行。すでに作ってあるなら cd で正しいフォルダに移動。 
git init
🚨fatal: remote origin already exists.
原因:同じ名前 origin のリモートがすでに登録されている。
対処:git remote -v で現在のURLを確認。書き換えたいなら set-url、消したいなら remove。 
git remote set-url origin <新しいURL>
# または
git remote remove origin
🚨Permission denied (publickey).
原因:SSH鍵がGitHub等のサービスに登録されていない。
対処:一番楽なのはHTTPSのURLに切り替えること（https://github.com/.../<repo>.git）。SSHを使うなら ssh-keygen で鍵を生成し、公開鍵 (~/.ssh/id_ed25519.pub) をサービス側のSSHキー設定に登録。 
git remote set-url origin https://github.com/USER/REPO.git
🚨fatal: Authentication failed for ...
原因:GitHub は2021年以降、HTTPS push でパスワード認証を廃止。Personal Access Token (PAT) が必要。
対処:GitHub → Settings → Developer settings → Personal access tokens でトークンを生成し、パスワード欄に貼り付ける。次回から省略するなら credential.helper を有効化。 
git config --global credential.helper store

💾コミットできない・コミットがおかしい

🚨nothing to commit, working tree clean（編集したのに変更なしと言われる）
原因:編集したファイルが .gitignore で無視されている、または別フォルダのファイルを触っている。
対処:git status で実際の変更を確認。.gitignore に該当パターンがないか確認。 
git status
cat .gitignore
🚨*** Please tell me who you are.（初コミットで出る）
原因:user.name と user.email が未設定。
対処:グローバル設定すれば一度きり。個別リポジトリで違う名前にしたいなら --global を外す。 
git config --global user.name "Taro"
git config --global user.email "you@example.com"
🚨直前のコミット作者・メールが間違っていた
原因:user.name / user.email の設定ミス、または別アカウントのまま作業していた。
対処:設定を直してから --amend で著者をリセット。複数コミットを直したい場合は filter-repo（上級）。 
git config --global user.email "正しい@example.com"
git commit --amend --reset-author --no-edit
🚨直前のコミットメッセージにタイポがある
原因:気づいたのが push 前なら簡単。
対処:まだ push していなければ --amend で上書き。push 済みなら新コミットで補足するのが安全。 
git commit --amend -m "正しいメッセージ"

⬆️push でつまずく

🚨! [rejected] main -> main (fetch first) / Updates were rejected because ...
原因:リモートに自分が持っていないコミットがある。
対処:まず git pull で取り込んでから push。コンフリクトを履歴に残したくないなら --rebase。 
git pull --rebase
git push
🚨fatal: The current branch has no upstream branch
原因:ローカルブランチがリモートのどのブランチに対応するかが未設定（初push時に多い）。
対処:-u オプションで紐付けを設定すれば、次回以降は git push だけで送れる。 
git push -u origin main
🚨rebase したら push が拒否される。--force したい
原因:rebase はコミットIDを書き換えるので、リモートと食い違って通常 push は拒否される。
対処:自分専用ブランチに限定し、--force-with-lease を使う（他人が push していたら拒否される安全版）。共有ブランチでは絶対NG。 
git push --force-with-lease origin <branch>

⬇️pull / clone でつまずく

🚨fatal: refusing to merge unrelated histories
原因:ローカルとリモートに共通の祖先コミットがない（先に init して、後から remote add した等）。
対処:一度だけ --allow-unrelated-histories を付けて pull。コンフリクト解消が必要になることがある。 
git pull origin main --allow-unrelated-histories
🚨error: Your local changes to the following files would be overwritten by ...
原因:未コミットの編集があり、pull や switch で上書きされそう。
対処:コミットするか、stash で退避してから再実行。 
git stash
git pull
git stash pop
🚨fatal: pathspec 'xxx' did not match any files
原因:ファイル名のタイポ、または存在しないパス。
対処:ls / dir で実際のファイル名を確認。大文字小文字も含めて一致させる。 
ls
git status

⚔️マージ・コンフリクト

🚨CONFLICT (content): Merge conflict in <file>
原因:両方のブランチが同じ行を別々に編集していた。
対処:ファイルを開き、<<<<<<< === >>>>>>> マーカーで挟まれた両者を見比べ、残したい内容に手で書き換える → 保存 → add → commit。 
# 編集後
git add <file>
git commit
🚨マージの途中で「やっぱりやめたい」
原因:コンフリクト解消が大変／間違ったブランチをマージしてしまった。
対処:merge を始める前の状態に安全に戻せる。reset --hard より安全。 
git merge --abort
# rebase 中なら
git rebase --abort

⏪取り消したい・戻したい

🚨直前のコミットを完全になかったことにしたい（ローカルのみ）
原因:編集も含めて捨てたい場合。
対処:reset --hard は強力だが破壊的。直前のコミットだけなら HEAD~1 を指定。push 済みなら使わない。 
git reset --hard HEAD~1
🚨直前のコミットを取り消したいが、編集は残しておきたい
原因:ステージング状態に戻して整理し直したい。
対処:--soft を使うと編集はステージングに、--mixed（デフォルト）ならワーキングツリーに残る。 
git reset --soft HEAD~1
🚨push 済みのコミットを取り消したい
原因:共有された後の取り消しは、履歴を書き換えると他人が困る。
対処:「打ち消しコミット」を新たに作る revert を使う。決して push --force しない。 
git revert <commit-id>
git push
🚨git pull したら勝手にマージされて履歴が汚くなった
原因:fast-forward できないときに自動でマージコミットが作られた。
対処:直前なら ORIG_HEAD で pull 前に戻せる（ローカル限定）。今後は --rebase 運用がおすすめ。 
git reset --hard ORIG_HEAD
# 今後の運用
git config --global pull.rebase true
🚨間違ったブランチでコミットしてしまった（push前）
原因:main にいるべきところを feature でコミット、またはその逆。まだリモートに push していない状態。
対処:正しいブランチに cherry-pick で移し、元のブランチは reset --hard で戻す。履歴を書き換える操作なので push前限定。 
# 例: feature でコミットしてしまった → main に移したい
git switch main
git cherry-pick <そのコミットID>
git switch feature
git reset --hard HEAD~1
🚨間違ったブランチでコミットしてしまった（push済み）
原因:間違いに気づく前に push してしまい、リモートにも残っている。
対処:元のブランチでは打ち消しコミット（revert）を作る。force push は他人の作業を壊すので使わない。 
# 例: feature に間違ってコミット＆pushしてしまった → main に移したい
# ① 正しいブランチ（main）にコピー
git switch main
git cherry-pick <そのコミットID>
git push
# ② 元のブランチ（feature）では打ち消しコミットを作る
git switch feature
git revert <そのコミットID>
git push
🚨コミットしたファイルを過去の状態に戻したい
原因:個別ファイルだけを以前のバージョンに巻き戻したい。
対処:restore --source で「どのコミットの状態に戻すか」を指定できる。 
git log --oneline -- <file>
git restore --source=<id> <file>

⌨️エディタ・ターミナル操作

🚨vim から抜けられない（コミット時の画面が閉じない）
原因:git commit を -m なしで実行するとデフォルトエディタ vim が起動。
対処:まず ESC キー → 編集を捨てて終わるなら :q! → Enter。書いて確定するなら :wq → Enter。 
:wq    # 保存して終了
:q!    # 保存せず終了
🚨今後 vim を使いたくない
原因:使い慣れたエディタにしたい。
対処:core.editor を変更。VS Code が入っているなら下記が定番。 
git config --global core.editor "code --wait"
# nano 派なら
git config --global core.editor "nano"
🚨detached HEAD state というメッセージが出た
原因:コミットIDやタグを直接 checkout/switch すると、ブランチに紐付かない状態（さまよう状態）になる。
対処:ここで作業して残したいなら新しいブランチを切る。戻すだけなら main に switch。 
# その場で残したい場合
git switch -c rescue-branch
# 戻るだけ
git switch main

🚨やってしまった！

🚨.env や秘密鍵をコミットしてしまった
原因:.gitignore に登録する前にコミットした、または add . で巻き込んだ。
対処:1) 履歴に残った時点で値は漏れたとみなし、即時ローテート（パスワード/トークンを再発行）。2) .gitignore に登録 → git rm --cached → 新コミット。3) push 済みなら git filter-repo で履歴から完全削除（高度）。Windows PowerShell では echo >> がBOM付きで壊れがち。Git Bash で実行するか .gitignore を直接エディタで編集してください。 
# Bash / zsh / Git Bash
echo ".env" >> .gitignore
git rm --cached .env
git commit -m "Untrack .env"
🚨巨大ファイル（動画・画像など）をコミットしてしまい push が遅い
原因:Git は大きなバイナリが苦手。リポジトリが肥大する。
対処:直近のコミットなら soft reset で巻き戻し → .gitignore に追加 → 再コミット。push 済みなら git filter-repo / BFG。今後は Git LFS の検討を。 
git reset --soft HEAD~1
echo "*.mp4" >> .gitignore
git add . && git commit -m "exclude large files"
🚨.DS_Store や Thumbs.db、*.swp が毎回コミットに混ざる
原因:OSやエディタが自動生成するファイル。プロジェクト個別に書くより、グローバルで除外するのが楽。
対処:グローバル .gitignore を設定。Windows PowerShell では echo >> がBOM付きで壊れるので、Git Bash で実行するか、~/.gitignore_global を直接エディタで作って中身を書いてください。 
# Bash / zsh / Git Bash
git config --global core.excludesfile ~/.gitignore_global
echo ".DS_Store" >> ~/.gitignore_global
echo "Thumbs.db" >> ~/.gitignore_global
echo "*.swp" >> ~/.gitignore_global
🚨ファイル名の大文字小文字を変えても変更扱いされない
原因:macOS / Windows の標準ファイルシステムは大文字小文字を区別しないため、Git からは「同じ」に見える。
対処:一度別名にしてから目的の名前に rename すると確実。 
git mv Readme.md README_TMP.md
git mv README_TMP.md README.md
git commit -m "Rename Readme.md → README.md"
🚨全ファイルが modified に見える／差分が大量に出る（CRLF と LF の混在）
原因:Windows と Mac/Linux で改行コードが異なり、core.autocrlf が未設定だと git が「全行を書き換えた差分」と判定する。
対処:OS に合わせて autocrlf を設定。Windows なら true（コミット時 LF、チェックアウト時 CRLF）、Mac/Linux なら input（コミット時 LF、チェックアウト時はそのまま）。既存ファイルを正規化したいときは設定後に git add --renormalize . でリセット。 
# Windows
git config --global core.autocrlf true
# Mac / Linux
git config --global core.autocrlf input
# 既存ファイルの正規化
git add --renormalize .
git commit -m "Normalize line endings"
🚨コミットを消してしまった！復活できる？
原因:reset --hard 等でコミット参照を失っても、Git の中には30日程度残る。
対処:reflog で過去のHEAD履歴を一覧 → 戻したいIDを見つけて reset --hard <id>。 
git reflog
git reset --hard <そのID>

⚠️ 履歴を書き換える操作（reset --hard / push --force / filter-repo）は、共有ブランチでは行わないでください。 他の人のローカル履歴と食い違って深刻な事故になります。「公開後の取り消しは git revert」が原則です。