git-markdown

Overview

Export GitHub pull requests and review threads to a single Markdown file. It is for developers reviewing pull-request discussions offline or supplying context to local tools. It exports metadata and discussion; it does not export the code diff. GitLab merge requests and custom templates are not implemented.

Installation

Ruby 4.0 or newer. Git is needed to infer the repository from its remote. Authenticate using an existing GitHub credential source or git-markdown setup; the token must have access to the requested repository.

gem install git-markdown

For a Bundler application, add gem "git-markdown" to its Gemfile and run bundle install.

Quick start

gem install git-markdown
git-markdown pr owner/repo#123

Replace owner/repo#123 with an accessible pull request. The command writes PR-{number}-{title-slug}.md in the current directory. From a checkout with a GitHub remote, git-markdown pr 123 infers the repository.

Usage

Export options

# 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 an existing directory
mkdir -p reviews
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:

GITHUB_TOKEN or GH_TOKEN environment variables
Git credential store (git credential fill)
GitHub CLI (gh auth token)
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 both API URLs. The REST API fetches PR content; GraphQL supplies review-thread resolution states:

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

Provide an Enterprise token through GITHUB_TOKEN or GH_TOKEN. The current Git credential lookup targets github.com, and gh auth token is invoked without an Enterprise hostname. Environment URLs fill unset configuration; values already saved in config.yml take precedence.

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 $XDG_CONFIG_HOME/git-markdown/, or ~/.config/git-markdown/ when XDG_CONFIG_HOME is unset:

config.yml for provider, REST API URL and GraphQL URL settings
credentials for the token (permissions: 0600)

Requirements

Ruby 4.0+
Git (for remote detection)
GitHub credentials with access to the requested repository; classic tokens need repo scope for private repositories

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

Technical details

The CLI uses Thor and GitHub REST endpoints. Authentication checks environment tokens, Git credentials, GitHub CLI credentials and locally saved credentials in that order. Saved token files use mode 0600. Authentication, missing pull requests and API failures exit with status 1. Treat exports according to the source repository’s access restrictions.

Project resources

GitHub repository
RubyGems package
Changelog
Issues
Upgrade notes
MIT license
Development and contributing: fork, create a branch and run bundle exec rake verify before opening a pull request.

About Ethos Link

Ethos Link is a software company founded by Paulo Fidalgo. We publish these Ruby tools alongside our business products.

Reviato: private customer feedback and public review analysis.
Nuntio: prepare, review and schedule social posts.
EthosPlaces: find places, opening hours and contact details.