# 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)
```bash
# Clone or download the project
cd github-issues-md

# Install dependencies
poetry install

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

### Using Pip

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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Install in development mode
poetry install

# Run tests
poetry run pytest

# Format code
poetry run black .
poetry run isort .
```