Creating and submitting pull requests

Once you're finished building, Graphite makes it easy to create pull requests from the branches in your stack.

Again, let's say we're working with this stack:

> gt log

◉ pp--06-14-part_3 (current)
│ 8 seconds ago
│
│ 95338df - part 3
│
◯ pp--06-14-part_2
│ 8 seconds ago
│
│ 95610c6 - part 2
│
◯ pp--06-14-part_1
│ 27 seconds ago
│
│ 48cd85e - part 1
│
◯ main 
│ 5 weeks ago
│

Let's submit the entire stack of 3 branches to GitHub with Graphite:

> gt stack submit

🥞 Validating that this Graphite stack is ready to submit...

📝 Preparing to submit PRs for the following branches...
▸ pp--06-14-part_1 (Create)
▸ pp--06-14-part_2 (Create)
▸ pp--06-14-part_3 (Create)

gt stack submit gives you interactive prompts to help you create pull requests for each branch:

Title
For the initial state of the PR title, Graphite will use the title of the first commit on the branch.

▸ pp--06-14-part_1 (Create)
? Title > part 1

Body
You can configure which text editor to use with Graphite for the PR body by running the command gt user editor --set (i.e. gt user editor --set vim). By default, Graphite will use your git editor.

For the initial state of the PR body, Graphite will follow the below logic:

If you have a pull request template saved locally for GitHub, Graphite will automatically detect it and add it to the PR for you to fill out.

You can also configure Graphite to include your commit message(s) in your PR body with gt user submit-body --include-commit-messages. If you have only one commit in the PR, this will not include the title of the commit (first line of message), as this is already the default title. If you have multiple commits, all of their messages will be included.

? Body › - Use arrow-keys. Return to submit.
❯   Edit Body (using vi)
    Skip (paste template)

Reviewers

You can optionally pass --reviewers or -r to manually specify reviewers for the new pull requests. By default, Graphite will just assign any reviewers specified by CODEOWNERS files in your repo.

▸ pp--06-14-part_1 (Create)
✔ Title … part 1
✔ Body › Edit body (using vi)
? Submit › - Use arrow-keys. Return to submit.
❯   Publish Pull Request
    Create Draft Pull Request

Draft state
Your last option will be whether to submit your PRs as draft or published (ready for review). You can also pass --draft or --publish to specify this for all PRs in the submit without having to select each time. In --no-interactive mode, new PRs will default to draft, and existing PRs will remain in the same state.

Tip

A common pattern for simpler changes, writing PR descriptions on the web app, or just to maximize velocity is gt ss -np which is the short form of gt stack submit --no-edit --publish.

Once you've created pull requests from your stack, Graphite will display the links to view them on the Graphite web dashboard:

📨 Pushing to remote and creating/updating PRs...
pp--06-14-part_1: https://app.graphite.dev/github/pr/withgraphite/pranathi-test-repo/100 (created)
pp--06-14-part_2: https://app.graphite.dev/github/pr/withgraphite/pranathi-test-repo/101 (created)
pp--06-14-part_3: https://app.graphite.dev/github/pr/withgraphite/pranathi-test-repo/102 (created)

Note

Note that if you need to cancel your submission or it fails for any reason, your PR titles and bodies won't be lost! We cache them locally so they'll be there for when you run submit again.

gt stack submit is also the command for updating your PRs after making changes to your stack! For example, you might open your PRs initially in draft mode, and then later run gt stack submit --publish to change all PRs in your stack to "ready for review."

> gt stack submit

🥞 Validating that this Graphite stack is ready to submit...

📝 Preparing to submit PRs for the following branches...
▸ pp--06-14-part_1 (Update)
▸ pp--06-14-part_2 (Update)
▸ pp--06-14-part_3 (Update)

📨 Pushing to remote and creating/updating PRs...
pp--06-14-part_1: https://app.graphite.dev/github/pr/withgraphite/pranathi-test-repo/100 (updated)
pp--06-14-part_2: https://app.graphite.dev/github/pr/withgraphite/pranathi-test-repo/101 (updated)
pp--06-14-part_3: https://app.graphite.dev/github/pr/withgraphite/pranathi-test-repo/102 (updated)

submit commands are available in all four scopes: branch submit only submits the current branch), stack submit (submits the current branch and all ancestors and descendants), upstack submit (submits the current branch and all descendants), and downstack submit (submits the current branch and all ancestors).

Now that you can create pull requests from your stack, you may be wondering how to sync your local repo with remote so that you can clear out merged branches and keep your stacks based on the latest version of trunk. See syncing with a remote repository.