ghpr

"Clone" GitHub PRs/issues, locally edit title/description/comments, "push" back to GitHub, and mirror to Gists.

• Sometimes PR and issue descriptions/comments warrant more complex editing than GitHub's web UI comfortably allows.
• ghpr lets you "clone" PRs and issues locally as Markdown files (including titles and comments), so you can edit them with your favorite IDE, then "push" updates back to GitHub.
• ghpr also mirrors PR/issue content to Gists, for version control and easy sharing / backing up / syncing across machines.

Examples:

• marin#1773: issue with complex description and comments (e.g.); mirrored to this gist
• marin#1723: PR with complex description, mirrored to this gist

Features

• Clone PR/Issues locally with comments
• Sync bidirectionally between GitHub and local files
• Diff local changes vs remote (with ownership warnings for others' comments)
• Push updates back to GitHub
• Gist mirroring for version control and sharing
• Comment management - edit and sync PR/issue comments
• Draft comments - create new*.md files, push to post as comments
• Shell integration - aliases and tab completion for subcommands, flags, and options

Installation

pip install ghpr-py

Usage

Basic Workflow

# Clone a PR or issue (to `gh/123` by default)
ghpr clone https://github.com/owner/repo/pull/123
# or
ghpr clone owner/repo#123
# or, from inside a repo on a branch with an open PR, no args:
ghpr clone

# Make edits to:
# - Title / Description: `gh/123/repo#123.md`
# - Comment files: `zNNNNNN-<author>.md` (existing comments) or `new.md` (new comments)

# Show differences (between local "clone" and GitHub)
ghpr diff

# Push changes
ghpr push

Adding Comments

To add a new comment, create a file starting with new and ending in .md:

# Create a draft comment
echo "My comment text" > new.md

# Commit it
git add new.md
git commit -m "Draft comment"

# Push to GitHub (posts the comment and renames to z{id}-{author}.md)
ghpr push

The push command will:

1. Post new*.md files as comments to GitHub
2. Create a commit renaming them to z{comment_id}-{author}.md
3. Sync to the gist mirror

Uploading Images

# Upload image(s) to this issue or PR's Gist mirror, and get markdown URLs
ghpr upload screenshot.png
# Output: ![screenshot.png](https://gist.githubusercontent.com/...)

Note: GitHub serves gist raw files as application/octet-stream, so images render in markdown but videos won't preview inline. For videos, use GitHub's native drag-drop upload in the web UI instead.

Directory Structure

Cloned PRs and issues are stored as:

gh/
  123/                    # Filed PRs/issues (numbered)
    repo#123.md           # Main description
    z3404494861-user.md   # Comments (ID-author format)
    z3407382913-user.md
  drafts/                 # In-flight drafts (not yet filed)
    my-feature/
      DESCRIPTION.md
  new/                    # Default single-draft slot (ghpr init with no arg)
    DESCRIPTION.md

Since PRs are issues in GitHub's API, we use the same gh/{number}/ pattern for both. Each gh/<number>/ and gh/drafts/<slug>/ is its own nested git repo, so the parent project can safely add gh/ to its .gitignore — ghpr clone and ghpr create set up nested git tracking automatically.

Parallel drafts

Pass a slug to stage multiple drafts at once:

ghpr init my-feature       # creates gh/drafts/my-feature/
ghpr init another-issue    # creates gh/drafts/another-issue/
ghpr create my-feature     # files the my-feature draft → renames to gh/<N>/

Shell Integration (Optional)

For users who want shorter aliases, ghpr provides shell integration:

Bash/Zsh

Add to your ~/.bashrc or ~/.zshrc:

eval "$(ghpr shell-integration bash)"

Fish

Add to your ~/.config/fish/config.fish:

ghpr shell-integration fish | source

Available Aliases

After enabling shell integration, you get convenient shortcuts and tab completion for subcommands, flags, and options:

ghprc      # ghpr clone (no args = clone branch's PR; + cd into directory)
ghpri      # ghpr init (+ cd into draft dir; pass slug for gh/drafts/<slug>/)
ghprcr     # ghpr create
ghprd      # ghpr diff
ghprp      # ghpr push
ghprl      # ghpr pull
ghpro      # ghpr open
ghprsh     # ghpr show
ghpru      # ghpr upload
ghia       # ghpr ingest-attachments
# ... and more (-n, -g, -o variants)

See the full list with:

ghpr shell-integration bash