Pull Requests

• 1: All Pull Requests
• 2: Incoming PRs
• 3: View PR Details
• 4: Filter PRs
• 5: Pull Request Dashboards
• 5.1: Tagged PRs
• 5.2: Solo PRs
• 5.3: Ignored PRs
• 5.4: Inactive PRs
• 5.5: Archived PRs

1 - All Pull Requests

PR Focus provides an All Pull Requests dashboard where you can see an aggregate view of all of the important pull requests across all of the repositories you’re watching. This is the main dashboard in the app, and it’s the view that loads when you open the app.

Not every PR in PR Focus appears in the All Pull Requests dashboard. Pull requests that you don’t need to actively pay attention to move to secondary dashboards to get them out of the way. PR Focus moves these pull requests automatically:

• Inactive PRs: When a PR hasn’t had activity for a while, PR Focus marks it as “inactive” and moves it to the Inactive PRs dashboard. If it gets an update, PR Focus moves it back to the active dashboards. You can configure the interval to wait to set a PR as inactive on a global basis, or on a per-repository basis. For more information, refer to Settings or Repository Settings.
• Ignored PRs: When you ignore a pull request, it moves to the Ignored PRs dashboard. You can un-ignore it at any time, or change your mind and start watching it. PRs where you are an assignee or a reviewer automatically appear in your active dashboards, even if you ignore them.
• Archived PRs: When a pull request is closed, it eventually moves to the Archived PRs dashboard. Once a PR becomes archived, you can delete it from PR Focus. You can configure the interval to wait to set a PR as archived on a global basis, or on a per-repository basis. For more information, refer to Settings or Repository Settings.

Any pull request that isn’t inactive, ignored, or archived appears in the All Pull Requests view.

Anatomy of the PR Focus Dashboard

The All Pull Requests and Repository dashboards break down into different lists of pull requests. By default, you see:

• Inbox: a list of Incoming PRs
• Watched PRs: a list of PRs you’ve chosen to watch
• My PRs: a list of your PRs
• Reviewing PRs: a list of PRs where you’re a reviewer

Optionally, if your workflow involves assigning PRs, you can check the setting in the Settings or the Repository Settings to Show Assigned PRs. This adds a fifth list of PRs that are assigned to you.

PR Summary

A summary view gives you information about each PR in the dashboard, including:

• The PR’s title
• The PR number
• The repository where the PR exists
• Whether a PR has merge conflicts
• Whether a PR is open, closed, or merged
• Whether there are any checks for the PR, and if those checks have passed or failed
• The number of commits in the PR
• The number of comments on the PR
• The number of reviews the PR has gotten

You can click into a PR summary to see the full details of the pull request.

The background color of the PR summary changes when the PR has new updates since you last viewed the details. Additionally, when there are updates since you’ve last viewed the details, PR Focus bolds the relevant column that has updates - Checks, Commits, Comments, or Reviews. PR Focus uses your macOS settings for Light or Dark mode.

In Light mode, a PR summary with a bright white background has updates you haven’t seen. One that is gray does not have any new updates since you last viewed it.

In Dark mode, a PR summary with a dark black background has updates you haven’t seen. One that is grey does not have any new updates since you last viewed it.

If you’re viewing a repository where you are showing all three columns - “My PRs”, “Assigned PRs”, and “Reviewing PRs”, you see a condensed PR Summary designed to prevent the column names from overflowing.

PR Summary Context Menu

You can right-click on a PR summary to open a context menu. This menu lets you quickly perform common actions without clicking into the pull request details.

The available options change depending on the context in which you open the menu. For example, if a PR is closed or merged, one of the options in the context menu is “Archive PR.” If the pull request is open, this option is not available.

If you have created tags to apply your own categorization to pull requests, you’ll see an “Apply Tags” option in the context menu. Tagged PRs get a tag icon in the summary to indicate they have a tag. You can view them in any of the relevant default dashboards, or get a focused view of them by applying filters in the Tagged PRs dashboard. If you have applied tags to a PR, you’ll see a “Remove Tags” option in the context menu.

You can always select “Open in GitHub” to immediately interact with the PR on GitHub. Or you can click into the pull request details to view the details without leaving PR Focus.

Conflicts

A PR’s “Conflicts” icon can indicate one of three states:

• A green check: A PR has no merge conflicts.
• A gray check: GitHub hasn’t finished calculating whether a PR has merge conflicts.
• A red X: A PR has merge conflicts.

Status

A PR’s “Status” can be one of four states:

• Draft: Indicated by a grey pull request draft icon:
• Open: Indicated by a green pull request icon:
• Merged: Indicated by a purple merged icon:
• Closed without merging: Indicated by a red pull request closed icon:

Checks

A PR’s “Checks” include jobs that run on a PR before merging, such as linters, test suites, or other CI jobs. The status of these jobs is indicated as one of three states in the PR summary:

• A green check: A PR has at least one check, and it has passed all checks.
• A red X: A PR has at least one check, and it has failed at least one check.
• An “N/A”: A PR has no checks, or the status of checks is unknown.

When you click into a PR’s details, you can see the status of individual checks.

Inbox

When a new PR is opened in a repository you’re watching, PR Focus checks for a few things:

• Are you the PR author? If so, the PR goes to My PRs.
• Are you an assignee? If so, the PR goes to Assigned PRs
• Are you a reviewer or requested reiewer? If so, the PR goes to Reviewing PRs

