git-pkgs 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ab0df1352b215987b6611a997fc62aa1e2a3ea05abe597c134812f9ec17d9d7
-  data.tar.gz: 5e929d2ebe9f2538d8d6b29ffc6ac89c7164f2d82afc898954159ae1a4a09ca9
+  metadata.gz: 6152060237bbc1d9902da8e721bb23cfeaed46bbe2f5241e848aa0853d906710
+  data.tar.gz: 5eebb36bd3eed487a100ddc8d3ef4c88cb0cdb28734f777d6fbfbd267f87f43e
 SHA512:
-  metadata.gz: 8e8eb54a1557bd2fa965fae8dfc2d2cceca578bec650a95821abef16f19ba2d6d6ab7c88a092cddca87de0b111fa9dd526a76439555144a8638f8507201b552e
-  data.tar.gz: 288792ce23dc723dcf61d37606cbe26cd89f33052687156d5ae032885c8e963647d972c7b772d4712da03aab024be61eb313992a213bff88d7c02c826937c5a9
+  metadata.gz: b2192d675dd23a3a2c69fc4de998070db17ac05004842855b1fbd1d5b5b148d8063db93db3d84e4e0bbcf42f5d33a173180f641e3309241f7d83e04615c5ba9a
+  data.tar.gz: cd7cfbe811f2a809ef428452708b18d1842ef2898d4b78c55e6373773b50546b215ec2dc43591ed4252d20595973ad060581dba72cc1400145068f55294655c4

data/CHANGELOG.md

@@ -1,4 +1,25 @@
-## [Unreleased]
+## [0.3.0] - 2026-01-03
+
+- Pager support for long output (respects `GIT_PAGER`, `core.pager`, `PAGER`)
+- `--no-pager` option for commands with long output
+- Colored output (respects `NO_COLOR`, `color.ui`, `color.pkgs`)
+- `GIT_DIR` and `GIT_PKGS_DB` environment variable support
+- `git pkgs stats` now supports `--since` and `--until` date filters
+- Consistent error handling across all commands (JSON errors when `--format=json`)
+- `git pkgs update` now uses a transaction for atomicity and better performance
+- Renamed `git pkgs outdated` to `git pkgs stale` (outdated remains as alias)
+- `git pkgs log` command to list commits with dependency changes
+- `git pkgs schema` command to output database schema in text, SQL, JSON, or markdown
+- `git pkgs praise` alias for `blame`
+- `git pkgs upgrade` command to handle schema upgrades after updating git-pkgs
+- Schema version tracking with automatic detection of outdated databases
+
+## [0.2.0] - 2026-01-02
+
+- `git pkgs show` command to display dependency changes in a single commit
+- `git pkgs history` now supports `--author`, `--since`, and `--until` filters
+- `git pkgs stats --by-author` shows who added the most dependencies
+- `git pkgs stats --ecosystem=X` filters statistics by ecosystem
 
 ## [0.1.1] - 2026-01-01
 

data/README.md

@@ -4,11 +4,9 @@ A git subcommand for tracking package dependencies across git history. Analyzes
 
 ## Why this exists
 
-Your lockfile shows what dependencies you have. It doesn't show how you got here. `git log Gemfile.lock` is useless noise.
+Your lockfile shows what dependencies you have, but it doesn't show how you got here, and `git log Gemfile.lock` is useless noise. git-pkgs indexes your dependency history into a queryable database so you can ask questions like: when did we add this? who added it? what changed between these two releases? has anyone touched this in the last year?
 
-git-pkgs indexes your dependency history into a queryable database. You can ask: when did we add this? who added it? what changed between these two releases? has anyone touched this in the last year?
-
-It works across ecosystems. Gemfile, package.json, Dockerfile, GitHub Actions workflows - one unified history instead of separate tools per ecosystem.
+It works across many ecosystems (Gemfile, package.json, Dockerfile, GitHub Actions workflows) giving you one unified history instead of separate tools per ecosystem. Everything runs locally and offline with no external services or network calls, and the database lives in your `.git` directory where you can use it in CI to catch dependency changes in pull requests.
 
 ## Installation
 
