From 9e438f688817a676d38b2963ce3e9c8c5d24e45b Mon Sep 17 00:00:00 2001 From: zawakin Date: Mon, 29 Jun 2026 20:18:47 +0900 Subject: [PATCH] docs: document gw new --stack and structural base selection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill and README still described `gw new` as always carrying changes onto the branch, with no mention of stacked PRs or the new structural rules. Update both: --stack for stacking on the current branch (with `gh pr create -B`), the feature-branch refusal, and the dirty→HEAD base guarantee. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/skills/git-workflow/SKILL.md | 25 ++++++++++++++++++++++++- README.md | 6 ++++-- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/.claude/skills/git-workflow/SKILL.md b/.claude/skills/git-workflow/SKILL.md index 638a30f..a123056 100644 --- a/.claude/skills/git-workflow/SKILL.md +++ b/.claude/skills/git-workflow/SKILL.md @@ -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. | @@ -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 --stack` (from the parent branch) | Bases the child on the parent's HEAD, not `origin/main`. | +| Creating the stacked PR | `gh pr create -B ...` | 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 | diff --git a/README.md b/README.md index e535e3c..6ad8ca3 100644 --- a/README.md +++ b/README.md @@ -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 @@ -83,7 +83,8 @@ git-workflow cleanup | Command | Description | |---------|-------------| -| `git-workflow new ` | Create branch from `origin/main` (fetches first) | +| `git-workflow new ` | Create branch from `origin/main` (fetches first); refuses off home unless `--stack` | +| `git-workflow new --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 | @@ -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