If none of those things applies, the pull request appears in the Inbox. From here, you can view the PR’s details and decide whether to Watch or Ignore a PR. If the PR is closed, you can Archive it. If you later become a reviewer or an assignee, the PR moves to one of those columns whether or not you Watch or Ignore it.

The aggregate Inbox gives you the option to perform bulk operations. You can select multiple PRs and Watch or Ignore them. If you select multiple closed PRs, you can Archive them.

For more information about processing incoming PRs, refer to Incoming PRs.

Watched PRs

When you choose to Watch an incoming PR, it moves into the Watched PRs list for the repository and in the All Pull Requests rollup view. If you watch an individual pull request without watching the repository, it automatically moves into your Watched PRs list.

Choosing to Watch a PR does not move the pull request out of the My PRs, Assigned PRs or Reviewing PRs columns.

Stop Watching

You can stop watching a PR at any time by either:

• Clicking into the PR Details and pressing the Stop Watching button.
• Right-clicking on the PR Summary and selecting Stop Watching from the context menu.

You can also choose to Ignore a pull request that you’re currently watching. If you select this option, PR Focus stops watching the PR and moves it to the Ignored PRs dashboard.

In a Watched Repository

If the PR is still open, it goes back to your Inbox. If the PR is no longer open, it disappears until it eventually becomes archived at the interval you’ve configured. Once it is archived, it appears in the Archived PRs dashboard.

You might stop watching a PR if you’re undecided if you need to pay attention to it. You might choose this option instead of going directly to Ignore if you want to see upcoming changes to a PR before deciding how to react to it.

When it’s a solo PR

If you have added a pull request that isn’t part of a repository you’re watching, it automatically goes into your Watched PRs list. PR Focus assumes that when you Stop Watching one of these pull requests, you no longer care about it, and PR Focus deletes it. This is the only scenario where PR Focus makes it possible to delete a pull request that isn’t closed.

My PRs

When the GitHub user who created the PR is the same as the GitHub user whose API token is used in PR Focus, the app considers you the PR author and automatically moves the PR into My PRs. PR Focus does not provide a way to manually designate a PR as “mine.”

Choosing to Watch or Ignore a PR does not move the pull request out of the My PRs column. The only way to move a pull request you’ve made is waiting for it to become inactive and automatically move to the Inactive PRs dashboard, or waiting for it to close and automatically or manually move to the Archived PRs dashboard.

Reviewing PRs

When the GitHub user whose API token is used in PR Focus is the same as a GitHub user in the requestedReviewers array in the GitHub Pull Request API, PR Focus moves the PR into the Reviewing PRs list.

When you review a PR, GitHub automatically adds you to the requestedReviewers array. Someone else, such as the PR author, can also add you as a requestedReviewer by requesting a review from you.

If you do not use this workflow, you can hide the Reviewing PRs list from your dashboards by un-checking the Show Reviewing PRs checkbox in the global app Settings or Repository Settings.

Reviewing PRs is enabled by default.

Note: PR Focus does not have support for requestedTeams because it does not have information about teams. If your organization uses requested teams, PR Focus will not add the PR to your Reviewing PRs list until you actually review the PR. If this is a feature that is important to you, please file a feature request or leave a comment or an emoji reaction if this feature request already exists.

Assigned PRs

When the GitHub user whose API token is used in PR Focus is the same as a GitHub user in the assignee field or the assignees array in the GitHub Pull Request API, PR Focus moves the PR into the Assigned PRs list.

If you do not use this workflow, you can hide the Assigned PRs list from your dashboards by un-checking the Show Assigned PRs checkbox in the global app Settings or Repository Settings.

Assigned PRs is disabled by default.

Note: PR Focus does not have support for requestedTeams because it does not have information about teams. If your organization uses requested teams, PR Focus will not add the PR to your Assigned PRs list. If this is a feature that is important to you, please file a feature request or leave a comment or an emoji reaction if this feature request already exists.

Sort PRs in Lists

You can sort pull request lists in the All Pull Requests or repository dashboards by a number of options. By default, all lists in these dashboards are sorted by updated date. Recently updated PRs always appear at the top of the lists.

You can change the sort order of Watched PRs, Assigned PRs, Reviewing PRs, or My PRs with one of these sort options:

• Review count: Sort in descending order by the number of reviews
• Comment count: Sort in descending order by the number of comments
• Commit count: Sort in descending order by the number of commits
• State: Group PRs together by state; Closed, Open, or Merged
• Broken: Show PRs with failing status checks and/or merge conflicts at the top of the list
• Updated date: Sort in descending order by updated date
• Closed date: Sort in descending order by closed date. Only closed PRs have a closed date.
• Merged date: Sort in descending order by merged date. Only merged PRs have a merged date.

You can individually change the sort order for each column. PR Focus does not preserve the sort order you select and always defaults to showing PRs in descending order by updated date.

PR Movement Between Lists and Dashboards

Pull requests may move automatically between lists and dashboards depending on things like whether you are a reviewer or assignee, or whether the PR has been inactive or closed for a period of time. You can manually change the status of PRs by watching or ignoring them, or by archiving a PR that is closed or merged.

Manually Move PRs Between Lists and Dashboards

When you Watch or Ignore a PR in your Inbox, the PR moves to the Watched PRs list or the Ignored PRs dashboard.

