Easy Screenshots in Your CLI Pull Requests


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.