Skip to content

Commit 09d77c5

Browse files
luqvenluqven
authored
docs: streamline README and add command documentation (#29)
1 parent f573d5a commit 09d77c5

18 files changed

Lines changed: 560 additions & 307 deletions

‎README.md‎

Lines changed: 112 additions & 307 deletions
Large diffs are not rendered by default.

‎docs/annotate.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# gh-stack annotate
2+
3+
Add a markdown table to each PR description showing the full stack.
4+
5+
## Usage
6+
7+
```bash
8+
gh-stack annotate 'STACK-ID'
9+
gh-stack annotate 'STACK-ID' --badges # shields.io badges (public repos)
10+
gh-stack annotate 'STACK-ID' --ci # skip confirmation prompt
11+
gh-stack annotate 'STACK-ID' --prefix '#' # remove prefix from titles
12+
gh-stack annotate 'STACK-ID' -p file.md # prepend file contents
13+
```
14+
15+
## Output
16+
17+
Each PR in the stack gets a table added to its description:
18+
19+
```markdown
20+
### Stack: STACK-ID
21+
22+
| PR | Title | Base |
23+
|:--:|:------|:----:|
24+
| #103 | [STACK-ID] Add validation | #102 |
25+
| #102 | [STACK-ID] Implement feature | #101 |
26+
| #101 | [STACK-ID] Initial scaffolding | main |
27+
```
28+
29+
GitHub auto-links PR numbers. Hovering shows PR status.
30+
31+
## Flags
32+
33+
| Flag | Description |
34+
|------|-------------|
35+
| `--badges` | Use shields.io status badges (public repos only) |
36+
| `--ci` | Skip confirmation prompt |
37+
| `--prefix` | Characters to strip from PR titles in the table |
38+
| `-p`, `--prelude` | File to prepend before the table |
39+
| `-r`, `--repository` | Override repository (owner/repo) |
40+
| `-o`, `--origin` | Git remote name (default: origin) |
41+
| `-e`, `--excl` | Exclude PR by number (repeatable) |
42+
43+
## How it works
44+
45+
1. Finds all PRs with the identifier in their title
46+
2. Builds a dependency graph from PR base branches
47+
3. Generates a markdown table
48+
4. Updates each PR description (idempotent)
49+
50+
The annotation is idempotent - running it multiple times updates the existing table rather than adding duplicates.
51+
52+
## When to use
53+
54+
- After creating all PRs in a stack
55+
- After adding or removing PRs from a stack
56+
- After PR status changes (to update badges)
57+
58+
## See also
59+
60+
- [log](log.md) - Visualize the stack
61+
- [land](land.md) - Merge the stack

‎docs/autorebase.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# gh-stack autorebase
2+
3+
Rebuild and push an entire stack after local changes.
4+
5+
## Usage
6+
7+
```bash
8+
gh-stack autorebase 'STACK-ID' -C /path/to/repo
9+
gh-stack autorebase 'STACK-ID' -C /path/to/repo --ci # skip confirmation
10+
gh-stack autorebase 'STACK-ID' -C /path/to/repo -b <sha> # cherry-pick boundary
11+
```
12+
13+
## How it works
14+
15+
1. Checks out the base branch (e.g., `main`)
16+
2. Cherry-picks commits from each PR in stack order
17+
3. Updates local branches to point at new commits
18+
4. Force-pushes all branches at once
19+
20+
This reconstructs a clean, linear stack from your local changes.
21+
22+
## Flags
23+
24+
| Flag | Description |
25+
|------|-------------|
26+
| `-C`, `--project` | Path to local repository (required) |
27+
| `--ci` | Skip confirmation prompt |
28+
| `-b`, `--initial-cherry-pick-boundary` | Stop initial cherry-pick at this SHA |
29+
| `-o`, `--origin` | Git remote name (default: origin) |
30+
| `-r`, `--repository` | Override repository (owner/repo) |
31+
| `-e`, `--excl` | Exclude PR by number (repeatable) |
32+
33+
## Conflict handling
34+
35+
If a conflict occurs during cherry-picking:
36+
37+
1. The process pauses
38+
2. Resolve conflicts manually
39+
3. Stage resolved files with `git add`
40+
4. Continue with `git cherry-pick --continue`
41+
42+
## Example
43+
44+
After amending a commit in the middle of your stack:
45+
46+
```bash
47+
# Your local history diverged from remote
48+
git checkout feat/part-1
49+
git commit --amend -m "Updated message"
50+
51+
# Rebuild and sync the entire stack
52+
gh-stack autorebase 'STACK-ID' -C .
53+
```
54+
55+
## Warnings
56+
57+
- **Force-pushes** to all branches in the stack
58+
- Back up your work before running
59+
- Collaborators will need to reset their local branches
60+
61+
## When to use
62+
63+
- After amending commits
64+
- After interactive rebase
65+
- After resolving conflicts with upstream
66+
- After reordering commits
67+
68+
## See also
69+
70+
- [log](log.md) - Verify stack structure after rebase
71+
- [rebase](rebase.md) - Generate a rebase script for manual control

‎docs/land.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# gh-stack land
2+
3+
Merge an entire stack by squash-merging the topmost approved PR and closing the rest.
4+
5+
## Usage
6+
7+
```bash
8+
gh-stack land 'STACK-ID'
9+
gh-stack land 'STACK-ID' --dry-run # preview without changes
10+
gh-stack land 'STACK-ID' --count 2 # only land bottom 2 PRs
11+
gh-stack land 'STACK-ID' --no-approval # skip approval check
12+
```
13+
14+
## How it works
15+
16+
1. Orders the stack from base to top
17+
2. Finds the topmost PR that can be merged (approved, not draft)
18+
3. Squash-merges that PR into its base
19+
4. Closes all PRs below it with a comment linking to the merge
20+
21+
This works because each PR contains all commits from PRs below it. Squash-merging the top PR lands all changes at once.
22+
23+
## Flags
24+
25+
| Flag | Description |
26+
|------|-------------|
27+
| `--dry-run` | Preview what would happen without making changes |
28+
| `--count N` | Only land the bottom N PRs in the stack |
29+
| `--no-approval` | Skip the approval requirement check |
30+
| `-r`, `--repository` | Override repository (owner/repo) |
31+
| `-o`, `--origin` | Git remote name (default: origin) |
32+
| `-e`, `--excl` | Exclude PR by number (repeatable) |
33+
34+
## Requirements
35+
36+
- PRs must be approved (unless `--no-approval`)
37+
- Draft PRs block landing
38+
- The PR being merged must pass branch protection rules
39+
40+
## Example
41+
42+
```
43+
Stack before:
44+
#103 [STACK-ID] Part 3 (approved)
45+
#102 [STACK-ID] Part 2 (approved)
46+
#101 [STACK-ID] Part 1 (approved, base: main)
47+
48+
After `gh-stack land 'STACK-ID'`:
49+
#103 squash-merged into main
50+
#102 closed (comment: "Landed via #103")
51+
#101 closed (comment: "Landed via #103")
52+
```
53+
54+
## When to use
55+
56+
- All PRs in the stack are approved
57+
- CI is passing on the top PR
58+
- Ready to merge to main/master
59+
60+
## See also
61+
62+
- [log](log.md) - Check stack status before landing
63+
- [annotate](annotate.md) - Update PR descriptions

‎docs/log.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# gh-stack log
2+
3+
Visualize your stack's structure and status.
4+
5+
## Usage
6+
7+
```bash
8+
gh-stack log 'STACK-ID'
9+
gh-stack log 'STACK-ID' --short # compact list view
10+
gh-stack log 'STACK-ID' --include-closed # show closed/merged PRs
11+
gh-stack log 'STACK-ID' --no-color # disable colors and unicode
12+
gh-stack log 'STACK-ID' -C /path/to/repo # specify repo path
13+
```
14+
15+
## Output
16+
17+
The default tree view shows:
18+
19+
```
20+
◉ feat/part-3 (current)
21+
│ 2 hours ago
22+
│
23+
│ a1b2c3d - Add validation logic
24+
│ f4e5d6c - Update tests
25+
│
26+
◯ feat/part-2
27+
│ 3 hours ago
28+
│
29+
◯ feat/part-1 (draft)
30+
│ 5 hours ago
31+
│
32+
◯ main
33+
```
34+
35+
- `◉` marks the current branch
36+
- `◯` marks other branches
37+
- Commits are shown when run from a git repo
38+
- Timestamps show when each PR was last updated
39+
- Draft PRs are labeled
40+
41+
The `--short` flag shows a compact list:
42+
43+
```
44+
#103: [STACK-ID] Add validation (Merges into #102)
45+
#102: [STACK-ID] Implement feature (Merges into #101)
46+
#101: [STACK-ID] Initial scaffolding (Base)
47+
```
48+
49+
## Flags
50+
51+
| Flag | Description |
52+
|------|-------------|
53+
| `--short`, `-s` | Compact list format instead of tree |
54+
| `--include-closed` | Show branches with closed/merged PRs |
55+
| `--no-color` | Disable colors and unicode characters |
56+
| `-C`, `--project` | Path to local repository |
57+
| `-r`, `--repository` | Override repository (owner/repo) |
58+
| `-o`, `--origin` | Git remote name (default: origin) |
59+
| `-e`, `--excl` | Exclude PR by number (repeatable) |
60+
61+
## When to use
62+
63+
- Before rebasing to understand stack structure
64+
- To check which PRs are open, merged, or draft
65+
- To see recent commits on each branch
66+
- To verify stack order before landing
67+
68+
## See also
69+
70+
- [annotate](annotate.md) - Add stack tables to PR descriptions
71+
- [land](land.md) - Merge the stack

‎docs/rebase.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# gh-stack rebase
2+
3+
Generate a bash script to manually rebase a stack.
4+
5+
## Usage
6+
7+
```bash
8+
gh-stack rebase 'STACK-ID' > rebase.sh
9+
chmod +x rebase.sh
10+
./rebase.sh
11+
```
12+
13+
## How it works
14+
15+
Outputs a bash script with git commands to:
16+
17+
1. Check out each branch in order
18+
2. Rebase onto the previous branch
19+
3. Handle the stack reconstruction step-by-step
20+
21+
This gives you full control over the rebase process.
22+
23+
## Flags
24+
25+
| Flag | Description |
26+
|------|-------------|
27+
| `-e`, `--excl` | Exclude PR by number (repeatable) |
28+
29+
## When to use
30+
31+
- When `autorebase` doesn't fit your workflow
32+
- When you need to inspect/modify the rebase steps
33+
- For debugging stack issues
34+
- When you want to dry-run before executing
35+
36+
## Warnings
37+
38+
- The generated script may need manual adjustments
39+
- Review the script before executing
40+
- Back up your work first
41+
42+
## See also
43+
44+
- [autorebase](autorebase.md) - Automatic stack rebuilding
45+
- [log](log.md) - Verify stack structure

0 commit comments

Comments
 (0)