You can manually change the status of a watched or ignored PR at any point by either:

• Clicking into the PR Details and pressing the appropriate button.
• Right-clicking on a PR Summary and selecting the appropriate option from the context menu.

You can also manually select the Archive PR option on a closed or merged PR to immediately move it to the Archived PRs dashboard.

Automatic Movement Between Lists and Dashboards

PRs may also move between lists automatically in the Repository Dashboard and Inactive/Archived dashboards when:

• You become a reviewer or an assignee on a pull request. When this occurs, the PR moves into one of those respective columns.
• A PR has been inactive for longer than the Days until inactive setting. When this occurs, the PR moves into the Inactive PRs dashboard.
• A PR has been closed or merged for longer than the Days until archive setting. When this occurs, the PR moves into the Archived PRs dashboard.

You can customize these settings on a per-repository basis, or by changing the app Settings from their default values. For more information, refer to:

• Customize Repository Settings
• Customize App Settings

View PR Details

At any time, you can click into a PR Summary in a list or dashboard to view the PR details. When you are viewing the PR details, you can press the buttons to Watch, Ignore, or Archive a PR. For more information, refer to View PR Details.

Fetch New and Updated PRs in the Repository

While PR Focus is open, it automatically fetches and updates PRs in the repositories. You can configure the interval at which PR Focus fetches and updates PRs in two ways:

• Customize the global default fetch interval from the app Settings.
• Customize the fetch interval for a specific repository from the Repository Settings.

The default interval for fetching and updating PRs is every hour.

If you configure repositories to fetch different intervals, you may see some repos not included in a “fetch PRs” job run in the logs. For example, you may have a few repositories fetching updates several times per hour, but the rest on an hourly cadence. When each of these jobs run, you’ll only see the repositories with that fetches interval appear in the logs for that job.

Manually Fetch PRs

When a job is running, you cannot manually fetch PRs. An animation appears in the PR Focus toolbar and replaces the Fetch PRs buttons. The buttons return when the job is complete.

Fetch all PRs

You can manually press the Fetch all PRs button at the upper right hand of the PR Focus window. This gets updates from GitHub for all of the solo pull requests and repositories you watch.

Fetch PRs for a Specific Repository

You can manually press the Fetch specific repo button at the upper right hand of the PR Focus window. This opens a dropdown of all of the repositories you’re watching. You can select a specific repository, and PR Focus fetches only the updates for that repository. This is useful if you’re watching a lot of repositories, and don’t want to wait for all of the fetch jobs to run - you can quickly fetch only the updates for a single repository.

What Does Fetching PRs Do?

When you press the Fetch PRs button, this kicks off a few jobs:

• It fetches updates for the solo PRs you’re watching
• It fetches a list of open pull requests in all of the repositories you’re watching
• During a fetch job:
  • If the PR has previously been added and is still open in PR Focus but closed in the remote repository, PR Focus fetches updates from the remote repository, and updates the status.
  • If the PR is merged or closed in PR Focus and not listed as “open” on the remote repository, PR Focus does not fetch updates for it.
  • While fetching updates, PR Focus looks for any new commits, comments, reviews, or status checks, adds them to the PR details, and increments the PR summary counts.
  • If PR updates include adding you as an assignee or requestedReviewer, PR Focus moves the PR to the appropriate list in your dashboard.

2 - Incoming PRs

PR Focus automatically fetches new pull requests and updates to existing pull requests:

• When you start PR Focus
• When you watch a solo pull request or repository
• At regular intervals while the app is open

You can also manually fetch PRs at any time.

If a PR already exists in PR Focus matching the PR number, PR Focus retrieves the most up-to-date version of the PR from GitHub and updates the details in PR Focus. If an open PR does not match a PR number that PR Focus already knows about, it creates a new PR.

Assigned, Reviewer, or My PR

If you are an assignee, a reviewer, or if the PR was made by you, the incoming PR goes directly into one of those columns, bypassing your Inbox. For more details about how PR Focus determines these states, refer to View a Repository.

Inbox

When the PR was made by somebody other than you, and you’re not an assignee or a reviewer, the PR goes to your Inbox. You’ll see a PR Summary giving you information about the PR, and you can click into it to view more details.

The list of PR Summaries in your Inbox let you quickly scan a list of new PRs and decide whether they require action from you or you can safely ignore them. You can view PRs in your Inbox on a per-repository basis, or see a list of all incoming PRs in the All Pull Requests view.

Watch, Ignore PR, or Archive PRs

You can watch, ignore, or achive a PR in one of three ways:

• If you can tell from the PR Summary what action you want to take, right-click on the PR Summary and select Watch PR, Ignore PR, or Archive PR from the context menu. Archive PR is only available if the PR is closed.
• Click into the PR Summary to view the PR Details and decide what action you want to take. Press the Watch, Ignore, or Archive buttons.
• Click the Perform bulk operations button to enable multi-selection. Select multiple PRs, and press the Watch, Ignore, or Archive buttons. The Archive button becomes disabled if you select a PR that is still open, as you can only archive closed PRs. Press the Perform bulk operations button again to hide the bulk operation buttons and disable multi-select in the list. You can only perform bulk operations in the aggregate Inbox.

You can also select the “Open in GitHub” option if you want to view details about the PR that are not available in PR Focus, such as looking at the PR diff.

