reivilibre
/
git-stack
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update readme to include repo arg (#5) 

This commit adds `-r` and `--repository` documentation to the README.md
This commit is contained in:
Luis H. Ball Jr 2021-11-04 21:41:51 -07:00 committed by GitHub
parent 8fdba69645
commit cd29468114
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 153 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@ -1,4 +1,4 @@
# gh-stack [![Check if compilation works; no tests yet!](https://api.travis-ci.org/timothyandrew/gh-stack.svg?branch=master&status=passed)](https://travis-ci.org/timothyandrew/gh-stack) # gh-stack
I use this tool to help managed stacked pull requests on Github, which are notoriously difficult to manage manually. Here are a few examples: I use this tool to help managed stacked pull requests on Github, which are notoriously difficult to manage manually. Here are a few examples:
@ -26,11 +26,8 @@ It then looks for all PRs containing this containing this identifier and builds
- [Strategy](#strategy) - [Strategy](#strategy)
- [Disclaimer](#disclaimer) - [Disclaimer](#disclaimer)
## Installation ## Installation
Building from source is the only option at the moment:
```bash ```bash
# Install Rust # Install Rust
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
@ -42,6 +39,13 @@ $ export PATH="$HOME/.cargo/bin:$PATH"
$ cargo install gh-stack $ cargo install gh-stack
``` ```
If you cloned this repository, you can build and install from source with:
```bash
$ cd gh-stack
$ cargo install --force --path .
```
## Usage ## Usage
```bash ```bash
@ -61,17 +65,23 @@ SUBCOMMANDS:
log Print a list of all pull requests in a stack to STDOUT log Print a list of all pull requests in a stack to STDOUT
rebase Print a bash script to STDOUT that can rebase/update the stack (with a little help) rebase Print a bash script to STDOUT that can rebase/update the stack (with a little help)
# Print a description of the stack to stdout.
$ gh-stack log 'stack-identifier'
# Same as above, but for a specific repository.
$ gh-stack log 'stack-identifier' -r 'repo-name'
# Idempotently add a markdown table summarizing the stack # Idempotently add a markdown table summarizing the stack
# to the description of each PR in the stack. # to the description of each PR in the stack.
$ gh-stack annotate 'stack-identifier' $ gh-stack annotate 'stack-identifier'
# Same as above, but for a specific repository.
$ gh-stack annotate 'stack-identifier' -r 'repo-name'
# Same as above, but precede the markdown table with the # Same as above, but precede the markdown table with the
# contents of `filename.txt`. # contents of `filename.txt`.
$ gh-stack annotate 'stack-identifier' -p filename.txt $ gh-stack annotate 'stack-identifier' -p filename.txt
# Print a description of the stack to stdout.
$ gh-stack log 'stack-identifier'
# Automatically update the entire stack, both locally and remotely. # Automatically update the entire stack, both locally and remotely.
# WARNING: This operation modifies local branches and force-pushes. # WARNING: This operation modifies local branches and force-pushes.
$ gh-stack autorebase 'stack-identifier' -C /path/to/repo $ gh-stack autorebase 'stack-identifier' -C /path/to/repo
@ -83,9 +93,10 @@ $ gh-stack rebase 'stack-identifier'
### Examples ### Examples
*This is a quick overview of the ways this tool could be used in practice.* _This is a quick overview of the ways this tool could be used in practice._
1. Write some code, create local commits/branches: 1. Write some code, create local commits/branches:
```bash ```bash
$ git checkout -b first $ git checkout -b first
# Write code # Write code
@ -103,6 +114,7 @@ $ gh-stack rebase 'stack-identifier'
``` ```
2. Your Git tree now looks like: 2. Your Git tree now looks like:
```bash ```bash
* 42315c4 U - (third) third * 42315c4 U - (third) third
| |
@ -116,6 +128,7 @@ $ gh-stack rebase 'stack-identifier'
``` ```
3. Push each branch: 3. Push each branch:
```bash ```bash
$ git push origin first:first second:second third:third $ git push origin first:first second:second third:third
* [new branch] first -> first * [new branch] first -> first
@ -124,20 +137,24 @@ $ gh-stack rebase 'stack-identifier'
``` ```
4. Create a PR for each new branch (starting at `first`), and: 4. Create a PR for each new branch (starting at `first`), and:
- Ensure that all the PRs have a common identifier in their title (I'll use `[EXAMPLE-17399]` here). This identifier (currently) is required to be unique across all GitHub repositories accessible to you (including _all_ public repositories).
- Ensure that all the PRs have a common identifier in their title (I'll use `[EXAMPLE-17399]` here). ~This identifier (currently) is required to be unique across all GitHub repositories accessible to you (including _all_ public repositories).~
- It is recommended that you use the `-r` flag to specify the repository you want gh-stack to search for PRs in. Otherwise, gh-stack will search all repositories accessible to you. This can result in matches from multiple repositories that are unrelated to the stack.
- Set the `base` for each PR to the branch preceding it. Here, `first`'s PR is set to merge into `master`, `second`'s PR is set to merge into `first`, and `third`'s PR is set to merge into `second`. - Set the `base` for each PR to the branch preceding it. Here, `first`'s PR is set to merge into `master`, `second`'s PR is set to merge into `first`, and `third`'s PR is set to merge into `second`.
5. Log all PRs in the stack: 5. Log all PRs in the stack:
```bash ```bash
$ gh-stack log 'EXAMPLE-13799' $ gh-stack log 'EXAMPLE-13799' -r 'example_user/example-repo'
#1: [EXAMPLE-13799] PR for branch `first` (Base) #1: [EXAMPLE-13799] PR for branch `first` (Base)
#2: [EXAMPLE-13799] PR for branch `second` (Merges into #1) #2: [EXAMPLE-13799] PR for branch `second` (Merges into #1)
#3: [EXAMPLE-13799] PR for branch `third` (Merges into #2) #3: [EXAMPLE-13799] PR for branch `third` (Merges into #2)
``` ```
6. Annotate all PRs with information about the stack: 6. Annotate all PRs with information about the stack:
```bash ```bash
$ gh-stack annotate 'EXAMPLE-13799' $ gh-stack annotate 'EXAMPLE-13799' -r 'example_user/example-repo'
1: [EXAMPLE-13799] PR for branch `first` 1: [EXAMPLE-13799] PR for branch `first`
2: [EXAMPLE-13799] PR for branch `second` 2: [EXAMPLE-13799] PR for branch `second`
3: [EXAMPLE-13799] PR for branch `third` 3: [EXAMPLE-13799] PR for branch `third`
@ -149,6 +166,7 @@ $ gh-stack rebase 'stack-identifier'
<img src="img/annotate.png" width="700" /> <img src="img/annotate.png" width="700" />
7. Make changes to a branch that rewrites commits in some way (amend, remove a commit, combine commits): 7. Make changes to a branch that rewrites commits in some way (amend, remove a commit, combine commits):
```bash ```bash
$ git checkout first $ git checkout first
# Do some work # Do some work
@ -156,6 +174,7 @@ $ gh-stack rebase 'stack-identifier'
``` ```
History has now diverged, and this will cause conflicts with dependent PRs when `first` is (force-)pushed. History has now diverged, and this will cause conflicts with dependent PRs when `first` is (force-)pushed.
```bash ```bash
* e7cb9c6 U - (HEAD -> first) amended first * e7cb9c6 U - (HEAD -> first) amended first
| |
@ -172,6 +191,7 @@ $ gh-stack rebase 'stack-identifier'
``` ```
8. Use the `autorebase` subcommand to fix this inconsistency (it requires a path to a local checkout of the repository): 8. Use the `autorebase` subcommand to fix this inconsistency (it requires a path to a local checkout of the repository):
```bash ```bash
$ gh-stack autorebase --repo /tmp/test EXAMPLE-13799 $ gh-stack autorebase --repo /tmp/test EXAMPLE-13799
Checking out Commit { id: 803101159653bf4bf92bf098e577abc436458b17, summary: "initial commit" } Checking out Commit { id: 803101159653bf4bf92bf098e577abc436458b17, summary: "initial commit" }
@ -209,6 +229,7 @@ $ gh-stack rebase 'stack-identifier'
``` ```
- This restores local history to a flat list and pushes the tip of each branch up to update the PRs themselves. - This restores local history to a flat list and pushes the tip of each branch up to update the PRs themselves.
```bash ```bash
* a85a193 N - (HEAD, origin/third, third) third * a85a193 N - (HEAD, origin/third, third) third
| |
@ -242,3 +263,11 @@ Use at your own risk (and make sure your git repository is backed up), especiall
- This tool works for my specific use case, but has _not_ been extensively tested. - This tool works for my specific use case, but has _not_ been extensively tested.
- I've been writing Rust for all of 3 weeks at this point. - I've been writing Rust for all of 3 weeks at this point.
- The `autorebase` command is in an experimental state; there are possibly edge cases I haven't considered. - The `autorebase` command is in an experimental state; there are possibly edge cases I haven't considered.
## Contributors
Contributors are encouraged to submit pull requests to improve the tool. Please stick to semantic versioning and don't submit pull requests that break the tool.
## Credits
This README and tool were originally written by [@timothyandrew](https://github.com/timothyandrew/gh-stack). I highly recommend reading his blog post [here](https://0xc0d1.com/blog/git-stack/).