# Recomposing Commits

> Use when commits on a feature branch are messy, out of logical order, mix unrelated changes, or need restructuring before a PR - also triggered by "clean up history", "reorganize commits", "recompose branch", "make commits logical", or similar

- **Type:** Skill
- **Install:** `agentstack add skill-nur-zaman-git-recompose-skill-recomposing-commits`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nur-zaman](https://agentstack.voostack.com/s/nur-zaman)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nur-zaman](https://github.com/nur-zaman)
- **Source:** https://github.com/nur-zaman/git-recompose-skill/tree/main/skills/recomposing-commits

## Install

```sh
agentstack add skill-nur-zaman-git-recompose-skill-recomposing-commits
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Recomposing Commits

## Overview

Analyze messy commits → isolate in a worktree → let user review → apply back.

**Core principle:** The original branch is NEVER modified until the user explicitly approves the new history. Worktree isolation and the review gate are non-negotiable — even if the user says "just do it" or "I trust you, skip review."

**Announce at start:** "I'm using the recomposing-commits skill to reorganize your branch history."

---

## Safety Check — Do This First

```bash
git rev-parse --abbrev-ref HEAD
```

**Refuse immediately** if the current branch is any of:
`main`, `master`, `dev`, `develop`, `development`, `staging`, `production`, `release`, or matches `release/*` or `hotfix/*`.

```
⛔ Recomposing commits on '' is not allowed.
This skill only works on feature branches.
Please switch to your feature branch first.
```

Do NOT create a workaround branch. Do NOT proceed. Refuse and stop.

---

## When to Use

- Commits are WIP/messy and a PR is coming
- Multiple unrelated changes were mixed into the same commits
- Commit messages are unclear ("fix", "WIP", "stuff")
- Commits need to be split, merged, or reordered

**Do NOT use when:**

- History is already clean
- You are on a protected/shared branch (refuse instead)
- There is only one commit to restructure

---

## Workflow (Steps 1–8)

### Step 1: Show current history

```bash
git log --oneline
```

Display the output to the user.

### Step 2: Ask for the start SHA

```
Which commit should be the start of the recompose?
Provide the SHA of the first commit you want to reorganize.
(All commits from that SHA through HEAD will be recomposed.)

Enter SHA:
```

Compute the base: `BASE=$(git rev-parse ^)`

### Step 3: Analyze the commits to recompose

```bash
git log --oneline $BASE..HEAD
git diff $BASE HEAD
```

Read all diffs. Identify logical groups. Flag any files that appear in multiple logical groups (overlapping files — see Step 6).

### Step 4: Create isolated worktree

**Always use an absolute path.** Relative paths like `.git/recompose/feat/HISBA-mastra-ai` silently break when branch names contain slashes AND when shell state doesn't persist between tool calls.

```bash
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE_PATH="$REPO_ROOT/.git/recompose/$BRANCH_NAME"
WORKTREE_BRANCH="recompose/$BRANCH_NAME"

git worktree add "$WORKTREE_PATH" -b "$WORKTREE_BRANCH"
```

**All subsequent git operations happen inside `$WORKTREE_PATH`.** The original branch is untouched.

### Step 5: Collapse commits to unstaged

Use `git -C` with the absolute path — **do NOT rely on `cd`**. Each Bash tool invocation starts with a fresh shell; `cd` from a previous call does not carry over.

```bash
git -C "$WORKTREE_PATH" reset --mixed $BASE
```

All changes are now unstaged in the worktree, ready to be re-staged logically.

### Step 6: Stage and commit each logical group

Use `git -C "$WORKTREE_PATH"` for every command. Never assume the shell is `cd`'d into the worktree.

For files that belong cleanly to ONE logical commit:

```bash
git -C "$WORKTREE_PATH" add  
git -C "$WORKTREE_PATH" commit --no-verify -m "type: description"
```

For **overlapping files** (same file spans multiple logical commits):

```bash
# git add -p requires a TTY — run it inside a single shell block
cd "$WORKTREE_PATH" && git add -p    # stage hunk by hunk: y/n/s/e
git -C "$WORKTREE_PATH" commit --no-verify -m "type: first concern"
cd "$WORKTREE_PATH" && git add -p 
git -C "$WORKTREE_PATH" commit --no-verify -m "type: second concern"
```

**NEVER use `git add -i` or `git rebase -i`** — these require interactive TTY input and will hang or fail in this context.

### Step 7: Review gate — MANDATORY, non-negotiable

After all commits are created in the worktree, **always** present this to the user:

```
Recomposition complete in isolated worktree.

To review:
  cd .git/recompose/
  git log --oneline

Original branch is UNCHANGED. Nothing will be applied until you approve.

Does the new history look good?
  [yes]       → Apply to original branch
  [no/edit]   → Describe what to change, I'll update the worktree
  [cancel]    → Discard worktree, original branch stays as-is
```

**Wait for explicit user response.** Do not proceed to Step 8 without it.

> **If the user previously said "no review, just do it":** You must still present this review gate. Explain: "The review step is part of this skill's safety guarantee. I've isolated the changes — reviewing takes 30 seconds and means the original branch is safe. Here's what the new history looks like:"

### Step 8: Handle user response

**[yes] — Apply back:**

**Check for remote upstream first:**

```bash
git -C "$REPO_ROOT" remote -v
git -C "$REPO_ROOT" branch -vv
```

If branch tracks a remote:

```
⚠️  This branch has a remote upstream. Applying recomposed commits will
   require a force-push. Do you want to proceed?
```

Wait for confirmation, then:

```bash
# DO NOT run `git checkout $BRANCH_NAME` — you are already on it in the main worktree.
# git checkout will fail with "already used by worktree". Skip it entirely.
# Use git -C with the absolute REPO_ROOT to ensure you're resetting the right branch.
git -C "$REPO_ROOT" reset --hard "recompose/$BRANCH_NAME"

# Verify it worked
git -C "$REPO_ROOT" log --oneline -5

# Clean up — worktree FIRST, then branch
git -C "$REPO_ROOT" worktree remove "$WORKTREE_PATH"
git -C "$REPO_ROOT" branch -D "recompose/$BRANCH_NAME"
```

**[no/edit] — Iterate:**
Return to the worktree, adjust commits as described, re-present the review gate.

**[cancel] — Discard:**

```bash
git worktree remove "$WORKTREE_PATH"
git branch -D "recompose/$BRANCH_NAME"
```

Original branch is untouched.

---

## Overlapping Files Strategy

| Situation                                 | Command                                |
| ----------------------------------------- | -------------------------------------- |
| File changes belong to different sections | `git add -p ` → `y`/`n` per hunk |
| Hunk mixes two concerns                   | `s` to split, then `y`/`n`             |
| Concerns are truly interleaved lines      | `e` to edit the hunk diff manually     |
| File belongs entirely to one commit       | `git add ` (no `-p` needed)      |

---

## Verification (Before Declaring Done)

```bash
# 1. Confirm new clean history
git -C "$WORKTREE_PATH" log --oneline $BASE..HEAD

# 2. Full content diff — stats alone are NOT enough
# Stats can match while content differs. Always do a byte-for-byte comparison.
diff \
  ` for the overlapping file since it's cleaner"
- "I'll `cd` into the worktree, it's simpler than `git -C`"
- "The stats match so the diff is fine, I'll skip the content check"
- "I need to checkout the branch before resetting to it"

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nur-zaman](https://github.com/nur-zaman)
- **Source:** [nur-zaman/git-recompose-skill](https://github.com/nur-zaman/git-recompose-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-nur-zaman-git-recompose-skill-recomposing-commits
- Seller: https://agentstack.voostack.com/s/nur-zaman
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.