Revue
DocumentationOpening a pull request

Opening a pull request

Open a pull request from any branch, with its title, description, ticket and reviewers filled in for you, and optionally announce it in Slack.

Where to start#

The form opens as the New pull request page, in a tab of its own named after the branch: one per branch, so you can have several open. Opening a branch's page again shows its tab. Cancel closes the tab and goes back to the repository you opened it from, if there is one, else to the nearest tab. You get there from a repository's tab (see Repositories and branches) or from your editor:

  • Branches tab, on a branch's row: the Open pull request icon.

  • Above a branch's diff: the Open pull request button, next to History.

  • Your local clone's branch: when your clone is checked out on a branch without a pull request, the top of the Branches tab says "Your checkout is on …" with Open pull request, or Push and open pull request when the branch isn't on the server yet.

  • From your editor: Revue: Open Pull Request in JetBrains IDEs, or revue --pull-request in a terminal, for the branch you're on. If it has an open pull request, that opens instead. See Editors: JetBrains IDEs.

The button only appears for branches that can have one: not the default branch, and not a branch that already has an open pull request (that one shows its number instead).

The form#

The page opens with everything guessed from the branch. Check it, change what you like, and press Open pull request (or Ctrl+Enter, Cmd+Enter on macOS).

Branch and base#

The top line reads your branch → base, with the size of the change (files, lines added and removed). The base starts on the repository's default branch. Click it to pick another: the default comes first, then branches of open pull requests and usual names (main, develop, release/…), then the rest. Type to narrow, use the arrow keys and Enter to pick.

Title#

Taken from the branch's last commit, or from the branch's name turned into words (feature/ABC-123-document-types becomes "Document types"). When the branch names a ticket, its key leads the title ("ABC-123 Document types"). A long title wraps, so you always see all of it. It stays one line: Enter doesn't break it, and a pasted line break becomes a space.

Ticket (optional)#

The ticket the branch is for: found in the last commit's message or in the branch name, and shown as a chip with its Jira summary and status. Click the chip to change it, or the cross for No ticket.

Without a ticket, the field searches Jira as you type (Search Jira, or type a key (ABC-123)). Empty, it lists Your open tickets. A key typed in full is offered as is (Use ABC-123 as typed), even without Jira.

The ticket is used for the title at the start and for the Slack announcement; the pull request itself gets it through the title.

Advanced: how the ticket is found
  • A key in the last commit's subject wins, then a key written in capitals in the branch name (dana/ABC-1007).
  • A lowercase key in the branch name (abc-12-fix) counts only when its project is known: a project of a connected Jira site, or one of the repository's ticket link rules.
  • Every connected Jira account is searched, up to 12 tickets each; with several sites, each ticket says which site it's from.
  • Without a Jira account, the dropdown says No Jira account: connect one in Settings → Accounts to search tickets.
  • The ticket's address comes from the repository's ticket link rules (and the connected Jira sites). When no rule covers the key, the chip says so.

Description#

Markdown, in the same editor as comments (see Comments, threads and drafts). It starts from the branch's commits: one commit's message body, or a list of the commits' subjects, oldest first. Once you edit it, Revue stops refilling it.

If the repository has a pull request template, Use the repository's template replaces the description with it.

Advanced: where templates are looked for

Revue reads the template from the base branch the form opened with, and offers the first one found:

ServicePaths, in order
GitHub.github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE.md, pull_request_template.md, docs/pull_request_template.md
Forgejo, Codeberg, Gitea.forgejo/pull_request_template.md, .forgejo/PULL_REQUEST_TEMPLATE.md, .gitea/pull_request_template.md, .gitea/PULL_REQUEST_TEMPLATE.md, .github/pull_request_template.md
Bitbucket CloudPULL_REQUEST_TEMPLATE.md, .bitbucket/PULL_REQUEST_TEMPLATE.md, .github/pull_request_template.md

An empty template file is skipped. Each line you type stays its own line on every service. With Slack connected, #channel names in the description become links to the channel.

Commits#

