You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a non-comprehensive list of dependencies required by `stack-pr.py`:
20
23
21
24
- Install `gh`, e.g., `brew install gh` on MacOS.
22
25
- Run `gh auth login` with SSH
23
26
24
-
## Installation
27
+
28
+
### Installation with `pipx`
25
29
26
30
To install via [pipx](https://pipx.pypa.io/stable/) run:
27
31
28
32
```bash
29
33
pipx install stack-pr
30
34
```
31
35
36
+
### Manual installation from source
37
+
32
38
Manually, you can clone the repository and run the following command:
33
39
34
40
```bash
35
41
pipx install .
36
42
```
37
43
38
-
## Workflow
44
+
## Usage
45
+
46
+
`stack-pr` allows you to work with stacked PRs: submit, view, and land them.
47
+
48
+
### Basic Workflow
49
+
50
+
The most common workflow is simple:
51
+
52
+
1. Create a feature branch from `main`:
53
+
```bash
54
+
git checkout main
55
+
git pull
56
+
git checkout -b my-feature
57
+
```
58
+
59
+
2. Make your changes and create multiple commits (one commit per PR you want to create)
60
+
```bash
61
+
# Make some changes
62
+
git commit -m "First change"
63
+
# Make more changes
64
+
git commit -m "Second change"
65
+
# And so on...
66
+
```
67
+
68
+
3. Review what will be in your stack:
69
+
```bash
70
+
stack-pr view # Always safe to run, helps catch issues early
71
+
```
72
+
73
+
4. Create/update the stack of PRs:
74
+
```bash
75
+
stack-pr submit
76
+
```
77
+
> **Note**: `export` is an alias for `submit`.
39
78
40
-
`stack-pr` is a tool allowing you to work with stacked PRs: submit,
41
-
view, and land them.
79
+
5. To update any PR in the stack:
80
+
- Amend the corresponding commit
81
+
- Run `stack-pr view` to verify your changes
82
+
- Run `stack-pr submit` again
42
83
43
-
The `stack-pr` tool has four commands:
84
+
6. To rebase your stack on the latest main:
85
+
```bash
86
+
git checkout my-feature
87
+
git pull origin main # Get the latest main
88
+
git rebase main # Rebase your commits on top of main
89
+
stack-pr submit # Resubmit to update all PRs
90
+
```
91
+
92
+
7. When your PRs are ready to merge, you have two options:
93
+
94
+
**Option A**: Using `stack-pr land`:
95
+
```bash
96
+
stack-pr land
97
+
```
98
+
This will:
99
+
- Merge the bottom-most PR in your stack
100
+
- Automatically rebase your remaining PRs
101
+
- You can run `stack-pr land` again to merge the next PR once CI passes
102
+
103
+
**Option B**: Using GitHub web interface:
104
+
1. Merge the bottom-most PR through GitHub UI
105
+
2. After the merge, on your local machine:
106
+
```bash
107
+
git checkout my-feature
108
+
git pull origin main # Get the merged changes
109
+
stack-pr submit # Resubmit the stack to rebase remaining PRs
110
+
```
111
+
3. Repeat for each PR in the stack
112
+
113
+
That's it!
114
+
115
+
> **Pro-tip**: Run `stack-pr view` frequently - it's a safe command that helps you understand the current state of your stack and catch any potential issues early.
116
+
117
+
### Commands
118
+
119
+
`stack-pr` has four main commands:
44
120
45
121
-`submit` (or `export`) - create a new stack of PRs from the given set of
46
122
commits. One can think of this as “push my local changes to the corresponding
@@ -52,9 +128,8 @@ The `stack-pr` tool has four commands:
52
128
-`abandon` - remove all stack metadata from the given set of commits. Apart
53
129
from removing the metadata from the affected commits, this command deletes
54
130
the corresponding local and remote branches and closes the PRs.
55
-
-`land` - merge PRs from the stack corresponding to the given set of commits.
56
-
This command attempts to merge PRs from the stack one by one, and if
57
-
succeeded deletes the corresponding branches from local and remote repos.
131
+
-`land` - merge the bottom-most PR in the current stack and rebase the rest of
132
+
the stack on the latest main.
58
133
59
134
A usual workflow is the following:
60
135
@@ -70,7 +145,8 @@ You can also use `view` at any point to examine the current state, and
70
145
`abandon` to drop the stack.
71
146
72
147
Under the hood the tool creates and maintains branches named
73
-
`$USERNAME/stack/$BRANCH_NUM` and embeds stack metadata into commit messages,
148
+
`$USERNAME/stack/$BRANCH_NUM` (the name pattern can be customized via
149
+
`--branch-name-template` option) and embeds stack metadata into commit messages,
74
150
but you are not supposed to work with those branches or edit that metadata
75
151
manually. I.e. instead of pushing to these branches you should use `submit`,
76
152
instead of deleting them you should use `abandon` and instead of merging them
@@ -88,7 +164,7 @@ and `-T` respectively and accept the standard git notation: e.g. one can use
88
164
The first step before creating a stack of PRs is to double-check the changes
89
165
we’re going to post.
90
166
91
-
By default the tool will look at commits in`main..HEAD` range and will create
167
+
By default `stack-pr` will look at commits in`main..HEAD` range and will create
92
168
a PR forevery commitin that range.
93
169
94
170
For instance, if we have
@@ -172,6 +248,11 @@ If we need to make changes to any of the PRs (e.g. to address the review
172
248
feedback), we simply amend the desired changes to the appropriate git commits
173
249
and run `submit` again. If needed, we can rearrange commits or add new ones.
174
250
251
+
`submit` simply syncs the local changes with the corresponding PRs. This is why
252
+
we use the same `stack-pr submit`command when we create a new stack, rebase our
253
+
changes on the latest main, update any PR in the stack, add new commits to the
254
+
stack, or rearrange commits in the stack.
255
+
175
256
When we are ready to merge our changes, we use `land` command.
176
257
177
258
```python
@@ -204,7 +285,7 @@ VIEW
204
285
205
286
This way we can land all the PRs from the stack one by one.
206
287
207
-
## Specifying custom commit ranges
288
+
### Specifying custom commit ranges
208
289
209
290
The example above used the default commit range - `main..HEAD`, but you can
210
291
specify a custom range too. Below are several commonly useful invocations of
0 commit comments