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. We also use Standard Ruby to keep code style consistent. CI validates commit messages, Standard Ruby, tests, and git-cliff changelog generation 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 tag-driven and published by GitHub Actions to RubyGems. Local release commands never publish directly.

Install git-cliff locally before preparing a release. The release task regenerates CHANGELOG.md from Conventional Commits.

Before preparing a release, make sure you are on main or master with a clean worktree.

Then run one of:

bundle exec rake 'release:prepare[patch]'
bundle exec rake 'release:prepare[minor]'
bundle exec rake 'release:prepare[major]'
bundle exec rake 'release:prepare[0.1.0]'

The task will:

1. Regenerate CHANGELOG.md with git-cliff.
2. Update lib/git/markdown/version.rb.
3. Commit the release changes.
4. Create and push the vX.Y.Z tag.

The Release workflow then runs tests, publishes the gem to RubyGems, and creates the GitHub release from the changelog entry.

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 operators who need clear workflows, fast onboarding, and real human support.

We also build Reviato, “Capture. Interpret. Act.”. Turn guest feedback into clear next steps for your team. Collect private appraisals, spot patterns across reviews, and act before small issues turn into public ones.