Under the description, the commits the pull request puts up for review: the branch's commits the base doesn't have, newest first, with their short hash, subject and age. They follow the base when you change it. Right-click one to copy its message or hash, or open it in the browser.

Stacking on another pull request#

When the base is the branch of another open pull request, the new one sits on top of it: Revue shows the two as a stack (see Stacked pull requests). A box then offers Start a pull request stack: "This pull request will be stacked with #5 …". Checked, the description ends with a "Stacked on #5" line, so readers on the web see it too.

If your branch was built on top of another open pull request's branch, the form notices and starts on that base with the box checked. Picking a base by hand overrides this.

Reviewers (optional)#

Add reviewer lists the people who can review in the repository, with their names (and logins); type part of either to find someone. Each reviewer becomes a chip; click it to remove them.

Per service: who can be picked
  • GitHub: the repository's collaborators (listing them needs push access), else the people it can be assigned to.
  • Forgejo, Codeberg, Gitea: the people the repository can be assigned to (collaborators and team members).
  • Bitbucket Cloud: the workspace's members.

You aren't listed yourself. If asking for reviews fails after the pull request is open, a warning says so; the pull request stays open.

Draft or ready#

The Open pull request button has a menu on its right: pick Open draft pull request to open it as a draft (not ready for review yet), or Open pull request to go back.

On Forgejo, Codeberg and Gitea, drafts are marked by the title: Revue adds WIP: in front of it.

Announce in Slack (optional)#

With Slack connected, the form can post the new pull request in a channel, as you. It starts on the channel saved for this repository (or the account's, the service's, the global default, or the one last used here) and says when a saved channel is gone. Pick another channel or Don't post in Slack.

The form shows What's posted: the message in the channel and, if set up, the reply in its thread. Reviewers are tagged; if Revue can't tell who a reviewer is on Slack, it asks (Who is … on Slack?), and No mention writes their name in plain text instead. If posting fails, the pull request is still open, and a notice offers Retry.

The wording and default channels are set in Settings → Slack messages. See Slack.

What happens when you open it#

  1. If the branch is only in your local clone, or your clone has commits the server doesn't, Revue pushes it first. The form says so beforehand and shows the exact command.
  2. Revue opens the pull request on the service and asks for the reviewers.
  3. It posts to Slack, if a channel is picked.
  4. The new pull request opens in its own tab, and the branch's row now links to it.
Advanced: what git does
  • Revue looks at the clone set for the repository (see Clones, worktrees and opening in your tools) and the branch checked out in it. A detached checkout is ignored.
  • A branch the server doesn't have is pushed with git push -u <remote> <branch>, so it tracks the remote.
  • A branch the clone is ahead on is pushed with a plain git push <remote> <branch>.
  • If the clone's branch is behind the server's, has diverged from it, or the server has commits the clone hasn't fetched, Revue doesn't push and says why (pull or fetch first).
  • git runs without asking for passwords. If the push fails, the form shows The push failed: with the command and git's output, and nothing is opened.
  • The description of a local branch comes from its commits not yet on the base (up to 50).
  • On Bitbucket, the branch isn't set to close on merge.

Guide: Open a pull request from a branch#

  1. Press Ctrl+G (Cmd+G on macOS) and open the repository.
  2. Press 3 for Branches.
  3. Find your branch and click its Open pull request icon.
  4. Check the base branch at the top; click it to pick another.
  5. Check the title and ticket.
  6. Edit the description, or click Use the repository's template.
  7. Click Add reviewer and pick the people to ask.
  8. Optionally pick a Slack channel and check the preview.
  9. To open it as a draft, pick Open draft pull request from the button's menu.
  10. Click Open pull request.

Guide: Push a local branch and open its pull request#

  1. Set your local clone for the repository (see Clones, worktrees and opening in your tools).
  2. Check out your branch in the clone and commit your work.
  3. Open the repository in Revue and press 3 for Branches.
  4. Click Push and open pull request at the top of the list.
  5. Fill in the form and click Push and open pull request.