# Squash

> Analyze branch commits and consolidate iterative modifications.

- Skill: `tencent/squash` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add tencent/squash`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tencent/squash/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tencent (https://skillmd.com/u/tencent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tencent/squash

---


# Squash — Consolidate Branch History

Analyzes commits on the current branch and consolidates them into clean,
logical units. The original branch is untouched until the user explicitly
confirms the result. Heavy git operations are delegated to Python scripts
(`scripts/` directory) that enforce safety checks.

## Instructions

- **NEVER** operate on the default branch (main/master).
- All user-facing text must match the language the user has been using.
- When presenting choices, use interactive dialogs with selectable options
  rather than plain text.
- Scripts are at `.codebuddy/skills/squash/scripts/` relative to repo root.
  Use `python3` to run them. **NEVER** read or modify the script contents.

### Cleanup procedure

Whenever stopping due to failure or user discard, extract these values from
the latest successful step output (if available), then run:

```bash
git worktree remove --force {worktree_path}
git branch -D {tmp_branch}
rm -rf {session_dir}
```

| Field | Source |
|---|---|
| `worktree_path` | Step 4 output (on Step 4 failure or Step 5 discard) |
| `tmp_branch` | Step 4 output (on Step 4 failure or Step 5 discard) |
| `session_dir` | Step 2 output (on Step 2/3 failure) |

If these values cannot be determined (e.g., Step 2 failed before creating
session_dir), skip the cleanup that depends on them. Errors during cleanup
can be safely ignored—resources will eventually be removed by `resolve_scope.py`
on the next run.

---

## Step 1: Cleanup

If `$ARGUMENTS` is **empty**, run:

```
python3 scripts/resolve_scope.py {repo_dir}
```

The script validates that the current branch is not the default branch, and
cleans up stale sessions from previous runs. If it fails, inform the user
and stop.

If `$ARGUMENTS` is non-empty (a branch name), **skip this step** — validation
is handled by the collect script in Step 2.

---

## Step 2: Collect Commits

Two modes depending on `$ARGUMENTS`:

- **No argument** — squash unpushed commits on the current branch:
  ```
  python3 scripts/collect_commits.py {repo_dir}
  ```
- **Branch name** (e.g. `/squash feature/foo`) — squash the entire named
  branch (does not require checking it out):
  ```
  python3 scripts/collect_commits.py {repo_dir} $ARGUMENTS
  ```

If the script fails, inform the user and stop.

Record `{session_dir}` from the output — all temporary files and the worktree
will live inside this directory throughout the session.

If `commits` is empty, inform the user and stop.
Present the `commit_table` field to the user.

---

## Step 3: Analyze & Decide

Use `commits` (with `subject`, `files`, `is_merge`, `quality_flag`) and
`overlaps` (adjacent pair file overlap ratios) from Step 2.

### Grouping

Group adjacent commits belonging to the same logical change when **either**:

1. **File overlap ≥ 30 %** (from `overlaps`).
2. **Message similarity** — same module/feature keyword, or follow-up pattern.

A `"revert"` commit should be grouped with the commit it reverts. If both are
adjacent, squashing them cancels them out.

**Never** group across a merge commit. **Never** include a merge commit in a
squash group. Never reorder commits.

### Messages

Synthesize a new commit message for each squash group. Rewrite any commit with
a non-null `quality_flag`.

If nothing to merge or rewrite, inform the user the history is clean and
**stop**.

### Output — Decision Table

Write to `{session_dir}/decision.json`:

```json
{
  "session_dir": "...",
  "repo_dir": "...",
  "branch": "...",
  "squash_base": "<full_hash>",
  "squash_end": "<full_hash>",
  "upstream_remote": null,
  "upstream_merge": null,
  "actions": [
    {"type": "keep",   "commits": ["<hash>"]},
    {"type": "squash", "commits": ["<hash1>", "<hash2>"], "message": "..."},
    {"type": "reword", "commits": ["<hash>"], "message": "..."},
    {"type": "merge",  "commits": ["<hash>"]}
  ]
}
```

Copy `session_dir`, `repo_dir`, `branch`, `squash_base`, `squash_end`,
`upstream_remote`, `upstream_merge` directly from Step 2 output.

Rules: chronological order (oldest first), every commit in exactly one action,
full 40-char hashes, `squash`/`reword` require `message`, `merge` must have
exactly one commit, `squash` must never contain a merge.

---

## Step 4: Build New History

```
python3 scripts/build_history.py {session_dir}/decision.json
```

On failure → run cleanup procedure and stop (error output includes
`worktree_path` and `tmp_branch`).

On success, parse the JSON output and record `{worktree_path}`, `{tmp_branch}`,
and `{current_head}` from it. The script automatically handles any commits
added after `squash_end` — no manual git operations needed.

---

## Step 5: User Confirmation

**Mandatory interaction point. Do NOT skip.**

```
python3 scripts/format_report.py {session_dir}/decision.json
```

Present the report (showing planned changes), then ask: **Confirm** / **Discard**.
Wait for response.

**Note:** The reported "new commit count" in the format report is an estimate
based on the decision table. The actual count after execution (which accounts
for zero-diff groups being skipped) will be shown in Step 6 results.

**Discard** → run cleanup procedure and stop.

---

## Step 6: Replace Branch

Write `{session_dir}/replace.json` using values from prior steps, then run:

```
python3 scripts/replace_branch.py {session_dir}/replace.json
```

| Field | Source |
|---|---|
| `repo_dir` | Step 2 output |
| `branch` | Step 2 output (`branch` field — may be a non-current branch) |
| `tmp_branch` | Step 4 output |
| `worktree_path` | Step 4 output |
| `current_head` | Step 4 output |
| `upstream_remote` | Step 2 output |
| `upstream_merge` | Step 2 output |

The script automatically appends any new commits added since `{current_head}`,
verifies tree equality, and atomically updates the branch ref. On success it
removes the worktree and tmp branch.

On failure → run cleanup procedure and stop.

On success:

```
rm -rf {session_dir}
```

Report using `new_commit_count` from Step 4 output (which accounts for commits
skipped due to zero-diff groups):

`Squash complete: {original_commit_count} commits → {new_commit_count} commits`

---

## Step 7: Offer to Push

If the branch has upstream tracking **and** the remote tracking point is an
ancestor of the new HEAD, ask: **Push** / **Skip**.

Otherwise, end silently.