@@ -113,8 +111,11 @@ Gemfile (rubygems):
 ### View dependency history
 
 ```bash
-git pkgs history          # all dependency changes
-git pkgs history rails    # changes for a specific package
+git pkgs history                       # all dependency changes
+git pkgs history rails                 # changes for a specific package
+git pkgs history --author=alice        # filter by author
+git pkgs history --since=2024-01-01    # changes after date
+git pkgs history --ecosystem=rubygems  # filter by ecosystem
 ```
 
 Shows when packages were added, updated, or removed:
@@ -145,6 +146,7 @@ Show who added each current dependency:
 ```bash
 git pkgs blame
 git pkgs blame --ecosystem=rubygems
+git pkgs praise  # alias for blame
 ```
 
 Example output:
@@ -166,6 +168,10 @@ Gemfile (rubygems):
 
 ```bash
 git pkgs stats
+git pkgs stats --by-author         # who added the most dependencies
+git pkgs stats --ecosystem=npm     # filter by ecosystem
+git pkgs stats --since=2024-01-01  # changes after date
+git pkgs stats --until=2024-12-31  # changes before date
 ```
 
 Example output:
@@ -211,7 +217,7 @@ Manifest Files
 git pkgs why rails
 ```
 
-Shows the commit that added the dependency with author and message.
+This shows the commit that added the dependency along with the author and message.
 
 ### Dependency tree
 
@@ -220,7 +226,18 @@ git pkgs tree
 git pkgs tree --ecosystem=rubygems
 ```
 
-Shows dependencies grouped by type (runtime, development, etc).
+This shows dependencies grouped by type (runtime, development, etc).
+
+### Find stale dependencies
+
+```bash
+git pkgs stale                  # list deps by how long since last touched
+git pkgs stale --days=365       # only show deps untouched for a year
+git pkgs stale --ecosystem=npm  # filter by ecosystem
+git pkgs outdated               # alias for stale
+```
+
+Shows dependencies sorted by how long since they were last changed in your repo. Useful for finding packages that may have been forgotten or need review.
 
 ### Diff between commits
 
