whygit

whygit

Git リポジトリで何が起きたのでしょうか？どうすれば直せますか？

whygit は Git リポジトリを調べ、その状態と、問題を解決するコマンドをわかりやすく説明します。マージコンフリクト、途中で止まったリベース、detached HEAD、拒否されたプッシュ、GitHub に受け付けられないログイン、GitHub が拒否する 120 MB の CSV などに対応します。エラーメッセージを貼り付ければ、それについても説明します。

Git を初めて使う人向けに作られています。Git 自身のメッセージは正確ですが読みにくいため、whygit は短い説明と具体的な修正方法に置き換えます。

リポジトリは読み取るだけです。提案する修正を実行することはないため、自分で操作を管理し、使いながらコマンドを学べます。

同じエンジンを使う、2 通りの利用方法があります。

• コマンドラインで、AI ツールを使わずに利用する：whygit。
• MCP サーバーとして利用することで、Claude Code、Claude Desktop、Cursor などのアシスタントが git status から推測するのではなく、信頼できる診断を得られます。

インストール

whygit の実行には Python 3.10 以降と Git が必要です。以下から 1 つ選んでください。

uv tool install whygit     # with uv (https://docs.astral.sh/uv/)
pipx install whygit        # with pipx
uvx whygit                 # run once without installing

macOS、Windows、Linux のいずれでも同じように動作します。

ターミナルから使う

プロジェクトフォルダー内で実行します。

whygit                    # what's wrong here, most urgent first
whygit status             # a plain summary: branch, upstream, what's changed
whygit explain "fatal: refusing to merge unrelated histories"
git push 2>&1 | whygit explain -

オプション：別のフォルダーを調べるには --path <folder>（または -C）、機械可読な出力には --json、色を無効にするには --no-color を指定します。色は実際のターミナルでのみ使われ、NO_COLOR が設定されている場合は使われません。

終了コード：0 ブロックする問題が見つからなかった、1 ブロックする問題が見つかった、2 使い方が正しくない（例：フォルダーが存在しない）、3 explain がメッセージを認識できなかった。

例

$ whygit
whygit: /Users/sam/ds3500/hw2 (branch main)

[BLOCKING] Merge in progress with conflicts in 1 file
  Git tried to combine two lines of work, but both changed the same part of these
  files, so it stopped and is waiting for you to choose what the result should be.
  Nothing is lost while you decide.
  Conflicted files:
    - analysis.py  (both changed)
  How to fix:
    Finish the merge:
      1. Open each file and find the blocks between <<<<<<< and >>>>>>>. The part
         above ======= is one version, the part below is the other. Keep what you
         want, and delete the three marker lines.
      2. git add analysis.py
         Marks the files as resolved
      3. git commit --no-edit
         Records the merge and finishes it
    Or cancel the merge:
      1. git merge --abort
         Puts everything back the way it was before the merge started
  Learn more: https://git-scm.com/docs/git-merge#_how_to_resolve_conflicts

1 blocking. whygit never runs these commands for you; copy the ones you want.

作業を失う可能性のあるコマンド（git restore、git rebase --skip、git push --force-with-lease など）には必ず警告が付けられ、安全な選択肢がある場合はそちらが先に表示されます。

AI アシスタントと使う（MCP）

whygit mcp は、読み取り専用の 3 つのツールを備えた Model Context Protocol サーバーを stdio 経由で実行します。

ツール	使用する場面	返される内容
diagnose_repo(path=".")	何かが止まっている、または壊れているように見える場合	見つかった問題すべて。緊急度の高い順に、説明と修正方法を表示
explain_git_error(error_text, path=None)	git コマンドがエラーを出力した場合	エラーの意味と修正方法。path が指定されていれば、リポジトリの状態も使用
explain_state(path=".")	状況を中立的に要約したい場合	ブランチ、アップストリーム、先行／遅延、リモート、ステージ済みファイルと変更されたファイル、進行中の操作

結果は小さな JSON オブジェクトです。絶対パスを渡してください。相対パスはサーバーの作業ディレクトリを基準に解決されます。デスクトップアプリの場合、通常これはプロジェクトの場所ではありません。~ も使えます。

Claude Code

claude mcp add --scope user whygit -- uvx whygit mcp

--scope user を指定すると、すべてのプロジェクトで利用できるようになります。省略すると、現在のプロジェクトにのみ追加されます。claude mcp list で確認してください。

Claude Desktop

