git-pkgs 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ff2285e54475944f6c8a9cb98ae9f5efcb78ee0aa74dbea6d46553bbf71caa2
-  data.tar.gz: 81aee90f3e0b9f573e1f9e442dc4c487f07957c320d70ca24a809929248279a3
+  metadata.gz: 6152060237bbc1d9902da8e721bb23cfeaed46bbe2f5241e848aa0853d906710
+  data.tar.gz: 5eebb36bd3eed487a100ddc8d3ef4c88cb0cdb28734f777d6fbfbd267f87f43e
 SHA512:
-  metadata.gz: ffdcb5fe7cc217b105f10018ba24101131120fdfcc8305f3142fcc11f29e7f77114e95c0a2abbe661fcac3a74e4ea0662031dc6a997020225bdabcc9b6ab754b
-  data.tar.gz: 204dc587c61ccb128957910784ccab0cb84c667627dff1fb81d18a6b6779abc34cfff3a838f06146c954d1a50b9ac095a036a67c898d12699c530476b9b3d31c
+  metadata.gz: b2192d675dd23a3a2c69fc4de998070db17ac05004842855b1fbd1d5b5b148d8063db93db3d84e4e0bbcf42f5d33a173180f641e3309241f7d83e04615c5ba9a
+  data.tar.gz: cd7cfbe811f2a809ef428452708b18d1842ef2898d4b78c55e6373773b50546b215ec2dc43591ed4252d20595973ad060581dba72cc1400145068f55294655c4

data/CHANGELOG.md

@@ -1,4 +1,18 @@
-## [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
 

data/README.md

@@ -146,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:
@@ -167,8 +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 --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:
@@ -225,6 +228,17 @@ git pkgs tree --ecosystem=rubygems
 
 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
 
 ```bash
@@ -244,6 +258,16 @@ 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:
@@ -258,6 +282,27 @@ You can also install git hooks to update automatically after commits and merges:
 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:
@@ -283,6 +328,19 @@ jobs:
       - 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.

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 show].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,10 +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

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

@@ -6,6 +6,8 @@ module Git
   module Pkgs
     module Commands
       class History
+        include Output
+
         def initialize(args)
           @args = args
           @options = parse_options
@@ -15,11 +17,7 @@ module Git
           package_name = @args.shift
 
           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)
 
@@ -52,18 +50,15 @@ module Git
           end
 
           if changes.empty?
-            if package_name
-              puts "No history found for '#{package_name}'"
-            else
-              puts "No dependency changes found"
-            end
+            msg = package_name ? "No history found for '#{package_name}'" : "No dependency changes found"
+            empty_result msg
             return
           end
 
           if @options[:format] == "json"
             output_json(changes)
           else
-            output_text(changes, package_name)
+            paginate { output_text(changes, package_name) }
           end
         end
 
@@ -81,13 +76,13 @@ module Git
 
             case change.change_type
             when "added"
-              action = "Added"
+              action = Color.green("Added")
               version_info = change.requirement
             when "modified"
-              action = "Updated"
+              action = Color.yellow("Updated")
               version_info = "#{change.previous_requirement} -> #{change.requirement}"
             when "removed"
-              action = "Removed"
+              action = Color.red("Removed")
               version_info = change.requirement
             end
 
@@ -150,6 +145,10 @@ module Git
               options[:until] = 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
@@ -163,8 +162,7 @@ module Git
         def parse_time(str)
           Time.parse(str)
         rescue ArgumentError
-          $stderr.puts "Invalid date format: #{str}"
-          exit 1
+          error "Invalid date format: #{str}"
         end
       end
     end

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

@@ -4,6 +4,8 @@ module Git
   module Pkgs
     module Commands
       class Hooks
+        include Output
+
         HOOK_SCRIPT = <<~SCRIPT
           #!/bin/sh
           # git-pkgs auto-update hook