@@ -229,20 +246,101 @@ git pkgs diff --from=abc123 --to=def456
 git pkgs diff --from=HEAD~10
 ```
 
-Shows added, removed, and modified packages with version info.
+This shows added, removed, and modified packages with version info.
+
+### Show changes in a commit
+
+```bash
+git pkgs show              # show dependency changes in HEAD
+git pkgs show abc123       # specific commit
+git pkgs show HEAD~5       # relative ref
+```
+
+Like `git show` but for dependencies. Shows what was added, modified, or removed in a single commit.
+
+### List commits with dependency changes
+
+```bash
+git pkgs log                  # recent commits with dependency changes
+git pkgs log --author=alice   # filter by author
+git pkgs log -n 50            # show more commits
+```
+
+Like `git log` but only shows commits that changed dependencies, with the changes listed under each commit.
 
 ### Keep database updated
 
+After the initial analysis, you can incrementally update the database with new commits:
+
 ```bash
 git pkgs update
 ```
 
-Or install git hooks to update automatically after commits and merges:
+You can also install git hooks to update automatically after commits and merges:
 
 ```bash
 git pkgs hooks --install
 ```
 
+### Upgrading
+
+After updating git-pkgs, you may need to rebuild the database if the schema has changed:
+
+```bash
+git pkgs upgrade
+```
+
+This is detected automatically and you'll see a message if an upgrade is needed.
+
+### Show database schema
+
+```bash
+git pkgs schema                   # human-readable table format
+git pkgs schema --format=sql      # CREATE TABLE statements
+git pkgs schema --format=json     # JSON structure
+git pkgs schema --format=markdown # markdown tables
+```
+
+Useful for understanding the [database structure](docs/schema.md) or generating documentation.
+
+### CI usage
+
+You can run git-pkgs in CI to show dependency changes in pull requests:
+
+```yaml
+# .github/workflows/deps.yml
+name: Dependencies
+
+on: pull_request
+
+jobs:
+  diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+      - run: gem install git-pkgs
+      - run: git pkgs init
+      - run: git pkgs diff --from=origin/${{ github.base_ref }} --to=HEAD
+```
+
+## Configuration
+
+git-pkgs respects [standard git configuration](https://git-scm.com/docs/git-config).
+
+**Colors** are enabled when writing to a terminal. Disable with `NO_COLOR=1`, `git config color.ui never`, or `git config color.pkgs never` for git-pkgs only.
+
+**Pager** follows git's precedence: `GIT_PAGER` env, `core.pager` config, `PAGER` env, then `less -FRSX`. Use `--no-pager` flag or `git config core.pager cat` to disable.
+
+**Environment variables:**
+
+- `GIT_DIR` - git directory location (standard git variable)
+- `GIT_PKGS_DB` - database path (default: `.git/pkgs.sqlite3`)
+
 ## Performance
 
 Benchmarked on a MacBook Pro analyzing [octobox](https://github.com/octobox/octobox) (5191 commits, 8 years of history): init takes about 18 seconds at roughly 300 commits/sec, producing an 8.3 MB database. About half the commits (2531) had dependency changes.
@@ -271,6 +369,21 @@ The database schema stores:
 
 See [docs/schema.md](docs/schema.md) for full schema documentation.
 
+Since the database is just SQLite, you can query it directly for ad-hoc analysis:
+
+```bash
+sqlite3 .git/pkgs.sqlite3 "
+  -- who added the most dependencies?
+  SELECT c.author_name, COUNT(*) as deps_added
+  FROM dependency_changes dc
+  JOIN commits c ON dc.commit_id = c.id
+  WHERE dc.change_type = 'added'
+  GROUP BY c.author_name
+  ORDER BY deps_added DESC
+  LIMIT 10;
+"
+```
+
 ## Development
 
 ```bash

data/lib/git/pkgs/cli.rb

@@ -5,7 +5,8 @@ require "optparse"
 module Git
   module Pkgs
     class CLI
-      COMMANDS = %w[init update hooks info list tree history search why blame outdated stats diff branch].freeze
+      COMMANDS = %w[init update hooks info list tree history search why blame stale stats diff branch show log upgrade schema].freeze
+      ALIASES = { "praise" => "blame", "outdated" => "stale" }.freeze
 
       def self.run(args)
         new(args).run
@@ -24,7 +25,7 @@ module Git
           print_help
         when "-v", "--version", "version"
           puts "git-pkgs #{Git::Pkgs::VERSION}"
-        when *COMMANDS
+        when *COMMANDS, *ALIASES.keys
           run_command(command)
         else
           $stderr.puts "Unknown command: #{command}"
@@ -34,6 +35,7 @@ module Git
       end
 
       def run_command(command)
+        command = ALIASES.fetch(command, command)
         command_class = Commands.const_get(command.capitalize.gsub(/_([a-z])/) { $1.upcase })
         command_class.new(@args).run
       rescue NameError
@@ -57,9 +59,13 @@ module Git
             search    Find a dependency across all history
             why       Explain why a dependency exists
             blame     Show who added each dependency
-            outdated  Show dependencies that haven't been updated
+            stale     Show dependencies that haven't been updated
             stats     Show dependency statistics
             diff      Show dependency changes between commits
+            show      Show dependency changes in a commit
+            log       List commits with dependency changes
+            upgrade   Upgrade database after git-pkgs update
+            schema    Show database schema
 
           Options:
             -h, --help     Show this help message