Settings > Developer > Edit Config を開き、claude_desktop_config.json に whygit を追加します（macOS では ~/Library/Application Support/Claude/、Windows では %APPDATA%\Claude\）。

{
  "mcpServers": {
    "whygit": {
      "command": "uvx",
      "args": ["whygit", "mcp"]
    }
  }
}

Claude Desktop を再起動します。uvx が見つからない場合は、which uvx（macOS）または where uvx（Windows）で表示されるフルパスを command として指定してください。

Cursor

同じブロックを ~/.cursor/mcp.json（すべてのプロジェクトに適用）またはプロジェクト内の .cursor/mcp.json に追加します：

{
  "mcpServers": {
    "whygit": {
      "command": "uvx",
      "args": ["whygit", "mcp"]
    }
  }
}

uv tool install または pipx で whygit をインストールした場合は、代わりに "command": "whygit" と "args": ["mcp"] を使用できます。

認識する状態

リポジトリの状態：マージコンフリクト（解決済みでもコミットされていないマージや、残っている <<<<<<< マーカーを含む）、コンフリクトまたは edit で停止中のリベース、進行中の cherry-pick、revert、 git am、bisect、detached HEAD（どのブランチからも指されていないコミットを含む）、upstream との分岐／遅れ／先行、まだ upstream が設定されていない状態（最初の git push -u）、リモートがない状態、upstream ブランチが削除された状態、まだコミットがない状態、リポジトリではない状態（1 階層上で操作している場合やホームフォルダーの場合を含む）、誤ってリポジトリにしてしまったホームフォルダー、ネストされたリポジトリ（ダウンロードしたスターターコードでよく見られます）、GitHub の 100 MB 制限（および 50 MB）を超える、ステージ済みまたは未プッシュのコミットに含まれるファイル、通常シークレットを含むファイル（.env、id_rsa、*.pem、kaggle.json、認証情報 JSON）、保存された出力が大きいノートブック、Jupyter ノートブックのコンフリクト、user.name／user.email の未設定、残った index.lock、および「dubious ownership」を理由に Git が拒否するフォルダー。

エラーメッセージ：プッシュの拒否、「You have divergent branches」、「refusing to merge unrelated histories」、GitHub のログイン失敗（パスワードは使えなくなったことを説明し、トークン、SSH、 gh auth login を案内します。トークンを尋ねることはありません）、「Permission denied (publickey)」、リポジトリが見つからない、403、「Your local changes would be overwritten」、邪魔になる未追跡ファイル、「not a git repository」、「src refspec main does not match any」、「pathspec did not match」、「remote origin already exists」、upstream の未設定、「couldn't find remote ref」、GitHub による大容量ファイルの拒否（GH001）、「detected dubious ownership」、「Please tell me who you are」、 index.lock が存在する状態、改行コードに関する警告、ネットワークエラーなどです。認識できないメッセージの場合は、その旨を伝え、代わりにリポジトリ内で確認できる情報を表示します。

読み取り専用の保証

whygit はリポジトリを変更しません。これは善意に委ねられているのではなく、コードで強制されています：

• すべての Git コマンドは、読み取り専用のサブコマンド（status、rev-parse、for-each-ref、rev-list、diff、log、ls-files、cat-file、config --get、remote -v、…）のみを受け付ける単一の関数を経由し、それ以外は拒否します。これには、書き込みを行う config、remote、symbolic-ref の形式も含まれます。
• GIT_OPTIONAL_LOCKS=0 を設定するため、git status でさえインデックスを更新しません。また、外部 diff プログラムと fsmonitor フックを無効にします。
• git fetch は実行しません。先行／遅れの数は「最後に fetch した時点の状態」です。必要な場合は、自分で git fetch を実行するよう whygit が案内します。
• テストスイートは、実際のリポジトリで各状態を作成し、診断の前後に .git 内のすべてのファイル（名前、タイムスタンプ、内容）をスナップショットして、何も変更されていないことを確認します。また、パッケージ内の他のモジュールがプロセスを起動したり、ファイルを書き込んだりできないことも確認します。

認証情報は表示されません。https://name:[email protected]/... のようなリモートアドレスは、すべての出力で https://***@github.com/... と表示されます。

プライバシー

whygit は何も収集せず、ネットワークへの接続も行いません。お使いのコンピューター上でリポジトリを読み取り、結果を表示するだけです。それだけです。

ライセンス

MIT。Copyright (c) 2026 Kameswara Sai Srikar Manda.