GitHub Issues to Markdown

A command-line tool that downloads all issues from a GitHub repository and compiles them into a single markdown file with token counting.

Prerequisites

• Python 3.8 or higher
• GitHub CLI (gh) installed and authenticated
• Poetry (recommended) or pip

Installation

Using Poetry (Recommended)

# Clone or download the project
cd github-issues-md

# Install dependencies
poetry install

# The script will be available as 'github-issues-md'

Using Pip

# From the repo
pip3 install git+https://git.laziness.rocks/PootisPenserHere/github-issues-md.git

# Clone or download the project
cd github-issues-md

# Install the package
pip3 install .

# Or install in development mode
pip3 install -e .

Setup GitHub CLI

Make sure GitHub CLI is installed and authenticated:

# Install GitHub CLI (if not already installed)
# On macOS: brew install gh
# On Ubuntu: sudo apt install gh
# On Windows: winget install GitHub.cli

# Authenticate with GitHub
gh auth login

Usage

# Basic usage with repository format
github-issues-md owner/repo

# Using full GitHub URL
github-issues-md https://github.com/owner/repo

# Filter by date range
github-issues-md owner/repo --after 2023-01-01 --before 2023-12-31

# Limit number of issues
github-issues-md owner/repo --limit 10

# Filter by state (open, closed, all)
github-issues-md owner/repo --state open

# Combine filters
github-issues-md owner/repo --after 2023-06-01 --limit 5 --state closed

# Save to file
github-issues-md owner/repo > issues.md

Options

• repo: GitHub repository (required) - can be owner/repo format or full GitHub URL
• --before DATE: Only issues created before this date (YYYY-MM-DD format)
• --after DATE: Only issues created after this date (YYYY-MM-DD format)
• --limit N: Maximum number of issues to fetch
• --state STATE: Issue state to filter by (open, closed, all) - default: all

Output

The tool outputs a markdown file to stdout containing:

• Repository information and generation metadata
• Each issue with its title, author, state, dates, and description
• All comments for each issue with author and timestamp
• Token count at the end using tiktoken

Each issue and its discussions are clearly separated with markdown headers and horizontal rules.

Examples

# Get all issues from a popular repository
github-issues-md microsoft/vscode > vscode-issues.md

# Get only open issues from the last 30 days
github-issues-md facebook/react --after 2023-11-01 --state open

# Get the latest 20 issues
github-issues-md owner/repo --limit 20

Development

# Install in development mode
poetry install

# Run tests
poetry run pytest

# Format code
poetry run black .
poetry run isort .