gh-issues-stats

A Ruby gem for analyzing GitHub repository issues with statistics and visualizations.

gh-issues-stats is a command-line tool that helps you analyze and understand the issues lifecycle in any GitHub repository. It provides detailed statistics, visualizations, and insights about issues including:

• Issue creation trends over time (yearly/monthly breakdowns)
• Closing time statistics (average and median)
• Label-based filtering and analysis
• Visual charts and tables for data representation
• Cached data for faster subsequent queries

gem install gh-issues-stats

git clone https://github.com/tschaefer/gh-issues-stats.git
cd gh-issues-stats
bundle install
rake install

• Ruby >= 3.3.0
• A GitHub account (optional, but recommended for higher API rate limits)

Display yearly statistics for a repository:

gh-issues-stats yearly owner/repository

Example:

gh-issues-stats yearly rails/rails

Options:

• --format FORMAT- Specify output format (table, chart, json). (default: table)
• --label LABEL - Filter by specific label (can be used multiple times; prefix with ! to exclude)
• --[no-]finished - Show finished stats (default: false)
• --[no-]legend - Toggle legend display (default: true)
• --[no-]pager - Toggle output paging (default: false)

Display monthly statistics for a specific year:

gh-issues-stats monthly YEAR owner/repository

Example:

gh-issues-stats monthly 2023 rails/rails

Options: Same as yearly command

Display all labels used in a repository:

gh-issues-stats labels owner/repository

• --configuration-file FILE - Specify a configuration file (default: ~/.config/gh-issues-stats.json)
• --cache-path PATH - Specify cache directory (default: ~/.cache/gh-issues-stats)
• --refresh INTERVAL - Set refresh interval (e.g., 30minutes, 2.5hours, 1day) (default: 24hours)
• -v, --version - Show version information
• -m, --man - Show manual page

Filter issues by multiple labels:

gh-issues-stats yearly --label bug --label '!enhancement' rails/rails

Show monthly breakdown with chart visualization:

gh-issues-stats monthly --format chart 2023 rails/rails

Use with custom refresh interval:

gh-issues-stats --refresh 2hours yearly rails/rails

For higher API rate limits, you can provide GitHub credentials through the configuration file. See Octokit Authentication for supported authentication methods.

Issue data is cached locally in to improve performance on subsequent queries. The cache is automatically refreshed on call based on the refresh interval (default: 24 hours).

• Statistical Analysis: Calculate average and median closing times for issues
• Time-based Grouping: View issues grouped by year or month
• Label Filtering: Filter issues by one or more labels
• Multiple Output Formats: Choose between tables and charts
• Smart Caching: Local SQLite database for fast repeated queries
• Flexible Refresh: Configurable data refresh intervals
• Pagination Support: Built-in pager for large datasets
• Issue Detection: Skips draft issues and pull requests

git clone https://github.com/tschaefer/gh-issues-stats.git
cd gh-issues-stats
bundle install

bundle exec rspec

# Run RuboCop
bundle exec rubocop

# Run with auto-correct
bundle exec rubocop -a

The gem is structured around several key components:

• Database Layer: SQLite-based storage for issue data
• Fetch Module: Retrieves issues from GitHub API using Octokit
• Statistics Module: Calculates various metrics (average, median, etc.)
• Group Module: Organizes issues by time periods
• App Layer: CLI interface built with Clamp

• clamp - Command-line parsing
• faraday-retry - HTTP request retries
• hashie - Enhanced Hash functionality
• octokit - GitHub API client
• pastel - Terminal color output
• sqlite3 - Local data caching
• tty-pager - Output pagination
• tty-table - Table rendering
• unicode_plot - Chart visualization

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• All tests pass
• Code follows RuboCop style guidelines
• New features include appropriate tests

This project is licensed under the MIT License - see the LICENSE file for details.