git-markdown

Convert GitHub pull requests into a single Markdown file you can review locally. Useful for offline or local AI review workflows with tools like opencode, GitHub Copilot CLI, and your own scripts.

Features

• Reuse existing GitHub credentials.
• Export PR details, threads and summaries as Markdown.
• Filter threads by status and write to a file or stdout.
• Use GitHub Enterprise and local credential storage with restricted permissions.

Install

gem install git-markdown

Quick start

1) Setup (optional)

git-markdown setup

2) Export a PR

From inside a git repository:

git-markdown pr 123

Or specify the repo:

git-markdown pr owner/repo#123

It saves PR-{number}-{title}.md in the current directory by default.

Usage

# Export PR from current repository
git-markdown pr 123

# Export PR from a specific repository
git-markdown pr owner/repo#123

# Output to stdout (useful for piping)
git-markdown pr 123 --stdout | pbcopy  # macOS; on Linux use `xclip`/`wl-copy` or redirect to a file

# Save to a directory
git-markdown pr 123 --output ./reviews/

# Filter comment threads (default: unresolved)
git-markdown pr 123 --status=unresolved
git-markdown pr 123 --status=resolved
git-markdown pr 123 --status=all

# Debug output
git-markdown pr 123 --debug

# Show version
git-markdown version

Authentication

git-markdown looks for a GitHub token in this order:

1. GITHUB_TOKEN or GH_TOKEN environment variables
2. Git credential store (git credential fill)
3. GitHub CLI (gh auth token)
4. Token saved by git-markdown setup

If you see a prompt for a GitHub username or an askpass error, set GITHUB_TOKEN or GH_TOKEN in your environment to skip git credential prompts.

GitHub Enterprise

Set your API URL:

export GITHUB_API_URL=https://github.yourcompany.com/api/v3
git-markdown pr owner/repo#123

Output

The generated Markdown includes:

• PR metadata (title, author, status, created date)
• PR description (full body)
• Review comments grouped by file with line numbers
• General discussion comments
• Review summaries (approvals, change requests)

Threads marked with [resolved] or [done] are filtered out by default. Use --status=all to include them.

Configuration

Config is stored under ~/.config/git-markdown/:

• config.yml for settings (provider, API URL, defaults)
• credentials for the token (permissions: 0600)

Requirements

• Ruby 4.0+
• Git (for remote detection)
• GitHub Personal Access Token with repo scope

Contributing

1. Fork it
2. Create a branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Push (git push origin feature/my-feature)
5. Open a Pull Request

Please use Conventional Commits for commit messages.

Roadmap

• GitLab Merge Request support (git-markdown mr)
• GitLab and GitHub Issue support (git-markdown issue)
• Custom templates
• Optional diff in output

References

• GitHub REST API docs: docs.github.com/en/rest
• GitHub CLI auth token: cli.github.com/manual/gh_auth_token
• Git credential interface: git-scm.com/docs/git-credential
• XDG Base Directory spec: specifications.freedesktop.org/basedir-spec
• RubyGems: rubygems.org/gems/git-markdown

License

MIT License, see LICENSE.txt

Development and releases

Shared tooling uses published Ethos Gemkit. Keep the exact Gemfile version and workflow commit pins on the same release.

bundle install
bundle exec lefthook install
bundle exec rake verify

Release preparation, publication, registry setup and recovery are documented in the Gemkit release guide.