data/lib/git/pkgs/color.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Git
+  module Pkgs
+    module Color
+      CODES = {
+        red: 31,
+        green: 32,
+        yellow: 33,
+        blue: 34,
+        magenta: 35,
+        cyan: 36,
+        bold: 1,
+        dim: 2
+      }.freeze
+
+      def self.enabled?
+        return @enabled if defined?(@enabled)
+
+        @enabled = determine_color_support
+      end
+
+      def self.enabled=(value)
+        @enabled = value
+      end
+
+      def self.reset!
+        remove_instance_variable(:@enabled) if defined?(@enabled)
+      end
+
+      def self.determine_color_support
+        # NO_COLOR takes precedence (https://no-color.org/)
+        return false if ENV["NO_COLOR"] && !ENV["NO_COLOR"].empty?
+        return false if ENV["TERM"] == "dumb"
+
+        # Check git config: color.pkgs takes precedence over color.ui
+        git_color = git_color_config
+        case git_color
+        when "always" then return true
+        when "never" then return false
+        # "auto" falls through to TTY check
+        end
+
+        $stdout.respond_to?(:tty?) && $stdout.tty?
+      end
+
+      def self.git_color_config
+        # color.pkgs overrides color.ui for git-pkgs specific control
+        pkgs_color = `git config --get color.pkgs 2>/dev/null`.chomp
+        return normalize_color_value(pkgs_color) unless pkgs_color.empty?
+
+        ui_color = `git config --get color.ui 2>/dev/null`.chomp
+        return normalize_color_value(ui_color) unless ui_color.empty?
+
+        "auto"
+      end
+
+      def self.normalize_color_value(value)
+        case value.downcase
+        when "true", "always" then "always"
+        when "false", "never" then "never"
+        else "auto"
+        end
+      end
+
+      def self.colorize(text, *codes)
+        return text unless enabled?
+
+        code_str = codes.map { |c| CODES[c] || c }.join(";")
+        "\e[#{code_str}m#{text}\e[0m"
+      end
+
+      def self.red(text)     = colorize(text, :red)
+      def self.green(text)   = colorize(text, :green)
+      def self.yellow(text)  = colorize(text, :yellow)
+      def self.blue(text)    = colorize(text, :blue)
+      def self.cyan(text)    = colorize(text, :cyan)
+      def self.bold(text)    = colorize(text, :bold)
+      def self.dim(text)     = colorize(text, :dim)
+    end
+  end
+end

data/lib/git/pkgs/commands/blame.rb

@@ -4,6 +4,8 @@ module Git
   module Pkgs
     module Commands
       class Blame
+        include Output
+
         def initialize(args)
           @args = args
           @options = parse_options
@@ -11,11 +13,7 @@ module Git
 
         def run
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
@@ -23,10 +21,7 @@ module Git
           branch_name = @options[:branch] || repo.default_branch
           branch = Models::Branch.find_by(name: branch_name)
 
-          unless branch&.last_analyzed_sha
-            $stderr.puts "No analysis found for branch '#{branch_name}'"
-            exit 1
-          end
+          error "No analysis found for branch '#{branch_name}'" unless branch&.last_analyzed_sha
 
           current_commit = Models::Commit.find_by(sha: branch.last_analyzed_sha)
           snapshots = current_commit&.dependency_snapshots&.includes(:manifest) || []
@@ -36,7 +31,7 @@ module Git
           end
 
           if snapshots.empty?
-            puts "No dependencies found"
+            empty_result "No dependencies found"
             return
           end
 
@@ -74,20 +69,24 @@ module Git
             end
             puts JSON.pretty_generate(json_data)
           else
-            grouped = blame_data.group_by { |d| [d[:manifest], d[:ecosystem]] }
+            paginate { output_text(blame_data) }
+          end
+        end
+
+        def output_text(blame_data)
+          grouped = blame_data.group_by { |d| [d[:manifest], d[:ecosystem]] }
 
-            grouped.each do |(manifest, ecosystem), deps|
-              puts "#{manifest} (#{ecosystem}):"
+          grouped.each do |(manifest, ecosystem), deps|
+            puts "#{manifest} (#{ecosystem}):"
 