Watch or Ignore a PR from the PR Summary

Watch or Ignore a PR from the PR Detail View

Perform Bulk Operations from the Aggregate Inbox List

When you press the Perform bulk operations button, this enables multi-selection in the Inbox list. The PR Summary switches to a less information-dense view with a few basic details:

• PR Name
• PR Status
• PR Number
• Repository

While in this view, select PRs and press the relevant button to perform a bulk operation. Press Perform bulk operations again to disable multi-selection and return the list to its normal behavior.

When to Watch or Ignore PRs

You might want to watch a PR if:

• You’re dependent on the work being merged
• You need to follow the status of the work for reporting reasons
• You may need to review the PR in the future
• Purely for personal interest because you’re curious about the feature

You might want to ignore a PR if:

• The work is internal to the originating team and you don’t need to know the outcome
• You haven’t interacted with the PR and don’t care about its progress

When you watch a PR, it goes into your Watched PRs list, both in the Repository Dashboard and in the All Pull Requests Dashboard.

When you ignore a PR, it goes into the Ignored PRs Dashboard.

Watch or Ignore Cannot Override Assigned, Reviewing, or My PR

When you are assigned to a PR, you are a PR reviewer, or the PR was made by you, Watch or Ignore has no effect. Watching such a PR does not move it into your Watched PRs list, and ignoring such a PR does not move it to the Ignored PRs dashboard.

This is an intentional design decision so you don’t miss important work that requires your attention. If you have a use case for changing this functionality, please send me an email or file a feature request.

If you Watch or Ignore an incoming PR, and later you become a reviewer or an assignee, it moves from your Watched PRs list or your Ignored PRs dashboard to the respective column.

Changing Watch or Ignore Status

Watch and Ignore are mutually exclusive options. If you have previously watched a PR, and then press the Ignore button, PR Focus stops watching the PR and moves it into the Ignored PRs dashboard. If you have previously ignored a PR, and then press the Watch button, PR Focus stops ignoring it and moves it from the Ignored PRs dashboard back to the Watched PRs list.

You can change the watch or ignore status in the same ways you can set it - from right-clicking on a PR Summary or while viewing the PR Details.

If you choose to Stop Watching or Stop Ignoring a PR, the behavior varies depending on whether it came into PR Focus through watching a repository, or whether it’s a PR you added as a solo PR.

In a Watched Repository

If the PR is still open, it goes back to your Inbox. If the PR is no longer open, it disappears until it eventually becomes archived at the interval you’ve configured. Once it is archived, it appears in the Archived PRs dashboard.

You might stop watching a PR if you’re undecided if you need to pay attention to it. You might choose this option instead of going directly to Ignore if you want to see upcoming changes to a PR before deciding how to react to it.

When it’s a solo PR

If you have added a pull request that isn’t part of a repository you’re watching, it automatically goes into your Watched PRs list. PR Focus assumes that when you Stop Watching one of these pull requests, you no longer care about it, and PR Focus deletes it. This is the only scenario where PR Focus makes it possible to delete a pull request that isn’t closed.

Tag Pull Requests

You can apply custom tags to pull requests to drill down into the work you’re tracking in different ways. Tag a pull request with a release version, a feature name, or a work category to easily view a roundup of related work. For more details, refer to Tagged PRs.

3 - View PR Details

When you’re viewing a Repository Dashboard, the All Pull Requests dashboard, or any of the other pull request dashboards, you can click into a PR Summary to get a detailed view of the pull request.

The PR Details view contains:

• Buttons to Watch or Ignore the PR. Optionally, if the PR is closed, a button to Archive the PR. If you clicked into the PR detail view from a list of PRs that contain PRs before or after the one you’re viewing, you’ll see previous and next buttons to page through all the PRs in the list.
• The PR title, number, description, and date last updated
• A link to view the PR on the GitHub website
• If you have applied tags to the PR, you can see the tags you have applied. You can also apply and remove tags from this view. For more details, refer to Tagged PRs
• A label telling you which repository a PR belongs to, which provides helpful context if you’ve clicked into it from the All Pull Requests view
• A list of commits in the PR, with links to view each commit on GitHub
• A list of status checks for the PR, with links to view each status check on GitHub
• A list of reviews on the PR, with links to view each review on GitHub
• A list of comments on the PR, with links to view each comment on GitHub
• A “New” label for any item that has been added to PR Focus since you last viewed the PR details

Commits

Each commit in the list of commits contains:

• The GitHub user who made the commit (if the commit contains this information)
• The date and time of the commit
• A link to view the commit on GitHub
• The commit message
• A “New” label if you have not viewed PR details since this commit was added to PR Focus

The list of commits displays in chronological reverse order, with the most recent commit at the top of the list.

Status Checks

Status Checks in PR Focus refer to a list of jobs or statuses associated with a PR. These may be GitHub workflow runs, CI jobs, or other required checks that repository rules enforce on a PR.

Each status check in the list of status checks contains:

• Information about whether the status check passed or failed
  • A green checkmark for passing checks
  • A red X mark for failing checks
• The name of the status check
• An icon, if one is associated with the status check
• A link to view it on GitHub
• A “New” label if you have not viewed PR details since this status check was added to PR Focus

PR Focus displays the status checks for the branch head commit sha at the time of the last fetch job. This information may not match the current state of status checks if:

