Pull Requests¶

Ship provides full support for GitHub pull requests. In general, anything that works on github.com for pull requests works in Ship, but Ship also provides some additional conveniences and functionality to make working with pull requests faster and easier.

Filing a New Pull Request¶

Use git to push your changes to a branch

cd $PROJ_DIR
# write code, commit changes
git push origin $feature

In Ship, choose File → New Pull Request (⇧⌘N).
Choose the item corresponding to the changes you pushed in step 1.
(Optional) Choose the destination repo and branch. By default, Ship will autoselect the furthest upstream repo and corresponding default branch, but you can override this using the two combo boxes at the bottom of the window shown above.
Click “Next” (Return)
(Optional) Edit the pull request title and description. Note that any pull request template will automatically be loaded.
Click “Save” (⌘S) to submit your new pull request
(Optional) Request reviewers. Once your pull request has been saved, you can request reviews from anyone with push access to the repository.

Reviewing a Pull Request¶

Locate the pull request you wish to view, either by selecting it in the Ship Overview window (⌘0), or double clicking it from a list view.

Tip

In the Ship Overview, you can restrict your view to just pull requests (or just issues) by selecting the “Issues & Pull Requests” item in the filter bar at the top of the window.

Click the “Review Changes” button to open the diff viewer for the pull request.

The diff viewer will open.

Note

Ship fetches your repository source code for displaying diffs by communicating directly from your Mac to GitHub, without using any intermediate servers. While the initial fetch of your source may take some time for the first pull request you view, successive views of the same pull request will be very fast (and will work even offline), and additional pull requests to the same repository will only require an incremental fetch and so will also be fast.

A Quick Guide to the Diff Viewer¶

Sidebar displays a hierarchical list of files that are changed, according to the project structure.

Code view in the main part of the window shows the full contents of the original and new versions of the file. Both unified and split diff views are available.

Minimap on the right of the window shows a graphical representation of the added, removed, or changed lines, and allows for quick navigation within the file.

Conversation button lets you quickly jump to the pull request conversation view, to see all comments and discussion as well as to edit assignees, reviewers, milestone, and view commit statuses, mergeability information, and more.

Terminal button quickly opens a temporary working copy of the code in the pull request, to allow for building, running tests, or experimentation.

Merge button allows you to merge the pull request (if possible).

Navigation buttons (up and down arrows), allow for easily jumping between changed parts of the code.

Send button (airplane), allows you to summarize and submit your code review.

Navigating Changes¶

When the diff viewer is first opened, it initially displays the first changed line in the first changed file. To navigate sequentially through the diff, use the arrow buttons in the window toolbar, touch bar, or the keyboard shortcuts ^⌘↑ and ^⌘↓ (ctrl-command-up and control-command-down). This will scroll through the files, stopping at each change or comment along the way, as well as stepping page at a time through large diff hunks. Sequential navigation is recommended as a first stop in reviewing a pull request for getting a look at every change being proposed.

Tip

If you have trouble distinguishing the red and green colors used in the diff viewer, enable macOS’s “Differentiate without color” setting under System Preferences → Accessibility → Display. With this setting enabled, Ship will use shapes to indicate which lines are removed or added in the diff viewer.

Adding Comments¶

To add a comment to a change, simply click on the line number in the gutter of the diff view.

The same editor used throughout Ship is provided for adding review comments. You can add attachments by drag and drop, use markdown, and write code using markdown fenced blocks with integrated syntax highlighting.

Once you have composed your comment, you may choose to send it immediately via the “Add Single Comment” button or queue the comment to post as part of a longer review via the “Start Review” button. Pending review comments are saved to GitHub, and may be resumed later either via Ship or github.com.

Note

GitHub only allows for comments on a changed line, or a line within 3 lines of a changed line. Ship uses darker line numbers in the gutter to indicate which lines are eligible for comments.

Viewing Commits¶

To view individual commits in the pull request, click on the … button at the top of the sidebar:

Each commit may be selected to view just the changes in that commit. Ship can also show changes since you last viewed the pull request as well as changes since you last submitted a review for the pull request (if applicable).

Filtering Files¶

Using the filter bar at the bottom of the sidebar, files may be filtered by path, or by whether or not they have been commented upon.

Searching¶

Search for strings within individual files is possible via the standard Mac search bar interface (⌘F), but it is also possible to search all changed files in a pull request via the “Find in Files” section of the sidebar.

By default, find in files searches the entire contents of the changed files, but using the popup menu it is possible to restrict the search to just changed lines.

Sending a Review¶

Once you are finished reviewing the changes in the pull request, click the Send Review button in the toolbar (airplane button), to send your review. You can enter a review summary, and choose to submit the review as either a “comment”, “approve changes”, or “request changes.” The diff viewer will close once you send your review.

Merging a Pull Request¶

Once you are ready to merge a pull request, you can use the merge button either in the pull request conversation view, or within the diff viewer.

At the bottom of the pull request conversation view is a merge checklist that summarizes reviews, status checks, and the mergeability of the branches. Once everything is in order, click “Merge” to merge the changes to the destination branch.

Note

After merging the pull request, if the source branch is in the same repository as the pull request destination, you will have the option to delete the now unneeded source branch.
If you merged a pull request in error, Ship offers the ability to perform a revert. This action opens a new pull request containing a commit to revert the merge.