-              max_name_len = deps.map { |d| d[:name].length }.max
-              max_author_len = deps.map { |d| d[:author].length }.max
+            max_name_len = deps.map { |d| d[:name].length }.max
+            max_author_len = deps.map { |d| d[:author].length }.max
 
-              deps.sort_by { |d| d[:name] }.each do |dep|
-                date = dep[:date].strftime("%Y-%m-%d")
-                puts "  #{dep[:name].ljust(max_name_len)}  #{dep[:author].ljust(max_author_len)}  #{date}  #{dep[:sha]}"
-              end
-              puts
+            deps.sort_by { |d| d[:name] }.each do |dep|
+              date = dep[:date].strftime("%Y-%m-%d")
+              puts "  #{dep[:name].ljust(max_name_len)}  #{dep[:author].ljust(max_author_len)}  #{date}  #{dep[:sha]}"
             end
+            puts
           end
         end
 
@@ -127,6 +126,10 @@ module Git
               options[:format] = v
             end
 
+            opts.on("--no-pager", "Do not pipe output into a pager") do
+              options[:no_pager] = true
+            end
+
             opts.on("-h", "--help", "Show this help") do
               puts opts
               exit

data/lib/git/pkgs/commands/branch.rb

@@ -4,6 +4,8 @@ module Git
   module Pkgs
     module Commands
       class Branch
+        include Output
+
         BATCH_SIZE = 100
         SNAPSHOT_INTERVAL = 20
 
@@ -25,32 +27,20 @@ module Git
           when nil, "-h", "--help"
             print_help
           else
-            $stderr.puts "Unknown subcommand: #{subcommand}"
-            $stderr.puts "Run 'git pkgs branch --help' for usage"
-            exit 1
+            error "Unknown subcommand: #{subcommand}. Run 'git pkgs branch --help' for usage"
           end
         end
 
         def add_branch
           branch_name = @args.shift
-          unless branch_name
-            $stderr.puts "Usage: git pkgs branch add <name>"
-            exit 1
-          end
+          error "Usage: git pkgs branch add <name>" unless branch_name
 
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
-          unless repo.branch_exists?(branch_name)
-            $stderr.puts "Branch '#{branch_name}' not found"
-            exit 1
-          end
+          error "Branch '#{branch_name}' not found" unless repo.branch_exists?(branch_name)
 
           existing = Models::Branch.find_by(name: branch_name)
           if existing
@@ -84,18 +74,14 @@ module Git
 
         def list_branches
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
           branches = Models::Branch.all
 
           if branches.empty?
-            puts "No branches tracked"
+            empty_result "No branches tracked"
             return
           end
 
@@ -110,25 +96,15 @@ module Git
 
         def remove_branch
           branch_name = @args.shift
-          unless branch_name
-            $stderr.puts "Usage: git pkgs branch remove <name>"
-            exit 1
-          end
+          error "Usage: git pkgs branch remove <name>" unless branch_name
 
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
           branch = Models::Branch.find_by(name: branch_name)
-          unless branch
-            $stderr.puts "Branch '#{branch_name}' not tracked"
-            exit 1
-          end
+          error "Branch '#{branch_name}' not tracked" unless branch
 
           # Only delete branch_commits, keep shared commits
           count = branch.branch_commits.count

data/lib/git/pkgs/commands/diff.rb

@@ -4,6 +4,8 @@ module Git
   module Pkgs
     module Commands
       class Diff
+        include Output
+
         def initialize(args)
           @args = args
           @options = parse_options
@@ -11,48 +13,27 @@ module Git
 
         def run
           repo = Repository.new
-
-          unless Database.exists?(repo.git_dir)
-            $stderr.puts "Database not initialized. Run 'git pkgs init' first."
-            exit 1
-          end
+          require_database(repo)
 
           Database.connect(repo.git_dir)
 
           from_ref = @options[:from]
           to_ref = @options[:to] || "HEAD"
 
