Unverified Commit d95b7bff authored by Tim Neutkens's avatar Tim Neutkens Committed by GitHub

docs: improve Graphite workflow documentation (#89488)

### What?

Improves the Graphite workflow documentation in
`.cursor/commands/gt-workflow.md`.

### Why?

The previous documentation was unclear about when to use `gt` vs `git`
commands, leading to potential workflow issues.

### How?

- Clarifies that `gt` should be used for ALL git commands (not just
specific ones)
- Adds a critical section about staging changes BEFORE running `gt
create` to avoid creating empty branches
- Updates all `git` references to `gt` for consistency (`git show` → `gt
show`, `git status` → `gt status`, etc.)
- Improves the command reference table with `gt add`
- Reorganizes checklists for clarity

### Improving Documentation

- [x] Run `pnpm prettier-fix` to fix formatting issues before opening
the PR (handled by lint-staged)
parent c28948e0
...@@ -4,17 +4,28 @@ ...@@ -4,17 +4,28 @@
Use Graphite (`gt`) instead of git for ALL branch and commit operations in this repository. Use Graphite (`gt`) instead of git for ALL branch and commit operations in this repository.
## Forbidden Git Commands ## Use `gt` Instead of `git`
NEVER use these git commands directly: All git commands work with `gt`. Always use `gt` instead of `git`:
- `git push` → use `gt submit --no-edit` ```bash
- `git branch` → use `gt create` 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 ## Graphite Commands
| Command | Description | | Command | Description |
| -------------------------------------- | ------------------------------------------- | | -------------------------------------- | ------------------------------------------- |
| `gt add <files>` | Stage files for commit |
| `gt create <branch-name> -m "message"` | Create a new branch with 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 modify -a --no-edit` | Stage all and amend current branch's commit |
| `gt checkout <branch>` | Switch branches | | `gt checkout <branch>` | Switch branches |
...@@ -22,6 +33,25 @@ NEVER use these git commands directly: ...@@ -22,6 +33,25 @@ NEVER use these git commands directly:
| `gt submit --no-edit` | Push and create/update PRs | | `gt submit --no-edit` | Push and create/update PRs |
| `gt log short` | View stack status | | `gt log short` | View stack status |
## Creating a New Branch with Changes
**CRITICAL**: Always stage changes BEFORE running `gt create`. The command format is:
```bash
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:**
```bash
gt add <files>
gt commit -m "commit message" # Create initial commit
gt submit --no-edit # Then submit
```
## Creating PRs with Descriptions ## Creating PRs with Descriptions
All PRs require a description. Use this workflow: All PRs require a description. Use this workflow:
...@@ -35,13 +65,12 @@ gh pr edit <pr-number> --body "Place description here" ...@@ -35,13 +65,12 @@ gh pr edit <pr-number> --body "Place description here"
- Graphite force-pushes everything - old commits only recoverable via reflog - Graphite force-pushes everything - old commits only recoverable via reflog
- Never have uncommitted changes when switching branches - they get lost during restack - Never have uncommitted changes when switching branches - they get lost during restack
- Never use `git stash` with Graphite - causes conflicts when `gt modify` restacks - Never use `gt stash` with Graphite - causes conflicts when `gt modify` restacks
- Never use `git checkout HEAD -- <file>` after editing - silently restores unfixed version - Never use `gt checkout HEAD -- <file>` after editing - silently restores unfixed version
- Always use `gt checkout` (not `git checkout`) to switch branches
- `gt modify --no-edit` with unstaged/untracked files stages ALL changes - `gt modify --no-edit` with unstaged/untracked files stages ALL changes
- `gt sync` pulls FROM remote, doesn't push TO remote - `gt sync` pulls FROM remote, doesn't push TO remote
- `gt modify` restacks children locally but doesn't push them - `gt modify` restacks children locally but doesn't push them
- Always verify with `git status -sb` after stack operations - Always verify with `gt status -sb` after stack operations
## Safe Multi-Branch Fix Workflow ## Safe Multi-Branch Fix Workflow
...@@ -49,19 +78,25 @@ gh pr edit <pr-number> --body "Place description here" ...@@ -49,19 +78,25 @@ gh pr edit <pr-number> --body "Place description here"
gt checkout parent-branch gt checkout parent-branch
# make edits # make edits
gt modify -a --no-edit # Stage all, amend, restack children gt modify -a --no-edit # Stage all, amend, restack children
git show HEAD -- <files> # VERIFY fix is in commit gt show HEAD -- <files> # VERIFY fix is in commit
gt submit --no-edit # Push immediately gt submit --no-edit # Push immediately
gt checkout child-branch # Already restacked from gt modify gt checkout child-branch # Already restacked from gt modify
# make edits # make edits
gt modify -a --no-edit gt modify -a --no-edit
git show HEAD -- <files> # VERIFY gt show HEAD -- <files> # VERIFY
gt submit --no-edit gt submit --no-edit
``` ```
## Checklist ## 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
- [ ] Using `gt` commands instead of `git push`/`git branch` - [ ] Always use `gt` instead of `git`
- [ ] No uncommitted changes before switching branches - [ ] No uncommitted changes before switching branches
- [ ] Verified changes with `git status -sb` after stack operations - [ ] Verify with `gt status -sb` after stack operations
- [ ] PR description follows `.github/pull_request_template.md` format
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment