Skip to content

docs: document gw new --stack and structural base selection #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zawakin merged 1 commit into from
Jun 29, 2026
Merged

docs: document gw new --stack and structural base selection #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion .claude/skills/git-workflow/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ prints one `Next:` line. Follow it. This is the situation → action → reason

| When | What | Why |
|------|------|-----|
| Starting | `gw new feature/your-feature` | New branch from `origin/main`. If you already edited on home, `gw new` keeps the changes and moves them onto the branch. |
| Starting | `gw new feature/your-feature` | New branch from `origin/main`. Run it **from home** — if you already edited there, `gw new` carries those changes onto the branch. From a feature branch it refuses (the base is ambiguous): use `--stack` to build on it, or `gw home` first to start fresh. |
| Code is ready to record | stage intentionally → `git commit -m "feat: ..."` | See **Staging** below — review before committing. |
| Committed | `git push -u origin feature/your-feature` | Publish for the PR. |
| Pushed | `gh pr create -a "@me" -t "feat: ..."` | Open the PR; the URL gives you the PR number. |
Expand Down Expand Up @@ -63,6 +63,29 @@ git commit -m "feat: ..."
files, unrelated edits, and stray config — things you didn't mean to ship.
Stage the specific paths for *this* change instead.

## Situation: stacking a PR on top of another

When the next change depends on a branch whose PR is still open, stack on it
instead of waiting:

```sh
gw new feature/child --stack # base on the CURRENT branch, not origin/main
git commit -m "feat: ..."
git push -u origin feature/child
gh pr create -a "@me" -B feature/parent -t "..." # -B sets the PR base to the parent
```

| When | What | Why |
|------|------|-----|
| Next change builds on an open PR's branch | `gw new <child> --stack` (from the parent branch) | Bases the child on the parent's HEAD, not `origin/main`. |
| Creating the stacked PR | `gh pr create -B <parent> ...` | A locally-stacked branch doesn't make GitHub default the base to the parent — set it explicitly with `-B`. |
| Parent PR later merges | `gw sync` | Restacks the child onto `main` (updates base, rebases, force-pushes). The teardown half of stacking. |

`gw new` chooses a base unambiguously: it auto-bases on `origin/main` only from
home; from a feature branch you must say `--stack` (or `gw home` first). A dirty
tree is carried on the current HEAD, so creating the branch never hits a merge
conflict.

## Situation: work gets interrupted or goes wrong

| When | What | Why |
Expand Down
6 changes: 4 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Add to your project's `CLAUDE.md`:

Use `git-workflow` commands for git operations:

- `git-workflow new feature/name` - Create branch (auto-fetches from origin)
- `git-workflow new feature/name` - Create branch from origin/main (auto-fetches); `--stack` bases on the current branch for stacked PRs
- `git-workflow status` - Check state and see next action
- `git-workflow pause "message"` - Save WIP and switch context
- `git-workflow cleanup` - Delete merged branch safely
Expand Down Expand Up @@ -83,7 +83,8 @@ git-workflow cleanup

| Command | Description |
|---------|-------------|
| `git-workflow new <branch>` | Create branch from `origin/main` (fetches first) |
| `git-workflow new <branch>` | Create branch from `origin/main` (fetches first); refuses off home unless `--stack` |
| `git-workflow new <branch> --stack` | Stack a new branch on the current branch (for stacked PRs) |
| `git-workflow status` | Show state and suggested next action |
| `git-workflow home` | Return to home branch, sync with origin |
| `git-workflow sync` | Sync current branch with origin/main |
Expand Down Expand Up @@ -147,6 +148,7 @@ If `GW_NOTIFY_CMD` is unset, the notification step is simply skipped.
- **Protected branches**: Cannot delete `main`, `master`, or home branch
- **PR verification**: `cleanup` checks GitHub PR status before deletion
- **Fast-forward only**: `sync`/`home` refuse to create merge commits on diverged branches
- **Unambiguous base**: `new` auto-bases on `origin/main` only from home; elsewhere it requires `--stack`. A dirty tree is carried on the current HEAD, so creating a branch never hits a merge conflict

## Git Worktree Support

Expand Down