-          unless from_ref
-            $stderr.puts "Usage: git pkgs diff --from=REF [--to=REF]"
-            exit 1
-          end
+          error "Usage: git pkgs diff --from=REF [--to=REF]" unless from_ref
 
           # Resolve git refs (like HEAD~10) to SHAs
           from_sha = repo.rev_parse(from_ref)
           to_sha = repo.rev_parse(to_ref)
 
-          unless from_sha
-            $stderr.puts "Could not resolve '#{from_ref}'"
-            exit 1
-          end
-
-          unless to_sha
-            $stderr.puts "Could not resolve '#{to_ref}'"
-            exit 1
-          end
+          error "Could not resolve '#{from_ref}'" unless from_sha
+          error "Could not resolve '#{to_ref}'" unless to_sha
 
           from_commit = find_or_create_commit(repo, from_sha)
           to_commit = find_or_create_commit(repo, to_sha)
 
-          unless from_commit
-            $stderr.puts "Commit '#{from_sha[0..7]}' not found"
-            exit 1
-          end
-
-          unless to_commit
-            $stderr.puts "Commit '#{to_sha[0..7]}' not found"
-            exit 1
-          end
+          error "Commit '#{from_sha[0..7]}' not found" unless from_commit
+          error "Commit '#{to_sha[0..7]}' not found" unless to_commit
 
           # Get all changes between the two commits
           changes = Models::DependencyChange
@@ -67,10 +48,14 @@ module Git
           end
 
           if changes.empty?
-            puts "No dependency changes between #{from_commit.short_sha} and #{to_commit.short_sha}"
+            empty_result "No dependency changes between #{from_commit.short_sha} and #{to_commit.short_sha}"
             return
           end
 
+          paginate { output_text(from_commit, to_commit, changes) }
+        end
+
+        def output_text(from_commit, to_commit, changes)
           puts "Dependency changes from #{from_commit.short_sha} to #{to_commit.short_sha}:"
           puts
 
@@ -79,35 +64,38 @@ module Git
           removed = changes.select { |c| c.change_type == "removed" }
 
           if added.any?
-            puts "Added:"
+            puts Color.green("Added:")
             added.group_by(&:name).each do |name, pkg_changes|
               latest = pkg_changes.last
-              puts "  + #{name} #{latest.requirement} (#{latest.manifest.path})"
+              puts Color.green("  + #{name} #{latest.requirement} (#{latest.manifest.path})")
             end
             puts
           end
 
           if modified.any?
-            puts "Modified:"
+            puts Color.yellow("Modified:")
             modified.group_by(&:name).each do |name, pkg_changes|
               first = pkg_changes.first
               latest = pkg_changes.last
-              puts "  ~ #{name} #{first.previous_requirement} -> #{latest.requirement}"
+              puts Color.yellow("  ~ #{name} #{first.previous_requirement} -> #{latest.requirement}")
             end
             puts
           end
 
           if removed.any?
-            puts "Removed:"
+            puts Color.red("Removed:")
             removed.group_by(&:name).each do |name, pkg_changes|
               latest = pkg_changes.last
-              puts "  - #{name} (was #{latest.requirement})"
+              puts Color.red("  - #{name} (was #{latest.requirement})")
             end
             puts
           end
 
           # Summary
-          puts "Summary: +#{added.map(&:name).uniq.count} -#{removed.map(&:name).uniq.count} ~#{modified.map(&:name).uniq.count}"
+          added_count = Color.green("+#{added.map(&:name).uniq.count}")
+          removed_count = Color.red("-#{removed.map(&:name).uniq.count}")
+          modified_count = Color.yellow("~#{modified.map(&:name).uniq.count}")
+          puts "Summary: #{added_count} #{removed_count} #{modified_count}"
         end
 
         def find_or_create_commit(repo, sha)
@@ -149,6 +137,10 @@ module Git
               options[:ecosystem] = v
             end
 
+            opts.on("--no-pager", "Do not pipe output into a pager") do
+              options[:no_pager] = true
+            end
+
             opts.on("-h", "--help", "Show this help") do
               puts opts
               exit