next.js/.cursor/commands/gt-workflow.md

Git Workflow with Graphite

Overview

Use Graphite (gt) instead of git for ALL branch and commit operations in this repository.

Use gt Instead of git

All git commands work with gt. Always use gt instead of git:

gt add <files>       # instead of git add
gt commit            # instead of git commit
gt status            # instead of git status
gt diff              # instead of git diff
# etc.

For branch/push operations, use the Graphite-specific commands:

• gt create <branch-name> -m "message" instead of git branch + git commit
• gt submit --no-edit instead of git push

Graphite Commands

Command	Description
gt add <files>	Stage files for commit
gt create <branch-name> -m "message"	Create a new branch with commit
gt modify -a --no-edit	Stage all and amend current branch's commit
gt checkout <branch>	Switch branches
gt sync	Sync and restack all branches
gt submit --no-edit	Push and create/update PRs
gt log short	View stack status

Creating a New Branch with Changes

CRITICAL: Always stage changes BEFORE running gt create. The command format is:

gt add <files>                               # Stage changes FIRST
gt create <branch-name> -m "commit message"  # Then create branch with commit

If you run gt create without staged changes, it creates an empty branch with no commit. Then gt modify -a --no-edit will fail because there's no commit to amend.

If you accidentally created an empty branch:

gt add <files>
gt commit -m "commit message"    # Create initial commit
gt submit --no-edit              # Then submit

Creating PRs with Descriptions

All PRs require a description. Use this workflow:

gt submit --no-edit
gh pr edit <pr-number> --body "Place description here"

Safety Rules

• Graphite force-pushes everything - old commits only recoverable via reflog
• Never have uncommitted changes when switching branches - they get lost during restack
• Never use gt stash with Graphite - causes conflicts when gt modify restacks
• Never use gt checkout HEAD -- <file> after editing - silently restores unfixed version
• gt modify --no-edit with unstaged/untracked files stages ALL changes
• gt sync pulls FROM remote, doesn't push TO remote
• gt modify restacks children locally but doesn't push them
• Always verify with gt status -sb after stack operations

Safe Multi-Branch Fix Workflow

gt checkout parent-branch
# make edits
gt modify -a --no-edit        # Stage all, amend, restack children
gt show HEAD -- <files>       # VERIFY fix is in commit
gt submit --no-edit           # Push immediately

gt checkout child-branch      # Already restacked from gt modify
# make edits
gt modify -a --no-edit
gt show HEAD -- <files>       # VERIFY
gt submit --no-edit

Checklist for Creating a PR

1. Stage changes: gt add <files>
2. Create branch with commit: gt create <branch-name> -m "message"
3. Push and create PR: gt submit --no-edit
4. Add PR description using .github/pull_request_template.md format: gh pr edit <pr-number> --body "..."

General Safety Checklist

• Always use gt instead of git
• No uncommitted changes before switching branches
• Verify with gt status -sb after stack operations