Create Graphite Stacked Diff

Create a stacked diff (commit + branch) from current changes using the Graphite CLI.

Stacked Diff Philosophy

Each diff in a stack should represent exactly one logical change. This makes code review easier and allows changes to land independently. When generating commit messages, think about what single thing this diff accomplishes.

Good examples of atomic changes:

• Add a new function or component
• Fix a specific bug
• Refactor a single module
• Update configuration for one purpose

Avoid combining unrelated changes in a single diff.

Execution Steps

Execute these steps in order. Stop and report errors if any step fails.

Step 1: Validate Environment

Run both commands to verify the environment is ready:

git rev-parse --is-inside-work-tree

If this fails, tell the user: "Not in a git repository. Navigate to a git repo first."

gt --version

If this fails, tell the user: "Graphite CLI not found. Install with: npm install -g @withgraphite/graphite-cli@latest"

Step 2: Check for Changes

git status --short

If output is empty, tell the user: "No changes to commit." and stop.

git diff --stat

Note the files changed count and line changes for the summary.

Step 3: Analyze Changes for Commit Message

Run these commands to understand what changed:

git diff
git diff --staged

Also check recent commit style:

git log -5 --oneline

Step 4: Generate Commit Message

Based on the diff analysis, write a commit message following these rules:

Subject line (first line):

• Use conventional commit format: type(scope): description
• Types: feat, fix, refactor, docs, test, chore, perf, style, build, ci
• Scope is optional but helpful (module name, component, file area)
• Keep under 72 characters
• Use imperative mood ("add feature" not "added feature")
• No period at the end

Body (optional, separated by blank line):

• Explain what and why, not how (the diff shows how)
• Wrap at 72 characters
• Only include if the subject line needs clarification

Footer (required):

Co-Authored-By: Claude Code

Example commit message:

fix(auth): handle expired JWT tokens gracefully

Return 401 with clear error message instead of 500 when token
validation fails due to expiration.

Co-Authored-By: Claude Code

Step 5: Create the Diff

Run the gt create command with the generated message:

gt create --all -m "<commit_message>"

The --all flag stages all changes automatically. Pass the full commit message including the footer.

Step 6: Report Results

After successful creation, report to the user:

• The commit message that was used
• Number of files changed
• Lines added/removed
• The branch name created by gt

Example output format:

Diff created on branch: feature/auth-token-handling

Commit: fix(auth): handle expired JWT tokens gracefully

Changes: 3 files, +45 -12

Error Handling

If gt create fails:

• Show the exact error output from gt
• Common issues: not on a valid base branch, merge conflicts, gt not initialized
• Suggest running gt init if the repo hasn't been set up with Graphite

Important Notes

• Each invocation creates one diff in the stack
• The branch name is auto-generated by gt based on the commit message
• Use /graphite:submit (or /gt:submit) when ready to open a PR for this diff
• Multiple diffs can be stacked by running this command multiple times