Prerequisites
To create and submit pull requests for a stack of branches in the CLI, make sure you've:
Initialized
gtin a repo of your choiceCreated or tracked a branch/stack of branches
Create pull requests for branches in a stack
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│
Graphite's gt submit command allows you to submit all of the PRs in your stack at once, rather than one by one. By default it submits the current branch, and any of its ancestors (downstack branches) that need to be submitted.
To submit descendants (upstack branches as well), you can use gt submit --stack:
> gt submit# OR> gt s🥞 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)
No matter the type of submit command you use, you'll see interactive prompts to help you create pull requests for each branch.
Title
For the initial state of the PR title, Graphite will default to using the title of the first commit on the branch, but you're free to change it.
▸ 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 uses your git editor.
For the initial state of the PR body, Graphite uses this logic:
If you have a pull request template saved locally for GitHub, Graphite automatically detects it and adds 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 config. 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. You can read more about using the CLI to customize your PR submissions on the configuration page.
? Body › - Use arrow-keys. Return to submit.❯ Edit Body (using vi)Skip (paste template)
Reviewers
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 repository, just like if you created the PR on GitHub.
▸ pp--06-14-part_1 (Create)✔ Title … part 1✔ Body › Edit body (using vi)? Submit › - Use arrow-keys. Return to submit.❯ Publish Pull RequestCreate Draft Pull Request
Draft PRs
Your last option is 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 default to draft, and existing PRs remain in the same state.
Tip
Use gt ss -np for simpler changes, writing PR descriptions on the web app, or just to maximize velocity. This is the short form of gt submit --stack --no-edit --publish.
Once you've created pull requests from your stack, Graphite displays the links to view them on the Graphite app:
📨 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
If you need to cancel your submission or it fails for any reason, your PR titles and bodies are not lost. We cache them locally for when you run submit again.
Use a PR template for submissions
The Graphite CLI automatically includes any PR templates that might be present in the repository. The logic mimics GitHub's for the most part, meaning all PR templates must be located in:
The top-level of the repository
A
.github/directoryA
.docs/directory
GitHub allows you to define a single default PR template by naming it pull_request_template (case-insensitive) with either a .md or .txt file extension. If one of these is provided, GitHub autofills the body field on the PR creation page—unless it is overridden with a template query param.
If you have multiple PR templates, you can put them in a PULL_REQUEST_TEMPLATE directory in one of the PR locations above. However, at PR creation time, GitHub doesn't autofill the body field on the PR creation page unless you tell it which template to use through a URL query param.
On the Graphite side, if the submit command finds multiple PR templates, it will prompt you to select one.
Use submit to update PRs in a stack
gt 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 submit --publish to set your PRs to the "ready for review" state. Similarly, you can run a submit command to update already open PRs after you've made new changes.
> gt 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)
Tip
To only update existing PRs and skip creating new ones, you can use gt submit --update-only or gt s -u.
