ghpr-py 0.1.9

GitHub PR/Issue management: clone, edit, and push PR/issue descriptions and comments, with gist mirroring

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

# 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/
  repo#123.md             # Main description
  z3404494861-user.md     # Comments (ID-author format)
  z3407382913-user.md

Since PRs are issues in GitHub's API, we use the same gh/{number}/ pattern for both.

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 (+ cd into directory)
ghpri      # ghpr init (+ cd into gh/new)
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