https://github.com/ethos-link/git-markdown
Convert GitHub pull requests into a single Markdown file for offline review and local AI workflows.
https://github.com/ethos-link/git-markdown
ai ai-agents ai-code-review ai-code-reviewer artificial-intelligence code-review coding-assistant devtools generative-ai github-actions llm pull-request pull-requests
Last synced: 21 days ago
JSON representation
Convert GitHub pull requests into a single Markdown file for offline review and local AI workflows.
- Host: GitHub
- URL: https://github.com/ethos-link/git-markdown
- Owner: ethos-link
- License: mit
- Created: 2026-02-07T12:03:54.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-03-20T15:25:33.000Z (about 2 months ago)
- Last Synced: 2026-04-02T02:11:59.626Z (about 1 month ago)
- Topics: ai, ai-agents, ai-code-review, ai-code-reviewer, artificial-intelligence, code-review, coding-assistant, devtools, generative-ai, github-actions, llm, pull-request, pull-requests
- Language: Ruby
- Homepage: https://www.ethos-link.com/opensource/git-markdown
- Size: 126 KB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Agents: AGENTS.md
Awesome Lists containing this project
README
# git-markdown
[](https://badge.fury.io/rb/git-markdown)
[](https://github.com/ethos-link/git-markdown/actions/workflows/ruby.yml)
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](https://opencode.ai), 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
```bash
gem install git-markdown
```
## Quick start
### 1) Setup (optional)
```bash
git-markdown setup
```
### 2) Export a PR
From inside a git repository:
```bash
git-markdown pr 123
```
Or specify the repo:
```bash
git-markdown pr owner/repo#123
```
It saves `PR-{number}-{title}.md` in the current directory by default.
## Usage
```bash
# 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:
```bash
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
```bash
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](https://lefthook.dev/) with the Ruby [commitlint](https://github.com/arandilopez/commitlint) gem to enforce Conventional Commits on every commit. We also use [Standard Ruby](https://standardrb.com/) 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:
```bash
bundle exec lefthook install
```
### Install locally
```bash
rake install
```
## Release
Releases are tag-driven and published by GitHub Actions to RubyGems. Local release commands never publish directly.
Install [git-cliff](https://git-cliff.org/) 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:
```bash
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`.
1. Update `lib/git/markdown/version.rb`.
1. Commit the release changes.
1. 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](https://www.conventionalcommits.org/) 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](https://docs.github.com/en/rest)
- GitHub CLI auth token: [cli.github.com/manual/gh_auth_token](https://cli.github.com/manual/gh_auth_token)
- Git credential interface: [git-scm.com/docs/git-credential](https://git-scm.com/docs/git-credential)
- XDG Base Directory spec: [specifications.freedesktop.org/basedir-spec](https://specifications.freedesktop.org/basedir-spec/latest/)
- RubyGems: [rubygems.org/gems/git-markdown](https://rubygems.org/)
## License
MIT License, see [LICENSE.txt](LICENSE.txt)
## About
Made by the team at [Ethos Link](https://www.ethos-link.com) — 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](https://www.reviato.com), “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.