• A more recent status check or workflow run has occurred since PR Focus last fetched the status checks
• The status check or workflow run was still running in GitHub when PR Focus checked for updates, and PR Focus does not have the status of the completed job

Missing Status Checks

Status checks or workflow runs come from GitHub in many different structures. PR Focus is still fine-tuning the best way to get the relevant status checks for the branch head. If you are missing status checks that you expect to see, please let me know these details (if the repo is public and you are able to share):

• The repo owner and name
• The PR number
• What checks you see in PR Focus
• The checks you expect to see that are missing from PR Focus

Feel free to file an issue, send me an email, or contact me directly with these details. Thank you!

Reviews

Each review in the list of reviews contains:

• The review status, which is one of:
  • Approved: The reviewer has approved the PR. Indicated by a green review approved icon
  • Changes Requested: The reviewer has requested changes on the PR. Indicated by a red request changes icon
  • Commented: The reviewer has commented without approving or requesting changes. Indicated by a yellow commented icon
• The GitHub user who left the review
• The date and time of the review
• A link to view the review on GitHub
• A review message, if one was left with the review.
• A “New” label if you have not viewed PR details since this review was added to PR Focus

The list of reviews displays in chronological reverse order, with the most recent review at the top of the list.

Comments

Each comment in the list of comments contains:

• The GitHub user who left the comment
• The date and time of the comment
• A link to view the comment on GitHub
• The comment text
• A “New” label if you have not viewed PR details since this comment was added to PR Focus

The list of comments displays in chronological reverse order, with the most recent comment at the top of the list.

Note: In PR Focus v0.2.0, I added a module to parse GitHub-flavored Markdown to nicely formatted text in the PR Detail view. I have seen some impact to performance when scrolling comment lists since adding this module. If you have performance issues when scrolling, the UI should un-freeze again after a short delay. Please let me know if you run into this issue so I can troubleshoot and potentially re-evaluate using this module.

4 - Filter PRs

You can define custom filters to automatically perform one of these actions when an incoming pull request meets your criteria:

• Watch
• Ignore
• Apply a Tag
• Mark important ¹

You can define criteria that determines when PR Focus should apply your filter, similar to email filtering.

If you want to find out about incoming pull requests, but automatically ignore certain PRs, such as Snyk dependency update PRs, you can define a filter to Ignore pull requests made by the Snyk PR user - in our case, admin-token-bot.

If your organization uses naming conventions in pull requests, you might want to automatically Watch a PR, or apply a specific tag to it, when the title includes “Feature:” or “Bug:” naming patterns.

Create a Filter

To create a new filter:

1. Go to the Filters menu.

2. Select Create a Filter

   

3. Provide a name for the filter.

4. Add at least one condition for PR Focus to determine when to apply the filter. You can optionally add multiple conditions.

5. Specify the action PR Focus should take when an incoming PR meets the filter criteria.

6. Press the Create Filter button.

Add Filter Criteria

You can define the criteria that PR Focus uses to determine whether or not to apply the filter. Filter criteria consists of:

• A supported field to filter
• A condition to determine whether or not to apply the filter
• A user-defined string to check for in the filter field

You cannot create a filter unless you provide a user-defined string.

You can optionally provide more than one condition. If you supply more than one condition, you must specify the filter logic that PR Focus should use when determining whether to apply the filter.

Supported Fields

You can select one of these fields for PR Focus to evaluate whether or not to apply the filter:

