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

This commit adds `-r` and `--repository` documentation to the README.md

README.md

@@ -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:
 
@@ -26,11 +26,8 @@ It then looks for all PRs containing this containing this identifier and builds
 - [Strategy](#strategy)
 - [Disclaimer](#disclaimer)
 
-
 ## Installation
 
-Building from source is the only option at the moment:
-
 ```bash
 # Install Rust
 $ 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
 ```
 
+If you cloned this repository, you can build and install from source with:
+
+```bash
+$ cd gh-stack
+$ cargo install --force --path .
+```
+
 ## Usage
 
 ```bash
@@ -61,17 +65,23 @@ SUBCOMMANDS:
     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)
 
+# 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
 # to the description of each PR in the stack.
 $ 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
 # contents of `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.
 # WARNING: This operation modifies local branches and force-pushes.
 $ gh-stack autorebase 'stack-identifier' -C /path/to/repo
@@ -83,9 +93,10 @@ $ gh-stack rebase 'stack-identifier'
 
 ### 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:
+
    ```bash
    $ git checkout -b first
    # Write code
@@ -103,6 +114,7 @@ $ gh-stack rebase 'stack-identifier'
    ```
 
 2. Your Git tree now looks like:
+
    ```bash
    * 42315c4 U - (third) third
    |
@@ -116,6 +128,7 @@ $ gh-stack rebase 'stack-identifier'
    ```
 
 3. Push each branch:
+
    ```bash
    $ git push origin first:first second:second third:third
      * [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:
-    - 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`.
 
 5. Log all PRs in the stack:
+
    ```bash
-    $ gh-stack log 'EXAMPLE-13799'
+   $ gh-stack log 'EXAMPLE-13799' -r 'example_user/example-repo'
     #1: [EXAMPLE-13799] PR for branch `first` (Base)
     #2: [EXAMPLE-13799] PR for branch `second` (Merges into #1)
     #3: [EXAMPLE-13799] PR for branch `third` (Merges into #2)
    ```
 
 6. Annotate all PRs with information about the stack:
+
    ```bash
-    $ gh-stack annotate 'EXAMPLE-13799'
+   $ gh-stack annotate 'EXAMPLE-13799' -r 'example_user/example-repo'
     1: [EXAMPLE-13799] PR for branch `first`
     2: [EXAMPLE-13799] PR for branch `second`
     3: [EXAMPLE-13799] PR for branch `third`
@@ -149,6 +166,7 @@ $ gh-stack rebase 'stack-identifier'
    <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):
+
    ```bash
    $ git checkout first
    # 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.
+
    ```bash
    * 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):
+
    ```bash
    $ gh-stack autorebase --repo /tmp/test EXAMPLE-13799
    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.
+
      ```bash
      * 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.
 - 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.
+
+## 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/).