Easy Screenshots in Your CLI Pull Requests

2018-08-14

Are you using hub to create your Pull Requests? How are you handling embedding images? Wait... you are embedding images, aren't you? For my money, a screenshot is one of the most important parts of a PR body. The context provided by an image goes a long way towards understanding a proposed change. A picture is worth a thousand words and all that.

Until recently, I'd been using hub to create a pull request, and then editing the PR on GitHub to embed screenshots. This always felt a little clunky and I assumed I'd make it more seamless some day.

Cue the cheesy dramatic music: That day has arrived.

Some instructions here will be Mac-specific but I'm sure you can figure out how to tweak it for your setup.


Since a PR body is just markdown, the mechanics of embedding a screenshot are well understood:

  1. Take a screenshot

    • To avoid littering the desktop or other folders, I prefer to take the screenshot to the clipboard (by default, add CTRL to your shortcut)
  2. Upload the screenshot somewhere that is world-readable

    • For longevity, you should probably use one of your company's s3 buckets for work-related PRs.
  3. Add the markdown to render the screenshot to the PR body

Assuming you did step 1 correctly and have a screenshot in your clipboard, how do we upload it somewhere world readable?

We'll use two new commands (both available via homebrew). pngpaste is a great utility for pasting an image to a file. awscli has an s3 subcommand for uploading files to a bucket.

Besides that, we'll do a little work to make the filename unique and then massage the resulting url into the proper markdown for an image and we're golden:

And there ya go. No more editing the PR after the fact.

If you use vim, you're now a quick :r !s3_image away from embedding a screenshot straight from the clipboard to your PR body. Make it a proper mapping. Declare victory.