• Username: The GitHub username of the pull request author
• Title: The pull request title
• Description: The content contained in the initial comment by the pull request author, which may include a pull request template and typically contains the PR author’s description of the pull request.
• Repository: The repository default name (for example, prfocus-website in https://github.com/dacharyc/prfocus-website), or the custom name for a repository you have defined in PR Focus.

Conditions

PR Focus evaluates these conditions when determining whether or not to apply the filter:

• exactly matches: the text in the selected field is an exact match (==) for the user-defined string. For example, username exactly matches admin-token-bot evalutes to true - and the filter is applied - when the PR author’s username is “admin-token-bot.”
• includes: the text in the selected field contains the user-defined string. PR Focus does not attempt to do any stemming or tokenization. This implementation uses the .contains() operator. For example, username includes admin-token-b evaluates to true - and the filter is applied - when the PR author’s username is “admin-token-bot.”
• does not match exactly: the text in the selected field does not match (!=) the exact user-defined string. For example, username does not match exactly bot evaluates to true - and the filter is applied - when the PR author’s username is “admin-token-bot.” The text contains the user-defined string, but it’s not an exact match.
• does not include: the text in the selected field does not contain the user-defined string. PR Focus does not attempt to do any stemming or tokenization. This implementation uses the !.contains() operator. For example, username does not include dacharyc evaluates to true - and the filter is applied - when the PR author’s username is “admin-token-bot.” If the user-defined text was bot, this would evaluate to false, because the “admin-token-bot” username does contain bot, and the filter would not be applied.

When evaluating these conditions, PR Focus uses case-insensitive comparison with the user-defined string.

User-Defined Strings

PR Focus requires a user-defined string to evaluate the condition. It does not accept an empty string, and does not support regex or wildcard matching.

PR Focus converts both the text and the user-defined string to lowercase for comparison, making it a case-insensitive comparison.

Apply Filter Logic

When you create a filter, you must supply at least one condition. You can optionally supply multiple conditions for a filter. When you provide more than one condition, you can specify the logic that PR Focus uses to apply the conditions. PR Focus supports the following logical operators:

• any of: if any of the conditions evaluate to true, PR Focus applies the filter. For example, if you define a username condition and a title condition, and the title meets your condition but the username does not, PR Focus applies the filter. “Any of” means at least one condition must apply. As long as at least one condition applies, the filter applies - even if the other conditions don’t apply.
• none of: if all of the conditions evaluate to false, PR Focus applies the filter. For example, if you define a username condition and a title doesn’t meet your condition, but the username does, PR Focus does not apply the filter. “None of” means that if any of your conditions do apply, the filter overall does not apply.
• all of: if all of the conditions evaluate to true, PR Focus applies the filter. For example, if you define a username condition and a title condition, and the username meets your condition but the title does not, PR Focus does not apply the filter. “All of” means that if any of your conditions do not apply, the filter overall does not apply. In other words, all of your conditions must evaluate to true.

Specify the Filter Action

When you create a filter, you specify what action PR Focus should take when a filter applies to a pull request. Available filter actions include:

• Watch: PR Focus automatically watches the PR on your behalf. It bypasses your Inbox and appears in your Watched PRs list as if you had manually selected to Watch the pull request.
• Ignore: PR Focus automatically ignores the PR on your behalf. It bypasses your Inbox and appears in your Ignored PRs dashboard as if you had manually selected to Ignore the pull request. Ignored PRs still appear in your main dashboards if you’re the PR author, or if you become a reviewer or assignee. For more details, refer to Ignored PRs: Unexpected Ignore Behavior.
• Apply a Tag: PR Focus automatically applies the tag you select. The PR appears in your Inbox or relevant lists already tagged, and is available in the Tagged PRs dashboard with your tag applied.
• Mark important: Mark important is a feature whose supporting functionality is coming in a future release. For the moment, “Mark important” has no visible effect.

Update a Filter

To update a filter:

1. Go to the Filters menu.

2. Select Manage Filters.

   

3. Press the Edit Filter button next to the filter you want to change.

   

From the Edit Filter window, you can:

• Rename the filter
• Add, remove, or change filter criteria
• Change the filter logic if your filter has multiple criteria (any, all, none)
• Change the filter action

When you have finished the filter edits, press the Update Filter button.

Delete a Filter

To delete a filter:

1. Go to the Filters menu.

2. Select Manage Filters.

   

3. Press the Delete Filter button next to the filter you want to remove from PR Focus.

   

5 - Pull Request Dashboards

5.1 - Tagged PRs

You can use tags to create your own categories to track important pull requests. You might create a tag to easily categorize pull requests:

• Going into a specific release
• Related to a new feature, even across repositories
• For a specific client
• Conforming to a certain naming protocol that has significance in your workplace, like “Feature” or “Bug”

You can apply tags to pull requests manually, or create filters to automatically tag incoming pull requests that meet criteria you define.

Once you have tagged pull requests, you can view and filter your tagged PRs in the Tagged PRs dashboard.

Tagged PRs Dashboard

In the Tagged PRs dashboard, each pull request summary displays a list of tags that have been applied to it.

You can filter PRs by tag, and optionally within a date range by one of the available date fields.

Filter PRs by Tag

You can filter PRs by tag using the Tag filter in the upper left-hand corner of the Tagged PRs dashboard. Select a specific tag to view only the PRs related to that tag. Or select the placeholder “Filter by Tag” to clear the tag filter.

Filter PRs within a date range

You can filter PRs within a date range in the Tagged PRs dashboard. Press the Filter by date button in the upper-right corner of the Tagged PRs dashboard. This opens the date picker.

Select a start date, and an optional end date. You can specify the type of pull request activity to use in the date filter:

• Created at date
• Updated at date
• Closed at date
• Merged at date

If a pull request has not yet been closed or merged, the closed and merged dates are nil, so the PR will not show up in either of those filters.

Press the Apply button to view only pull requests where the specified pull request activity falls within the date range. When you’re done, press the Clear button to remove the date filter.

Apply Tags to PRs

You can apply tags to a PR from two places:

• The right-click context menu available when you’re viewing pull request summaries in a list view. Right-click a PR summary, and select Apply Tags.

  

• The pull request detail view. Select a tag from the Apply Tags menu in the upper right-hand corner of the detail view, above the repository label.

  

Any tags that you’ve created appear in this menu, sorted by most recently updated.

When you apply a tag, the pull request summary gets a “Tag” icon.

The tag appears in the pull request detail view. And the tag is displayed in the pull request summary when you’re viewing the Tagged PRs dashboard.

Remove Tags from PRs

You can remove tags from a PR from two places:

• The right-click context menu available when you’re viewing pull request summaries in a list view. Right-click a PR summary, and select Remove Tags. Choose the tag you want to remove.

  

• The pull request detail view. Right click on a tag in this view, and select the Remove Tag option.

  

The tag is removed from the PR. If no other tags apply, the PR no longer appears in the Tagged PRs dashboard.

Create and Manage Tags

You can create and manage tags from the Tags menu.

Create a Tag

To create a new tag:

1. Go to the Tags menu.

2. Select Create a Tag

   

3. Provide a name for the tag.

   

4. Press the Create Tag button.

Rename or Delete a Tag

To rename or delete a tag:

1. Go to the Tags menu.

2. Select Manage Tags.

   

3. Click a tag name to bring up a sheet where you can edit the tag name. This automatically renames the tag in the menus, and on all PRs that have had the tag applied.

   

4. Press the Delete tag button to remove a tag from PR Focus. This automatically untags all PRs that have the tag applied.

   

5.2 - Solo PRs

In addition to watching a repository for every pull request that comes through it, you can watch individual pull requests - without watching the repository. You might want to watch an individual pull request:

• When the repository is too busy to watch the entire repo
• When you’re watching your own pull request in a repo you don’t normally visit, and want to know when it has activity
• When someone is proposing an important patch or update in a repo you don’t normally watch, and you want to know when it’s merged

You can watch these “one-off” pull requests in PR Focus. The app refers to pull requests that don’t come through watching a repository as a “Solo PR.”

How to Watch a Solo PR

To watch a solo PR:

1. Go to the Pull Requests menu in the menu bar

2. Select Watch a PR

   

3. Enter a GitHub URL for the pull request you want to watch, similar to https://github.com/swiftlang/swift/pull/74908.

   

4. Press the Watch PR button

This validates the PR URL, checks the GitHub permissions to confirm you can access the relevant repository, and enqueues a job to fetch the solo PR details. Once any running jobs are complete, PR Focus gets the PR details from GitHub.

View Updates to Solo PRs

Once PR Focus fetches the solo PR details, it appears in the “Watched” list in two dashboards:

• In the All Pull Requests dashboard (unless it falls under the rules to become inactive or archived)
• In the Solo PRs dashboard

PR Focus provides individual repository dashboards to let you focus on a subset of pull requests. If you’re watching a lot of repositories, or highly active repositories, the All Pull Requests dashboard may make it easier to miss updates. The Solo PRs dashboard serves this same purpose for pull requests that don’t fall into a repository dashboard.

PRs in the Solo PRs dashboard are sorted by updated date.

Unlike the repository dashboards and the All Pull Requests dashboard, pull requests never move out of the Solo PRs dashboard when they become inactive or archived. PR Focus assumes that pull requests you felt were important enough to add manually should not “get out of the way” until you manually stop watching them.

Stop Watching a Solo PR

You can stop watching a solo PR the same way you can stop watching PRs that come in through watched repositories:

• Right click a PR Summary to open the context menu, and select Stop Watching
• View the PR Details and press the Stop Watching button

However, unlike PRs that come in through watched repositories, when you stop watching a solo PR, PR Focus deletes it from the app. It does not go to your Inbox for you to re-process at a future time.

This is the only way to remove a pull request from the Solo PRs dashboard.

Solo PR Fetch Interval

Unlike watched repositories, you cannot customize the interval to fetch solo PRs. PR Focuses uses the “several times per day” interval to automatically fetch updates to solo PRs. You can manually fetch updates to solo PRs at any time by pressing the Fetch PRs button.

Watch a Repository Where You’ve Added a Solo PR

In some cases, you might watch a solo PR in a repository, and then later decide to watch the repository for all activity. When you Watch a Repository, PR Focus starts treating solo PRs the same as any other pull request that comes in through watching a repository. The solo PR no longer appears in the Solo PRs dashboard, and instead appears in the Repository Dashboard for the repository. If you stop watching a solo PR after you have started watching its repository, it moves to the Inbox for you to re-process at your convenience.

Customize Solo PR Repository Details

When you watch a solo PR, PR Focus creates a “hidden” repository that behaves differently than repositories you watch. It uses the repository name as the repo label on the PR Summary, and selects a random color for the repo label. Unlike a repository you’re watching, PR Focus does not provide the option to customize the repo name or label color for a “hidden” repository.

5.3 - Ignored PRs

From the PR Summary context menu, or when viewing PR details, you can access a button to Ignore a pull request.

You might want to Ignore a pull request if its status and details don’t matter to you. For example, if you’re watching a repository for user-facing changes, and a team puts up a pull request for internal refactoring, you may want to ignore the PR. When you press the Ignore button, the pull request goes into the Ignored PRs dashboard, which gets it out of your main dashboard views.

While a PR is ignored, but its status is still open, PR Focus continues to fetch updates to the pull request.

Ignored PRs Dashboard

This dashboard is a list of PRs that you’ve ignored, sorted by the repository where the PR originated.

You can access the Ignored PRs Dashboard by pressing the Ignored PRs button in the PR Focus sidebar.

The Ignored PRs dashboard does not have a counter. The PR Focus design assumes you do not need to pay attention to ignored PRs.

Stop Ignoring a PR

At any time, you can stop ignoring a PR. You might want to stop ignoring a PR if you have a reason to think you might need to pay attention to it, but you’re not necessarily ready to watch it. When you stop ignoring a PR, it moves out of your Ignored PRs Dashboard and into the Inbox.

To stop ignoring a PR:

1. Go into your Ignored PRs Dashboard.
2. Find the PR you want to stop ignoring.
3. Use the PR Summary context menu or click into the PR Summary to open the PR Details view.
4. Press the Stop Ignoring button.

If you want an ignored PR to move directly to your Watched PRs list, press the Watch button instead of the Stop Ignoring button. This automatically stops ignoring the PR and moves it directly to your Watched PRs list.

Unexpected Ignore Behavior

PR Focus is an opinionated app designed to prevent you from missing important pull requests that require your attention. It includes some important design decisions that may result in behavior that seems unexpected unless you understand the design rationale:

• Some PRs may not move to the Ignored PRs dashboard
• PRs may come back from the Ignored PRs dashboard without you doing anything
• You cannot delete an open PR - you can only ignore it

PR Not Moving to Ignored PRs

If you try to ignore a PR where you are an assignee, a reviewer, or where the PR is yours, it does not move into the Ignored PRs Dashboard. It stays in the relevant column in the Repository Dashboard and All Pull Requests Dashboard.

This is an intentional design decision to prevent you from missing important work that requires your attention.

PR Comes Back from Ignored PRs

If you have previously ignored a PR, but you later become an assignee or reviewer, the PR moves out of the Ignored PRs Dashboard and into the relevant column in the Repository Dashboard and All Pull Requests Dashboard.

This is an intentional design decision to prevent you from missing important work that requires your attention.

You Can Only Ignore - Can’t Delete - an Open PR

In some cases, you may want to delete a pull request instead of ignoring it. You might want to delete a pull request when you’re absolutely certain you don’t need to pay attention to it.

PR Focus does not allow deleting open pull requests. This is an intentional design decision, as PR Focus assumes you may eventually become a reviewer or assignee on an open pull request. Ignoring a pull request is intended to remove it from the pull requests you need to pay attention to, while preserving the ability to let you know if it moves into a state where you need to pay attention to it.

5.4 - Inactive PRs

Sometimes, a PR sits for a long time without progress. This may be because:

• A PR is blocked while waiting for external dependencies
• A PR is waiting for other contributors
• For business reasons, work on the PR is paused
• Many other reasons

In these cases, you may still care about the eventual outcome of the PR, but it becomes clutter sitting around in your regular PR Focus dashboards while no activity is occurring. You may not want to Stop Watching or Ignore a PR, but may want to get it out of your way.

This is the case that Inactive PRs solves.

Inactive PRs Dashboard

After some interval, a PR that hasn’t had updates moves to the Inactive PRs Dashboard. This dashboard is a list of PRs that have become inactive, sorted by the repository where they originated.

You can click into the PR Summary for an inactive PR to view the PR Details.

A PR becoming inactive is one of two ways in which a PR can move out of:

• My PRs
• Assigned PRs
• Reviewing PRs

The only other way a PR can move out of these columns is when it becomes archived, or if you are no longer an assignee or a reviewer.

You can configure the Days until inactive setting from:

• App Settings
• Repository Settings

The default value for this setting is 30 days.

Moving a PR Out of Inactive PRs

There is no way to manually move a PR out of the Inactive PRs dashboard and back into your Repository Dashboard and All Pull Requests Dashboard.

When a PR receives updates again, it moves out of the Inactive PRs dashboard and back into your Repository Dashboard and All Pull Requests Dashboard.

If you change the value of the Days until inactive setting to a longer time interval, PR Focus recalculates whether PRs should be inactive and moves any PRs that no longer meet this setting. In this case, PR Focus moves inactive PRs back into your Repository Dashboard and All Pull Requests Dashboard.

5.5 - Archived PRs

Some workflows call for you to be able to view PRs after they have been closed or merged. You may still want to see those PRs in your Repository Dashboard or All Pull Requests Dashboard for a period of time after the PR status has become closed or merged.

PR Focus is optimized for this case. PRs do not disappear from your repository views immediately when they get closed. Instead, they remain in your repository views for a number of days until they are archived. The default value for this setting is 10 days, but you can configure the number of days until a PR is archived.

Archived PRs Dashboard

After some interval, a PR that has been closed or merged moves to the Archived PRs Dashboard. This dashboard is a list of PRs that have become archived, sorted by the repositories where they originated.

You can click into the PR Summary for an archived PR to view the PR Details.

A PR becoming archived is one of two ways in which a PR can move out of:

• My PRs
• Assigned PRs
• Reviewing PRs

The only other way a PR can move out of these columns is when it becomes inactive, or if you are no longer an assignee or a reviewer.

Watched PRs also become archived, which automatically moves them from your Watched PRs list to the Archived PRs dashboard.

Configure the Archive Interval

You can configure the Days until archive setting from:

• App Settings
• Repository Settings

The default value for this setting is 10 days.

Immediately Archive a PR

You don’t have to wait until a PR moves to archived automatically. You can immediately archive a closed or merged PR:

• Right click on a closed or merged PR summary in a repository dashboard, and you’ll see the Archive PR option.
• Enter a PR detail view, and you’ll see the Archive PR option alongside the Watch and Ignore buttons.
• In the aggregate Inbox, you can press the Perform bulk operations button to enable multi-select. Select multiple closed PRs, and you can archive them all. If you select a PR that is not closed, the Archive button becomes disabled.

This option is not available for open PRs.

Un-Archiving a PR

You can un-archive a PR from the PR Detail view. Pressing the Un-Archive button returns the PR to whichever column it was previously in. Note that if the PR was archived automatically, un-archiving it is only temporary until the archive job runs again. For more details, refer to Configure the Archive Interval above.

Deleting Archived PRs

PR Focus provides the ability to delete archived PRs. When you’re viewing the Archived PRs dashboard, you can press the Delete PRs button to delete all PRs that are archived.

This button is disabled when a background job is running. If you’re unable to press the Delete PRs button, wait for background jobs to finish and try again.