Skip to content

Commit d2c1df5

Browse files
committed
docs(README): update README.md
1 parent 5cbd3aa commit d2c1df5

1 file changed

Lines changed: 23 additions & 19 deletions

File tree

README.md

Lines changed: 23 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# gh-stack
22

3-
A GitHub CLI extension for managing stacked pull requests.
3+
A [GitHub CLI][] extension for managing stacked pull requests.
44

55
## What Are Stacked PRs?
66

@@ -21,23 +21,14 @@ The catch? Managing these stacks by hand is tedious. When `main` updates, you ne
2121

2222
**gh-stack automates all of that.**
2323

24-
## Features
25-
26-
- **Local-first** — Stack metadata lives in `.git/config`, not a remote service
27-
- **GitHub-native** — Works with the `gh` CLI you already use
28-
- **Conflict-aware** — Cascade rebases with continue/abort recovery
29-
- **Automatic sync** — Detects merged PRs, retargets orphaned branches, cascades all
30-
3124
## Installation
3225

33-
Requires [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated.
26+
Requires [GitHub CLI][] (`gh`) installed and authenticated.
3427

3528
```bash
3629
gh extension install boneskull/gh-stack
3730
```
3831

39-
That's it. Precompiled binaries are available for macOS, Linux, and Windows.
40-
4132
## Usage
4233

4334
### Initialize a Repository
@@ -56,6 +47,15 @@ gh stack create feature-auth
5647

5748
Creates `feature-auth` branched from your current position and tracks it as a child.
5849

50+
> ![TIP]
51+
>
52+
> `gh stack create` is sugar for this:
53+
>
54+
> ```bash
55+
> git checkout -b feature-auth
56+
> gh stack adopt feature-auth
57+
> ```
58+
5959
### View Your Stack
6060
6161
```bash
@@ -128,7 +128,7 @@ Fetches from origin, fast-forwards trunk, detects merged PRs, cleans up merged b
128128

129129
## How It Works
130130

131-
gh-stack stores metadata in your local `.git/config`:
131+
**gh-stack** stores metadata in your local `.git/config`:
132132

133133
```ini
134134
[stack]
@@ -149,32 +149,32 @@ No remote service required. Your stack relationships stay with your repository.
149149

150150
### vs. Graphite
151151

152-
[Graphite](https://graphite.dev/) is a SaaS product with a polished CLI and web dashboard. It requires an account and stores stack metadata on their servers. gh-stack stores everything locally in `.git/config`—no account, no remote dependency.
152+
[Graphite](https://graphite.dev/) is a SaaS product with a polished CLI and web dashboard. It requires an account and stores stack metadata on their servers. **gh-stack** stores everything locally in `.git/config`—no account, no remote dependency.
153153

154154
### vs. spr
155155

156156
[spr](https://github.com/ejoffe/spr) enforces a strict "one commit = one PR" model. You work on a single branch, and each commit automatically becomes a separate PR. You cannot merge PRs through GitHub's UI—you must use `spr merge`.
157157

158-
gh-stack uses a traditional "one branch = one PR" model. You control what goes into each PR, create PRs when you're ready, and merge through GitHub normally. More flexibility, less automation.
158+
**gh-stack** uses a traditional "one branch = one PR" model. You control what goes into each PR, create PRs when you're ready, and merge through GitHub normally. More flexibility, less automation.
159159

160160
### vs. git-town
161161

162162
[git-town](https://github.com/git-town/git-town) is a general-purpose Git workflow tool that automates branch creation, synchronization, and cleanup across many workflows (Git Flow, GitHub Flow, trunk-based development). Stacked changes are one feature among many.
163163

164-
gh-stack focuses exclusively on stacked PRs. If you want a comprehensive Git workflow tool, use git-town. If you want a lightweight tool just for managing PR stacks on GitHub, use gh-stack.
164+
**gh-stack** focuses exclusively on stacked PRs. If you want a comprehensive Git workflow tool, use git-town. If you want a lightweight tool just for managing PR stacks on GitHub, use **gh-stack**.
165165

166166
### vs. git-branchless
167167

168168
[git-branchless](https://github.com/arxanas/git-branchless) is a powerful suite that enhances Git with undo functionality, interactive commit graph editing, and patch-stack workflows. It's designed for power users and optimized for massive repositories.
169169

170-
gh-stack is narrower in scope: it tracks parent-child relationships between branches and helps you manage the resulting PRs. It doesn't modify how Git works—it just adds stack awareness on top.
170+
**gh-stack** is narrower in scope: it tracks parent-child relationships between branches and helps you manage the resulting PRs. It doesn't modify how Git works—it just adds stack awareness on top.
171171

172172
## Development
173173

174174
To build from source, you'll need Go 1.22+.
175175

176176
```bash
177-
git clone https://github.com/boneskull/gh-stack.git
177+
gh repo clone boneskull/gh-stack
178178
cd gh-stack
179179
make build # Build binary to ./gh-stack
180180
make test # Run tests
@@ -184,8 +184,12 @@ make gh-install # Install as gh extension locally
184184

185185
## Acknowledgements
186186

187-
Inspired by [Graphite](https://graphite.dev/).
187+
- Inspired by [Graphite][].
188188

189189
## License
190190

191-
Copyright © 2026 [Christopher "boneskull" Hiller](https://github.com/boneskull). Licensed under [Apache-2.0](LICENSE).
191+
Copyright © 2026 [Christopher "boneskull" Hiller][boneskull]. Licensed under [Apache-2.0](LICENSE).
192+
193+
[GitHub CLI]: https://cli.github.com/
194+
[boneskull]: https://github.com/boneskull
195+
[graphite]: https://graphite.dev/

0 commit comments

Comments
 (0)