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

• 🔐 Zero-config auth: uses your existing GitHub credentials
• 🧾 Clean output: PR details, threads, and summaries in readable Markdown
• 🧰 Practical controls: filter by status, write to file or stdout, debug when needed
• 🏢 GitHub Enterprise support, plus safe local credential storage (XDG-style, tight perms)

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 3.0+
• Git (for remote detection)
• GitHub Personal Access Token with repo scope

Development

git clone https://github.com/ethos-link/git-markdown.git
cd git-markdown

bundle install
bundle exec rake test
bundle exec standardrb
bundle exec rake

Note: Gemfile.lock is intentionally not tracked to avoid conflicts across Ruby versions.

Git hooks

We use lefthook with the Ruby commitlint gem to enforce Conventional Commits on every commit. CI also validates commit messages on pull requests and pushes to main/master.

Run the hook installer once per clone:

bundle exec lefthook install

Install locally

rake install

Release

Releases are triggered by pushed tags and use CHANGELOG.md for GitHub release notes.

If you want changelog automation, install git-cliff (https://github.com/orhun/git-cliff) locally and use it to update CHANGELOG.md.

The release workflow expects a ## [X.Y.Z] entry in CHANGELOG.md that matches the tag. Note: release:prep enforces a clean working tree and must run on the main or master branch; it will skip if the changelog has no changes.

Before bumping, install dependencies:

bundle install

Then run:

# 1) Bump the version (commit created)
bundle exec gem bump -v X.Y.Z

# 2) Prepare release (changelog + tag + push)
bundle exec rake release:prep

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

About

Made by the team at Ethos Link — practical software for growing businesses. We build tools for hospitality and retail teams who don’t have time for complicated setups: plain-language insights, fast onboarding, and real human support so you can get clear insights, take action, and move on.

We also build Reviato, “More stars. Less hassle.”. Reviato helps restaurants, hotels, clinics, vets and other local businesses collect and analyse customer reviews, highlights recurring themes, and turns feedback into actionable next steps.