GemChangelogDiff

CLI that shows you the changelog diff for each gem before you bundle update, pulled from GitHub releases.

Table of Contents

• Installation
• Usage
  • GitHub Authentication
  • Output Formats
  • Output Control
  • Detection Strategy
  • Filtering
  • Interactive Mode
  • Show Subcommand
  • Caching
  • Dry Run
  • Configuration File
• Development
• Contributing
• License

Installation

Install the gem by executing:

gem install gem_changelog_diff

Or add it to your Gemfile:

bundle add gem_changelog_diff

Back to top

Usage

gem_changelog_diff

Run from a project directory with a Gemfile.lock. The tool detects outdated gems via bundle outdated, looks up their GitHub repositories, fetches release notes, and displays a formatted changelog diff.

gem_changelog_diff version    # Print version
gem_changelog_diff --version  # Same as above

GitHub Authentication

To avoid the 60 requests/hour unauthenticated rate limit, provide a GitHub personal access token:

gem_changelog_diff --token ghp_your_token
# or
export GITHUB_TOKEN=ghp_your_token
gem_changelog_diff

Token resolution priority: --token flag → GITHUB_TOKEN env → Rails credentials → config file.

Rails Credentials

When running inside a Rails app, the token is automatically read from Rails credentials:

Rails.application.credentials.dig(:gem_changelog_diff, :github_token)

Set it via rails credentials:edit:

gem_changelog_diff:
  github_token: ghp_your_token

Output Formats

gem_changelog_diff --format text      # Plain text with ANSI colors (default)
gem_changelog_diff --format json      # JSON for piping to jq or CI tools
gem_changelog_diff --format markdown  # Markdown for PR descriptions
gem_changelog_diff --output report.md --format markdown  # Write to a file

Output Control

gem_changelog_diff --verbose   # Show detailed status messages
gem_changelog_diff --quiet     # Suppress warnings
gem_changelog_diff --no-color  # Disable colored output

The tool also respects the $NO_COLOR environment variable.

Detection Strategy

gem_changelog_diff --strategy lockfile   # Parse Gemfile.lock directly
gem_changelog_diff --strategy outdated   # Use bundle outdated only
gem_changelog_diff --strategy auto       # Try bundle outdated, fallback to lockfile (default)
gem_changelog_diff --lockfile path/to/Gemfile.lock  # Custom lockfile path

Filtering

gem_changelog_diff check rails sidekiq  # Only check specific gems
gem_changelog_diff --group development   # Filter by Bundler group
gem_changelog_diff --ignore rails rake   # Exclude specific gems

Interactive Mode

gem_changelog_diff --interactive  # Multi-select which gems to check
gem_changelog_diff -i             # Short alias

After detecting outdated gems, presents a multi-select prompt where you can choose which gems to fetch changelogs for.

Show Subcommand

Look up changelogs for a specific gem between two versions, without needing a Gemfile.lock:

gem_changelog_diff show rails 7.0.8 7.1.3
gem_changelog_diff show rails 7.0.8 7.1.3 --format json

Caching

API responses are cached to ~/.cache/gem_changelog_diff/ with a 24-hour TTL. Subsequent runs reuse cached data and use ETag conditional requests to avoid consuming rate limit.

gem_changelog_diff --no-cache             # Bypass the cache
gem_changelog_diff --cache-ttl 3600       # Set TTL to 1 hour
gem_changelog_diff cache clear            # Clear all cached data

Dry Run

Preview which gems would be checked without fetching changelogs:

gem_changelog_diff --dry-run                     # List gems in text format
gem_changelog_diff --dry-run --format json       # JSON array of gem objects
gem_changelog_diff --dry-run --format markdown   # Markdown bullet list

Configuration File

Generate a config file template:

gem_changelog_diff init  # Creates .gem_changelog_diff.yml

The tool loads settings from two locations (project overrides user):

1. ~/.config/gem_changelog_diff/config.yml (user-level defaults)
2. .gem_changelog_diff.yml (project-level overrides)

Supported keys:

github_token: ghp_xxx
default_format: text       # text, json, markdown
cache_ttl: 86400           # seconds (default: 24 hours)
concurrency: 4
ignore_gems:
  - rake
  - bundler
no_color: false

CLI flags always take priority over config file values.

Back to top

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Back to top

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/eclectic-coding/gem_changelog_diff.

Back to top

License

The gem is available as open source under the terms of the MIT License.