gitcleanplan

gitcleanplan

ブランチの一覧はいつの間にか増えていきます。機能が取り込まれてもブランチは残り、実験を中止してもそのブランチは残ります。上流ブランチが消えても、ローカルコピーは残ったままです。勘でブランチを削除すると作業を失うことになりかねません。そこで gitcleanplan は中間の道を取ります。ブランチデータを渡すと、計画を返します。まず一覧を表示し、何も削除しません。

渡された各ブランチについて、計画では理由とともに次の3つの判断のいずれかを示します。

• keep — デフォルトブランチ、保護されたブランチ、現在チェックアウトされているブランチ、または単にまだアクティブなブランチです。
• review — マージ済みだが最近もアクティブなブランチ、上流ブランチがなくマージもされていないブランチ、または古くなっているがマージされていないブランチです。ほかの操作を行う前に、人が確認する価値のある整理候補です。
• delete — マージ済みで、かつ上流ブランチがないか、stale_days 以上古くなっているブランチです。ここに分類されるのは、マージ済みのブランチだけです。

判断には固定されたルールの順序が適用されるため、理由が曖昧になることはありません。デフォルトブランチは保護より優先され、保護はマージ済みかつ上流ブランチがない状態より優先され、チェックアウト中であることはマージ済みであることより優先され、「マージ済みで上流ブランチがない」状態は「マージ済みで古くなっている」状態より優先されます。古さの判定には境界値を含みます。最後のコミットがちょうど stale_days 日前のブランチは、古いものとして扱われます。

ブランチごとの判断に加えて、結果ではアクションごとにブランチ名をまとめ、その数を数え、削除予定のブランチごとに安全な削除コマンド（git branch -d <name>）を名前順で一覧表示します。これらのコマンドは一覧表示されるだけで、実行されることはありません。gitcleanplan は git を呼び出さず、リポジトリを開かず、何も削除しません。計画を読んだうえで、実行する内容は自分で判断します。

不正な入力（ブランチリストがない、または空、ブランチ名がない、空、または重複している、last_commit_days_ago がない、負の値、または整数以外、フラグの型が正しくない、不正な stale_days または default_branch）は、問題のあるパスを示す検証エラーになります（例：branches[1].last_commit_days_ago must be an integer >= 0）。部分的な計画は生成されません。処理は純粋かつローカルで行われます。ネットワークも設定も必要なく、渡された入力以外のファイルを読み込むこともありません。

CLI

npx @reneturcios/gitcleanplan plan --input args.json
npx @reneturcios/gitcleanplan --version

args.json には引数オブジェクト全体が含まれます。

{
  "stale_days": 90,
  "branches": [
    { "name": "main", "last_commit_days_ago": 0, "current": true },
    { "name": "shipped-feature", "merged": true, "upstream_gone": true, "last_commit_days_ago": 45 },
    { "name": "old-spike", "last_commit_days_ago": 180 }
  ]
}

ブランチごとの merged、upstream_gone、protected、current のデフォルト値は false です。stale_days のデフォルト値は 90、default_branch のデフォルト値は "main" です。計画は JSON として出力されます。

{
  "branches": [
    { "name": "main", "action": "keep", "reason": "default branch" },
    { "name": "old-spike", "action": "review", "reason": "stale but not merged" },
    { "name": "shipped-feature", "action": "delete", "reason": "merged and upstream is gone" }
  ],
  "plan": {
    "delete": ["shipped-feature"],
    "review": ["old-spike"],
    "keep": ["main"]
  },
  "counts": { "delete": 1, "review": 1, "keep": 1 },
  "commands": ["git branch -d shipped-feature"]
}

終了コード：成功時は 0、実行時エラー（読み取り不能または無効な入力ファイル、無効な入力を含む）では 1、使用法エラーでは 2 です。

MCP サーバー

npx -y @reneturcios/gitcleanplan mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "gitcleanplan": {
      "command": "npx",
      "args": ["-y", "@reneturcios/gitcleanplan", "mcp"]
    }
  }
}

ツール

• plan_branch_cleanup — 古くなったブランチとマージ済みブランチの整理計画を作成します。
  • branches（配列、必須、1つ以上） — {name, last_commit_days_ago, merged?, upstream_gone?, protected?, current?} オブジェクトとして指定するブランチです。name はセット内で一意であり、last_commit_days_ago は0以上の整数日数です。
  • stale_days（整数、省略可能、デフォルト値は90、1以上） — 最後のコミットからこの日数が経過すると、ブランチは古いものとみなされます。
  • default_branch（文字列、省略可能、デフォルト値は "main"） — デフォルトブランチ名です。削除対象に指定されることはありません。

{branches, plan, counts, commands} を返します。

Docker

docker run -i ghcr.io/cloudcorprecords/gitcleanplan
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/gitcleanplan plan --input /w/args.json

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios