pretty-git 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e190585a91de27221e54bc2cbc58b5f6d26a1428c2e5cd5189ff0c18d362e6c
-  data.tar.gz: f8d2bc8f5d6c6a4887a745abd611a038166bcb54e95267a15d4868ee9d530003
+  metadata.gz: 7bd982eee724a56adcb2aa941fdecc2c95309c1bf681a5c3b9a1be0b8bf0306f
+  data.tar.gz: 1ef12cd144493563bbe99a869e81fe6aa9436136dc7aac52b713d5436975a48a
 SHA512:
-  metadata.gz: e11fd51d24ed1e63fd5c773f76a46510bbcedad23c02ace63b25d7d80c366479fd02fe2bfabaa58693389c222bafe4fd9e6fc0b157b7d598e96294a3f888fbef
-  data.tar.gz: 38fc87c6467d72ae6a1cb63a13b06c417e81f714d5b074feae961f121e061cea0733494020e0b8f562f36ea00b2d537a0d6fd5ac36eea942465680376f8eb71e
+  metadata.gz: fba3dc59a53571d80cf38e13a555b2ad62b44964f29039a1fe68000349f642d024bb854542d62d58608dd8f9a8169548b0444a0fc8488cccc9a8e3497ba68ade
+  data.tar.gz: 1f8037f3e7ef97e13b60be37c6d447c684586ffb78017d1905fc6b75d4d055ce533d4a87f04baf6e15fa734fa20fcbfe8854f5f4ef429c402106cbbf4a9a70b5

data/CHANGELOG.md

@@ -5,7 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
 
 ## [Unreleased]
- 
+### Added
+- Docs: `docs/testing.md` covering the golden workflow, snapshot update/validation; linked from `README.md`, `README.ru.md`, and `CONTRIBUTING.md`.
+- Tests: determinism invariants for YAML/XML renderers (stable output regardless of input order).
+
+### Changed
+- Completions: refreshed bash/zsh completions — added short flags `-f`/`-o`/`-l`, values for `--time-bucket` (`day|week|month`), and repo path completion as the 2nd positional argument.
+
+## [0.1.5] - 2025-08-17
+### Added
+- CLI: warn to stderr when `--theme`/`--no-color` are used with non-console `--format` values.
+- Docs: expanded Filters documentation (branches, authors, paths, time semantics, verbose diagnostics), schemas/examples pointers, performance and CI usage.
+- Tests: unit tests for `PrettyGit::Utils::TimeUtils`.
+
+### Changed
+- Internals: extracted time parsing/normalization to `PrettyGit::Utils::TimeUtils` and centralized verbose logging via `PrettyGit::Logger`. `Git::Provider` routes verbose messages through the centralized logger (stderr).
+- Verbose mode: documentation clarified to note that diagnostics are printed to stderr for easier CI parsing.
+
+### Deprecated
+- Filters: legacy `:until` keyword in `PrettyGit::Filters` initialization is accepted for backward compatibility and emits a deprecation warning; use `:until_at` instead.
+
+### Fixed
+- Filters: allow initialization via a single Hash argument (legacy call sites) while preserving `Struct` keyword semantics.
 
 ## [0.1.4] - 2025-08-17
 ### Added

data/README.md

@@ -58,6 +58,13 @@ Generator of rich reports for a local Git repository: summary, activity, authors
 * **Exports**: `console`, `json`, `csv`, `md`, `yaml`, `xml`.
 * **Output**: to stdout or file via `--out`.
 
+## ❓ Why Pretty Git
+* **One tool, many views**: activity, authorship, hotspots, languages, ownership — consistent UX and outputs.
+* **Deterministic results**: stable sorting and formatting make it reliable for CI and diffs.
+* **Format-first**: JSON/CSV/Markdown/YAML/XML out of the box with strict and documented rules.
+* **Fast enough for daily use**: streams `git log` and aggregates in-memory; tips below for large repos.
+* **Safe defaults**: sensible path and binary ignores for the `languages` report; colorized console output with themes.
+
 ## ⚙️ Requirements
 * **Ruby**: >= 3.4 (recommended 3.4.x)
 * **Git**: installed and available in `PATH`
@@ -142,12 +149,15 @@ Key options:
 * **--no-color** Disable colors in console
 * **--theme** `basic|bright|mono` — console theme (default `basic`; `mono` forces monochrome)
 * **--metric** `bytes|files|loc` — metric for `languages` report (default `bytes`)
+* **--verbose** Print debug information (effective git command, filters)
 
 Examples with multiple values:
 
 ```bash
-# Multiple branches
+# Multiple branches (treated as explicit revisions)
 pretty-git summary . --branch main --branch develop
+## This is equivalent to:
+## git log main develop -- ...
 
 # Filter authors (include/exclude)
 pretty-git authors . --author alice@example.com --exclude-author bot@company
@@ -157,7 +167,30 @@ pretty-git files . --path app,lib --exclude-path vendor,node_modules
 ```
 
 ### Filters
-Filters apply at commit fetch and later aggregation. Date format: ISO8601 or `YYYY-MM-DD`. If timezone is omitted — your local zone is assumed; output timestamps are normalized to UTC.
+Filters apply at commit fetch and later aggregation. Below — exact semantics and tips.
+
+#### Branches / revisions
+* `--branch BRANCH` may be provided multiple times.
+* Multiple branches are treated as explicit revisions to `git log` (no implicit merge-base range). Example: `--branch main --branch develop` → `git log main develop -- ...`.
+* If no branches are specified, the repository’s current `HEAD` is used.
+
+#### Authors
+* `--author` and `--exclude-author` accept name or email substrings (case-insensitive match by `git log`).
+* Multiple values may be provided by repeating the option.
+
+#### Paths
+* `--path` and `--exclude-path` accept comma-separated values or repeated options.
+* Globs are supported by git pathspec. Excludes are translated to `:(exclude)pattern` and applied consistently.
+* When only excludes are present, `.` is included to ensure the pathspec is valid (mirrors tests in `spec/pretty_git/git/provider_spec.rb`).
+
+#### Time period
+* `--since` / `--until`: ISO8601 (e.g. `2025-01-31T12:00:00Z`) or `YYYY-MM-DD`.
+* Date-only values are interpreted as UTC midnight to avoid timezone drift in different environments.
+* Time values are normalized to UTC in outputs.
+
+#### Verbose diagnostics
+* `--verbose` prints the effective `git log` command and active filters to stderr.
+* Useful for debugging filters, CI logs, or when reproducing results locally.
 
 ### Output format
 Set via `--format`. For file formats it’s recommended to use `--out`.
@@ -397,6 +430,13 @@ _Example terminal output (theme: basic)._
   {"report":"summary","generated_at":"2025-01-31T00:00:00Z","totals":{"commits":123}}
   ```
 
+## 🧾 Schemas and Examples
+Machine-readable examples and schemas live under `docs/export_schemas/` and `docs/examples/`.
+
+* **Schemas**: see `docs/export_schemas/README.md` for JSON and XML schema notes.
+* **Examples**: example payloads for JSON/XML for each report under `docs/examples/`.
+* Intended use: validation in CI, contract documentation, and integration tests.
+
 ### CSV
 * **Structure**: flat table, first line is header.
 * **Encoding**: UTF‑8 without BOM.
@@ -495,16 +535,46 @@ These lists mirror the implementation in `lib/pretty_git/analytics/languages.rb`
 ## 🔁 Determinism and Sorting
 Output is deterministic given the same input. Sorting for files/authors: by changes (desc), then by commits (desc), then by path/name (asc). Limits are applied after sorting; `all` or `0` means no limit.
 
+## ⚡ Performance Tips
+* Prefer narrowing by `--path`/`--exclude-path` and `--since/--until` on large repositories.
+* Use multiple `--branch` only when you explicitly want to include several heads; otherwise rely on current `HEAD`.
+* For CI, cache the repository and fetch shallow history if full history is unnecessary for your report.
+
+## 🤖 CI Usage
+Examples for common pipelines:
+
+```yaml
+# GitHub Actions (excerpt)
+jobs:
+  reports:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+      - run: gem install pretty-git
+      - run: pretty-git authors . --format json --out authors.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: authors-report
+          path: authors.json
+```
+
 ## 🪟 Windows Notes
-Primary targets — macOS/Linux. Windows is supported best‑effort:
-* Running via Git Bash/WSL is OK
-* Colors can be disabled by `--no-color`
-* Carefully quote arguments when working with paths
+Primary targets — macOS/Linux. Windows is supported best‑effort. See detailed notes in [docs/windows.md](docs/windows.md).
+
+Highlights:
+* Running via Git Bash/WSL is recommended.
+* CRLF output from git is handled by the parser; exports use UTF‑8 with LF.
+* Path filters are normalized to Unicode NFC when available; otherwise pass‑through.
+* Colors can be disabled by `--no-color` or `--theme mono`.
 
 ## 🩺 Diagnostics and Errors
 Typical issues and solutions:
 
 * **Unknown report/format** — check the first argument and `--format`.
+* **Debugging** — add `--verbose` to see the effective `git log` command and applied filters.
 * **Invalid date format** — use ISO8601 or `YYYY-MM-DD` (e.g., `2025-01-31` or `2025-01-31T12:00:00Z`).
 * **Git not available** — ensure `git` is installed and in the `PATH`.
 * **Empty result** — check your filters (`--since/--until`, `--branch`, `--path`); your selection might be too narrow.
@@ -527,5 +597,7 @@ bundle exec rubocop
 
 Style — RuboCop clean. Tests cover aggregators, renderers, CLI, and integration scenarios (determinism, format correctness).
 
+For detailed testing strategy, determinism rules, and golden tests workflow (how to run/update snapshots), see `docs/testing.md`.
+
 ## 📄 License
 MIT © Contributors

data/README.ru.md

@@ -20,6 +20,7 @@
 
 ## Содержание
 - [Возможности](#возможности)
+- [Почему Pretty Git](#почему-pretty-git)
 - [Требования](#требования)
 - [Установка](#установка)
 - [Быстрый старт](#быстрый-старт)
@@ -41,11 +42,14 @@
 - [Экспорт в форматы](#экспорт-в-форматы)
   - [Console](#console)
   - [JSON](#json)
+  - [Схемы и примеры](#схемы-и-примеры)
   - [CSV](#csv)
   - [Markdown](#markdown)
   - [YAML](#yaml)
   - [XML](#xml)
 - [Детерминизм и сортировка](#детерминизм-и-сортировка)
+- [Советы по производительности](#советы-по-производительности)
+- [Использование в CI](#использование-в-ci)
 - [Советы по Windows](#советы-по-windows)
 - [Диагностика и ошибки](#диагностика-и-ошибки)
 - [FAQ](#faq)
@@ -58,6 +62,13 @@
 * __Экспорт__: `console`, `json`, `csv`, `md`, `yaml`, `xml`.
 * __Вывод__: в stdout или файл через `--out`.
 
+## ❓ Почему Pretty Git
+* __Один инструмент — много представлений__: активность, авторство, риск, языки, владение — единый UX и форматы.
+* __Детерминированные результаты__: стабильные сортировки и форматирование — удобно для CI и диффов.
+* __Сразу форматы__: JSON/CSV/Markdown/YAML/XML из коробки с чёткими правилами.
+* __Достаточно быстро__: потоковый `git log` и ин‑мемори агрегации; советы для больших репозиториев ниже.
+* __Безопасные дефолты__: разумные игноры путей и бинарников для отчёта `languages`; цветной консольный вывод с темами.
+
 ## ⚙️ Требования
 * __Ruby__: >= 3.4 (рекомендуется 3.4.x)
 * __Git__: установлен и доступен в `PATH`
@@ -142,12 +153,15 @@ pretty-git <report> <repo_path> [options]
 * __--no-color__ Отключить цвета в консоли
 * __--theme__ `basic|bright|mono` — тема оформления консольного вывода (по умолчанию `basic`; `mono` принудительно отключает цвета)
 * __--metric__ `bytes|files|loc` — метрика для отчёта `languages` (по умолчанию `bytes`)
+* **--verbose** Печатать отладочную информацию (эффективная команда git, применённые фильтры)
 
 Примеры значений с несколькими параметрами:
 
 ```bash
-# Несколько веток
+# Несколько веток (трактуются как явные ревизии)
 pretty-git summary . --branch main --branch develop
+## Эквивалентно:
+## git log main develop -- ...
 
 # Фильтрация по авторам (включая/исключая)
 pretty-git authors . --author alice@example.com --exclude-author bot@company
@@ -157,7 +171,30 @@ pretty-git files . --path app,lib --exclude-path vendor,node_modules
 ```
 
 ### Фильтры
-Фильтры применяются на этапе выборки коммитов и последующей агрегации. Формат дат: ISO8601 или `YYYY-MM-DD`. Если часовой пояс не указан — используется локальная зона пользователя; на выводе время нормализуется к UTC.
+Фильтры применяются на этапе выборки коммитов и последующей агрегации. Ниже — точные правила и советы.
+
+#### Ветки / ревизии
+* `--branch BRANCH` можно указывать несколько раз.
+* Несколько веток трактуются как явные ревизии для `git log` (без неявного диапазона от merge-base). Пример: `--branch main --branch develop` → `git log main develop -- ...`.
+* Если ветки не указаны — используется текущий `HEAD` репозитория.
+
+#### Авторы
+* `--author` и `--exclude-author` принимают подстроки имени или email (регистронезависимо по логике `git log`).
+* Можно передавать несколько значений повтором опции.
+
+#### Пути
+* `--path` и `--exclude-path` принимают значения через запятую или повтором опции.
+* Поддерживаются glob‑маски git pathspec. Исключения переводятся в `:(exclude)pattern` и применяются последовательно.
+* Если заданы только исключения — автоматически добавляется `.` для корректного pathspec (как в тестах `spec/pretty_git/git/provider_spec.rb`).
+
+#### Период времени
+* `--since` / `--until`: ISO8601 (например, `2025-01-31T12:00:00Z`) или `YYYY-MM-DD`.
+* Даты без времени интерпретируются как полночь UTC, чтобы исключить сдвиги между средами.
+* На выводе время нормализуется к UTC.
+
+#### Подробная диагностика (verbose)
+* `--verbose` печатает эффективную команду `git log` и активные фильтры в stderr.
+* Полезно для отладки фильтров, логов CI и воспроизведения результатов локально.
 
 ### Формат вывода
 Задаётся через `--format`. Для файловых форматов рекомендуется использовать `--out`.
@@ -423,6 +460,13 @@ _Пример вывода в терминале (тема: basic)._
   {"report":"summary","generated_at":"2025-01-31T00:00:00Z","totals":{"commits":123}}
   ```
 
+## 🧾 Схемы и примеры
+Машиночитаемые примеры и схемы лежат в `docs/export_schemas/` и `docs/examples/`.
+
+* __Схемы__: смотрите `docs/export_schemas/README.md` с заметками по JSON и XML схемам.
+* __Примеры__: примеры нагрузок для JSON/XML по каждому отчёту — в `docs/examples/`.
+* Назначение: валидация в CI, документация контрактов и интеграционные тесты.
+
 ### CSV
 * __Структура__: плоская таблица, первая строка — заголовок.
 * __Кодировка__: UTF‑8, без BOM.
@@ -496,6 +540,32 @@ _Пример вывода в терминале (тема: basic)._
 ## 🔁 Детерминизм и сортировка
 Вывод детерминирован при одинаковых входных данных. Сортировка для файлов/авторов: по количеству изменений (desc), затем по числу коммитов (desc), затем по пути/имени (asc). Лимиты применяются поверх отсортированного списка; значение `all` или `0` означает отсутствие ограничения.
 
+## ⚡ Советы по производительности
+* На больших репозиториях сужайте выборку `--path/--exclude-path` и `--since/--until`.
+* Несколько `--branch` используйте, только если нужно включить несколько голов; иначе полагайтесь на текущий `HEAD`.
+* В CI кешируйте репозиторий и используйте shallow‑fetch, если полная история не нужна для выбранного отчёта.
+
+## 🤖 Использование в CI
+Пример для GitHub Actions:
+
+```yaml
+# GitHub Actions (фрагмент)
+jobs:
+  reports:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+      - run: gem install pretty-git
+      - run: pretty-git authors . --format json --out authors.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: authors-report
+          path: authors.json
+```
+
 ## 🪟 Советы по Windows
 Целевая платформа — macOS/Linux. Windows поддерживается в режиме best‑effort:
 * Запуск через Git Bash/WSL допустим
@@ -505,7 +575,8 @@ _Пример вывода в терминале (тема: basic)._
 ## 🩺 Диагностика и ошибки
 Типичные ошибки и решения:
 
-* __Неизвестный отчёт/формат__ — проверьте значение первого аргумента и `--format`.
+* **Неизвестный отчёт/формат** — проверьте первый аргумент и `--format`.
+* **Отладка** — добавьте `--verbose`, чтобы увидеть фактическую команду `git log` и применённые фильтры.
 * __Неверный формат даты__ — используйте ISO8601 или `YYYY-MM-DD` (например, `2025-01-31` или `2025-01-31T12:00:00Z`).
 * __Git недоступен__ — убедитесь, что `git` установлен и доступен в `PATH`.
 * __Пустой результат__ — проверьте фильтры (`--since/--until`, `--branch`, `--path`), возможно, выборка слишком узкая.
@@ -528,5 +599,7 @@ bundle exec rubocop
 
 Стиль — RuboCop без ошибок. Тесты покрывают агрегаторы, рендереры, CLI и интеграционные сценарии (детерминизм, корректность форматов).
 
+Подробнее о стратегии тестирования, правилах детерминизма и процессе работы с golden‑тестами (как запускать/обновлять снапшоты) см. `docs/testing.md`.
+
 ## 📄 Лицензия
 MIT © Contributors

data/lib/pretty_git/analytics/languages.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'time'
+require 'json'
+require 'find'
 
 module PrettyGit
   module Analytics
@@ -79,30 +81,46 @@ module PrettyGit
     # Default metric: bytes (similar to GitHub Linguist approach).
     # rubocop:disable Metrics/ClassLength
     class Languages
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       def self.call(_enum, filters)
         repo = filters.repo_path
-        items = calculate(repo, include_globs: filters.paths, exclude_globs: filters.exclude_paths)
+        prof = ENV['PG_PROF'] == '1'
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC) if prof
         metric = (filters.metric || 'bytes').to_s
+        items = calculate(repo, include_globs: filters.paths, exclude_globs: filters.exclude_paths, metric: metric)
         totals = compute_totals(items)
         items = add_percents(items, totals, metric)
         items = add_colors(items)
         items = sort_and_limit(items, filters.limit, metric)
 
-        build_result(repo, items, totals, metric)
+        res = build_result(repo, items, totals, metric)
+        if prof
+          t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          elapsed = (t1 - t0)
+          files = totals[:files]
+          warn format(
+            '[pg_prof] languages: time=%<sec>.3fs files=%<files>d metric=%<metric>s',
+            { sec: elapsed, files: files, metric: metric }
+          )
+          summary = { component: 'languages', time_sec: elapsed, files: files, metric: metric }
+          warn("[pg_prof_json] #{summary.to_json}")
+        end
+        res
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
       # rubocop:disable Metrics/AbcSize
-      def self.calculate(repo_path, include_globs:, exclude_globs:)
+      def self.calculate(repo_path, include_globs:, exclude_globs:, metric: 'bytes')
         by_lang = Hash.new { |h, k| h[k] = { bytes: 0, files: 0, loc: 0 } }
         Dir.chdir(repo_path) do
-          each_source_file(include_globs, exclude_globs) do |abs_path|
-            basename = File.basename(abs_path)
-            ext = File.extname(abs_path).downcase
+          each_source_file(include_globs, exclude_globs) do |path|
+            basename = File.basename(path)
+            ext = File.extname(path).downcase
             lang = FILENAME_TO_LANG[basename] || EXT_TO_LANG[ext]
             next unless lang
 
-            size = safe_file_size(abs_path)
-            lines = safe_count_lines(abs_path)
+            size = safe_file_size(path)
+            lines = metric == 'loc' ? safe_count_lines(path) : 0
             agg = by_lang[lang]
             agg[:bytes] += size
             agg[:files] += 1
@@ -113,14 +131,33 @@ module PrettyGit
       end
       # rubocop:enable Metrics/AbcSize
 
-      def self.each_source_file(include_globs, exclude_globs)
-        # Build list of files under repo respecting includes/excludes
-        all = Dir.glob('**/*', File::FNM_DOTMATCH).select { |p| File.file?(p) }
-        files = all.reject { |p| vendor_path?(p) || binary_ext?(p) }
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def self.each_source_file(include_globs, exclude_globs, &block)
+        # Traverse tree with early prune for vendor/binary paths, then apply include/exclude
+        files = []
+        Find.find('.') do |path|
+          rel = path.sub(%r{^\./}, '')
+          # Prune vendor dirs early
+          if File.directory?(path)
+            dir = File.basename(path)
+            if VENDOR_DIRS.include?(dir)
+              Find.prune
+              next
+            end
+            next
+          end
+          next unless File.file?(path)
+          next if rel.empty?
+          next if vendor_path?(rel) || binary_ext?(rel)
+
+          files << rel
+        end
+
         files = filter_includes(files, include_globs)
         files = filter_excludes(files, exclude_globs)
-        files.each { |rel| yield File.expand_path(rel) }
+        files.each { |rel| block.call(rel) }
       end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       def self.safe_file_size(path)
         File.size(path)
@@ -141,7 +178,8 @@ module PrettyGit
         return files if globs.empty?
 
         allowed = globs.flat_map { |g| Dir.glob(g) }
-        files.select { |f| allowed.include?(f) }
+        allowed_map = allowed.each_with_object({}) { |f, h| h[f] = true }
+        files.select { |f| allowed_map[f] }
       end
 
       def self.filter_excludes(files, globs)
@@ -149,7 +187,8 @@ module PrettyGit
         return files if globs.empty?
 
         blocked = globs.flat_map { |g| Dir.glob(g) }
-        files.reject { |f| blocked.include?(f) }
+        blocked_map = blocked.each_with_object({}) { |f, h| h[f] = true }
+        files.reject { |f| blocked_map[f] }
       end
 
       def self.vendor_path?(path)

data/lib/pretty_git/app.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'open3'
 require_relative 'git/provider'
 require_relative 'analytics/summary'
 require_relative 'analytics/activity'
@@ -37,7 +38,9 @@ module PrettyGit
     private
 
     def ensure_repo!(path)
-      return if File.directory?(File.join(path, '.git'))
+      # Use git to reliably detect work-trees/worktrees/bare repos
+      stdout, _stderr, status = Open3.capture3('git', 'rev-parse', '--is-inside-work-tree', chdir: path)
+      return if status.success? && stdout.to_s.strip == 'true'
 
       raise ArgumentError, "Not a git repository: #{path}"
     end
@@ -47,21 +50,25 @@ module PrettyGit
     end
 
     def renderer_for(filters, io)
-      case filters.format
-      when 'console'
-        use_color = !filters.no_color && filters.theme != 'mono'
-        Render::ConsoleRenderer.new(io: io, color: use_color, theme: filters.theme)
-      when 'csv'
-        Render::CsvRenderer.new(io: io)
-      when 'md'
-        Render::MarkdownRenderer.new(io: io)
-      when 'yaml'
-        Render::YamlRenderer.new(io: io)
-      when 'xml'
-        Render::XmlRenderer.new(io: io)
-      else
-        Render::JsonRenderer.new(io: io)
+      if filters.format == 'console'
+        return Render::ConsoleRenderer.new(
+          io: io,
+          color: !filters.no_color && filters.theme != 'mono',
+          theme: filters.theme
+        )
       end
+
+      dispatch = {
+        'csv' => Render::CsvRenderer,
+        'md' => Render::MarkdownRenderer,
+        'yaml' => Render::YamlRenderer,
+        'xml' => Render::XmlRenderer,
+        'json' => Render::JsonRenderer
+      }
+      klass = dispatch[filters.format]
+      raise ArgumentError, "Unknown format: #{filters.format}" unless klass
+
+      klass.new(io: io)
     end
 
     def analytics_for(report, enum, filters)

data/lib/pretty_git/cli.rb

@@ -9,9 +9,6 @@ require_relative 'cli_helpers'
 module PrettyGit
   # Command-line interface entry point.
   class CLI
-    SUPPORTED_REPORTS = %w[summary activity authors files heatmap languages hotspots churn ownership].freeze
-    SUPPORTED_FORMATS = %w[console json csv md yaml xml].freeze
-
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity
     def self.run(argv = ARGV, out: $stdout, err: $stderr)
       options = {
@@ -28,6 +25,7 @@ module PrettyGit
         out: nil,
         no_color: false,
         theme: 'basic',
+        _verbose: false,
         _version: false,
         _help: false
       }

data/lib/pretty_git/cli_helpers.rb

@@ -1,29 +1,71 @@
 # frozen_string_literal: true
 
 require 'optparse'
+require 'fileutils'
 require_relative 'filters'
 require_relative 'app'
+require_relative 'constants'
 
 module PrettyGit
   # Helpers extracted from `PrettyGit::CLI` to keep the CLI class small
   # and RuboCop-compliant. Provides parser configuration and execution utilities.
   # rubocop:disable Metrics/ModuleLength
   module CLIHelpers
-    REPORTS = %w[summary activity authors files heatmap languages hotspots churn ownership].freeze
-    FORMATS = %w[console json csv md yaml xml].freeze
-    METRICS = %w[bytes files loc].freeze
+    REPORTS = PrettyGit::Constants::REPORTS
+    FORMATS = PrettyGit::Constants::FORMATS
+    METRICS = PrettyGit::Constants::METRICS
+    THEMES  = PrettyGit::Constants::THEMES
 
     module_function
 
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def configure_parser(opts, options)
-      opts.banner = 'Usage: pretty-git [REPORT] [REPO] [options]'
+      opts.banner = <<~BANNER
+        Usage: pretty-git [REPORT] [REPO] [options]
+
+        Reports: #{REPORTS.join(', ')}
+        Formats: #{FORMATS.join(', ')}
+        Themes:  #{THEMES.join(', ')}
+      BANNER
+      opts.separator('')
+      opts.separator('Repository and branch:')
       add_repo_options(opts, options)
+      opts.separator('')
+      opts.separator('Time, authors, and bucketing:')
       add_time_author_options(opts, options)
+      opts.separator('')
+      opts.separator('Paths and limits:')
       add_path_limit_options(opts, options)
+      opts.separator('')
+      opts.separator('Format and output:')
       add_format_output_options(opts, options)
+      opts.separator('')
+      opts.separator('Metrics (languages report only):')
       add_metric_options(opts, options)
+      opts.separator('')
+      opts.separator('Other:')
       add_misc_options(opts, options)
+      opts.separator('')
+      opts.separator('Examples:')
+      opts.separator('  # Summary in JSON to stdout')
+      opts.separator('  $ pretty-git summary . --format json')
+      opts.separator('')
+      opts.separator('  # Authors since a date with a limit')
+      opts.separator('  $ pretty-git authors ~/repo --since 2025-01-01 --limit 20')
+      opts.separator('')
+      opts.separator('  # Files with includes/excludes (globs)')
+      opts.separator('  $ pretty-git files . --path app/**/*.rb --exclude-path spec/**')
+      opts.separator('')
+      opts.separator('  # Activity bucketed by week to Markdown file')
+      opts.separator('  $ pretty-git activity . --time-bucket week --format md --out out/report.md')
+      opts.separator('')
+      opts.separator('  # Languages by LOC to CSV (redirect to file)')
+      opts.separator('  $ pretty-git languages . --metric loc --format csv > langs.csv')
+      opts.separator('')
+      opts.separator('  # Hotspots on main with a higher limit to YAML')
+      opts.separator('  $ pretty-git hotspots . --branch main --limit 50 --format yaml')
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
     def add_repo_options(opts, options)
       opts.on('--repo PATH', 'Path to git repository (default: .)') { |val| options[:repo] = val }
@@ -47,8 +89,14 @@ module PrettyGit
     def add_format_output_options(opts, options)
       opts.on('--format FMT', 'console|json|csv|md|yaml|xml') { |val| options[:format] = val }
       opts.on('--out FILE', 'Output file path') { |val| options[:out] = val }
-      opts.on('--no-color', 'Disable colors in console output') { options[:no_color] = true }
-      opts.on('--theme NAME', 'console color theme: basic|bright|mono') { |val| options[:theme] = val }
+      opts.on('--no-color', 'Disable colors in console output') do
+        options[:no_color] = true
+        options[:_no_color_provided] = true
+      end
+      opts.on('--theme NAME', 'console color theme: basic|bright|mono') do |val|
+        options[:theme] = val
+        options[:_theme_provided] = true
+      end
     end
 
     def add_metric_options(opts, options)
@@ -60,6 +108,7 @@ module PrettyGit
     def add_misc_options(opts, options)
       opts.on('--version', 'Show version') { options[:_version] = true }
       opts.on('--help', 'Show help') { options[:_help] = true }
+      opts.on('--verbose', 'Verbose output (debug)') { options[:_verbose] = true }
     end
 
     def parse_limit(str)
@@ -75,9 +124,14 @@ module PrettyGit
       code = handle_version_help(options, parser, out)
       return code unless code.nil?
 
-      base_ok = valid_report?(options[:report]) && valid_theme?(options[:theme]) && valid_metric?(options[:metric])
+      base_ok = valid_base?(options)
       conflicts_ok = validate_conflicts(options, err)
-      return nil if base_ok && conflicts_ok
+      if base_ok && conflicts_ok
+        early = warn_ignores(options, err)
+        return 0 if early == :early_exit
+
+        return nil
+      end
 
       print_validation_errors(options, err)
       1
@@ -96,19 +150,47 @@ module PrettyGit
     end
 
     def valid_report?(report) = REPORTS.include?(report)
-    def valid_theme?(theme) = %w[basic bright mono].include?(theme)
+    def valid_theme?(theme) = THEMES.include?(theme)
+    def valid_format?(fmt) = FORMATS.include?(fmt)
+
+    def valid_base?(options)
+      valid_report?(options[:report]) &&
+        valid_theme?(options[:theme]) &&
+        valid_metric?(options[:metric]) &&
+        valid_format?(options[:format])
+    end
 
     def valid_metric?(metric)
       metric.nil? || METRICS.include?(metric)
     end
 
     def print_validation_errors(options, err)
-      supported = REPORTS.join(', ')
-      unless valid_report?(options[:report])
-        err.puts "Unknown report: #{options[:report]}."
-        err.puts "Supported: #{supported}"
-      end
-      err.puts "Unknown theme: #{options[:theme]}. Supported: basic, bright, mono" unless valid_theme?(options[:theme])
+      print_report_error(options, err)
+      print_theme_error(options, err)
+      print_format_error(options, err)
+      print_metric_error(options, err)
+    end
+
+    def print_report_error(options, err)
+      return if valid_report?(options[:report])
+
+      err.puts "Unknown report: #{options[:report]}."
+      err.puts "Supported: #{REPORTS.join(', ')}"
+    end
+
+    def print_theme_error(options, err)
+      return if valid_theme?(options[:theme])
+
+      err.puts "Unknown theme: #{options[:theme]}. Supported: #{THEMES.join(', ')}"
+    end
+
+    def print_format_error(options, err)
+      return if valid_format?(options[:format])
+
+      err.puts "Unknown format: #{options[:format]}. Supported: #{FORMATS.join(', ')}"
+    end
+
+    def print_metric_error(options, err)
       return if valid_metric?(options[:metric])
 
       err.puts "Unknown metric: #{options[:metric]}. Supported: #{METRICS.join(', ')}"
@@ -125,12 +207,45 @@ module PrettyGit
       ok
     end
 
+    # Print non-fatal warnings for flags that won't have effect with current options
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def warn_ignores(options, err)
+      return unless err
+
+      fmt = options[:format]
+      return unless fmt && fmt != 'console'
+
+      err.puts "Warning: --theme has no effect when --format=#{fmt}" if options[:theme]
+      err.puts "Warning: --no-color has no effect when --format=#{fmt}" if options[:no_color]
+
+      # Exit early only if user explicitly provided these console-only flags
+      # AND no other significant options that warrant running the app were provided.
+      return unless options[:_theme_provided] || options[:_no_color_provided]
+
+      significant = significant_options?(options)
+      :early_exit unless significant
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def significant_options?(options)
+      return true if options[:out]
+      return true if options[:metric]
+      return true if options[:time_bucket]
+      return true if options[:limit] && options[:limit] != 10
+
+      any_collection_present?(options, %i[branches authors exclude_authors paths exclude_paths])
+    end
+
+    def any_collection_present?(options, keys)
+      keys.any? { |k| options[k]&.any? }
+    end
+
     def build_filters(options)
       Filters.new(
         repo_path: options[:repo],
         branches: options[:branches],
         since: options[:since],
-        until: options[:until],
+        until_at: options[:until],
         authors: options[:authors],
         exclude_authors: options[:exclude_authors],
         paths: options[:paths],
@@ -141,14 +256,25 @@ module PrettyGit
         format: options[:format],
         out: options[:out],
         no_color: options[:no_color],
-        theme: options[:theme]
+        theme: options[:theme],
+        verbose: options[:_verbose]
       )
     end
 
     def execute(report, filters, options, out, err)
       if options[:out]
-        File.open(options[:out], 'w') do |f|
-          return PrettyGit::App.new.run(report, filters, out: f, err: err)
+        begin
+          dir = File.dirname(options[:out])
+          FileUtils.mkdir_p(dir) unless dir.nil? || dir == '.'
+          File.open(options[:out], 'w') do |f|
+            return PrettyGit::App.new.run(report, filters, out: f, err: err)
+          end
+        rescue Errno::EACCES
+          err.puts "Cannot write to: #{options[:out]} (permission denied)"
+          return 2
+        rescue Errno::ENOENT
+          err.puts "Cannot write to: #{options[:out]} (directory not found)"
+          return 2
         end
       end
 

data/lib/pretty_git/constants.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PrettyGit
+  module Constants
+    REPORTS = %w[
+      summary activity authors files heatmap languages hotspots churn ownership
+    ].freeze
+
+    FORMATS = %w[console json csv md yaml xml].freeze
+
+    METRICS = %w[bytes files loc].freeze
+
+    THEMES = %w[basic bright mono].freeze
+  end
+end

data/lib/pretty_git/filters.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 require 'time'
+require_relative 'utils/time_utils'
 
 module PrettyGit
   Filters = Struct.new(
     :repo_path,
     :branches,
     :since,
-    :until,
+    :until_at,
     :authors,
     :exclude_authors,
     :paths,
@@ -19,35 +20,53 @@ module PrettyGit
     :out,
     :no_color,
     :theme,
+    :verbose,
     keyword_init: true
   ) do
-    def since_iso8601
-      time_to_iso8601(since)
+    # Backward-compat: allow initializing with `until:` keyword by remapping to :until_at
+    # Preserve Struct keyword_init behavior by overriding initialize instead of .new
+    def initialize(*args, **kwargs)
+      # Accept a single Hash positional argument for backward compatibility
+      kwargs = args.first if (kwargs.nil? || kwargs.empty?) && args.length == 1 && args.first.is_a?(Hash)
+      kwargs ||= {}
+
+      if kwargs.key?(:until)
+        Kernel.warn('[pretty-git] DEPRECATION: Filters initialized with :until. Use :until_at instead.')
+        kwargs = kwargs.dup
+        kwargs[:until_at] = kwargs.delete(:until)
+      end
+
+      # Keyword-init struct: prefer keyword form consistently to keep initialize simple
+      super(**kwargs)
     end
 
-    def until_iso8601
-      time_to_iso8601(self[:until])
+    # Backward-compat: support filters.until and filters.until=
+    def until
+      self[:until_at]
+    end
+
+    def until=(val)
+      self[:until_at] = val
     end
 
-    private
+    # Backward-compat for hash-style access used in older specs
+    def [](key)
+      key = :until_at if key == :until
+      super
+    end
 
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-    def time_to_iso8601(val)
-      return nil if val.nil? || val.to_s.strip.empty?
+    def []=(key, value)
+      key = :until_at if key == :until
+      super
+    end
 
-      # If value is a date without time, interpret as UTC midnight to avoid
-      # timezone-dependent shifts across environments.
-      if val.is_a?(String) && val.match?(/^\d{4}-\d{2}-\d{2}$/)
-        y, m, d = val.split('-').map(&:to_i)
-        t = Time.new(y, m, d, 0, 0, 0, '+00:00')
-      else
-        # Otherwise parse normally and normalize to UTC.
-        t = val.is_a?(Time) ? val : Time.parse(val.to_s)
-      end
-      t.utc.iso8601
-    rescue ArgumentError
-      raise ArgumentError, "Invalid datetime: #{val} (expected ISO8601 or YYYY-MM-DD)"
+    def since_iso8601
+      PrettyGit::Utils::TimeUtils.to_utc_iso8601(since)
+    end
+
+    # Keep method name for backwards compatibility across the codebase
+    def until_iso8601
+      PrettyGit::Utils::TimeUtils.to_utc_iso8601(self[:until_at])
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
   end
 end

data/lib/pretty_git/git/provider.rb

@@ -2,7 +2,10 @@
 
 require 'open3'
 require 'time'
+require 'json'
 require_relative '../types'
+require_relative '../logger'
+require_relative '../utils/path_utils'
 
 module PrettyGit
   module Git
@@ -17,10 +20,18 @@ module PrettyGit
       end
 
       # Returns Enumerator of PrettyGit::Types::Commit
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/BlockLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def each_commit
         Enumerator.new do |yld|
+          prof = ENV['PG_PROF'] == '1'
+          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          headers = 0
+          numstat_lines = 0
           cmd = build_git_command
+          PrettyGit::Logger.verbose(
+            "[pretty-git] git cmd: #{cmd.join(' ')} (cwd=#{@filters.repo_path})",
+            @filters.verbose
+          )
           Open3.popen3(*cmd, chdir: @filters.repo_path) do |_stdin, stdout, stderr, wait_thr|
             current = nil
             stdout.each_line do |line|
@@ -28,6 +39,7 @@ module PrettyGit
               # Try to start a new commit from header on any line
               header = start_commit_from_header(line)
               if header
+                headers += 1 if prof
                 # emit previous commit if any
                 emit_current(yld, current)
                 current = header
@@ -36,6 +48,7 @@ module PrettyGit
 
               next if line.empty?
 
+              numstat_lines += 1 if prof
               append_numstat_line(current, line)
             end
 
@@ -47,9 +60,26 @@ module PrettyGit
               raise StandardError, (err && !err.empty? ? err : "git log failed with status #{status.exitstatus}")
             end
           end
+
+          t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if prof
+            # Emit a compact profile to stderr
+            elapsed = (t1 - t0)
+            warn format(
+              '[pg_prof] git_provider: time=%<sec>.3fs headers=%<headers>d numstat_lines=%<num>d',
+              { sec: elapsed, headers: headers, num: numstat_lines }
+            )
+            summary = {
+              component: 'git_provider',
+              time_sec: elapsed,
+              headers: headers,
+              numstat_lines: numstat_lines
+            }
+            warn("[pg_prof_json] #{summary.to_json}")
+          end
         end
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/BlockLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       private
 
@@ -73,10 +103,6 @@ module PrettyGit
         yld << commit
       end
 
-      def record_separator?(line)
-        line == SEP_RECORD
-      end
-
       def start_commit_from_header(line)
         sha, author_name, author_email, authored_at, subject = line.split(SEP_FIELD, 5)
         return nil unless subject
@@ -121,13 +147,13 @@ module PrettyGit
 
       def add_author_and_branch_filters(args)
         @filters.authors&.each { |a| args << "--author=#{a}" }
-        @filters.branches&.each { |b| args << "--branches=#{b}" }
+        # Treat branches as explicit revisions to include
+        @filters.branches&.each { |b| args << b }
       end
 
-      # rubocop:disable Metrics/AbcSize
       def add_path_filters(args)
-        path_args = Array(@filters.paths).compact
-        exclude_args = Array(@filters.exclude_paths).compact
+        path_args = PrettyGit::Utils::PathUtils.normalize_globs(@filters.paths)
+        exclude_args = PrettyGit::Utils::PathUtils.normalize_globs(@filters.exclude_paths)
 
         # Nothing to filter by
         return if path_args.empty? && exclude_args.empty?
@@ -137,15 +163,14 @@ module PrettyGit
         # If only excludes provided, include all paths first
         args << '.' if path_args.empty? && !exclude_args.empty?
 
-        # Include patterns as-is
+        # Include patterns (normalized)
         args.concat(path_args) unless path_args.empty?
 
-        # Exclude patterns via git pathspec magic with glob
+        # Exclude patterns via git pathspec magic with glob (normalized)
         exclude_args.each do |pat|
           args << ":(exclude,glob)#{pat}"
         end
       end
-      # rubocop:enable Metrics/AbcSize
 
       # rubocop:disable Metrics/CyclomaticComplexity
       def exclude_author?(name, email)

data/lib/pretty_git/logger.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PrettyGit
+  # Minimal centralized logger for PrettyGit.
+  # Writes to stderr by default; can accept custom IO via keyword.
+  module Logger
+    module_function
+
+    def warn(msg, err: $stderr)
+      err.puts(msg)
+    end
+
+    # Convenience: only emit when enabled is truthy
+    def verbose(msg, enabled, err: $stderr)
+      return unless enabled
+
+      warn(msg, err: err)
+    end
+  end
+end

data/lib/pretty_git/utils/path_utils.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PrettyGit
+  module Utils
+    # Utilities for path/glob normalization and handling cross-platform quirks.
+    module PathUtils
+      module_function
+
+      # Normalize a string path or glob to Unicode NFC form.
+      # Returns nil if input is nil.
+      def normalize_nfc(str)
+        return nil if str.nil?
+
+        s = str.to_s
+        # Only normalize if supported in this Ruby build; otherwise return as-is
+        if s.respond_to?(:unicode_normalize)
+          s.unicode_normalize(:nfc)
+        else
+          s
+        end
+      end
+
+      # Normalize each entry in an Array-like collection to NFC and compact
+      # nils. Returns an Array.
+      def normalize_globs(collection)
+        Array(collection).compact.map { |p| normalize_nfc(p) }
+      end
+    end
+  end
+end

data/lib/pretty_git/utils/time_utils.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module PrettyGit
+  module Utils
+    # Utilities for time parsing and ISO8601 normalization used by filters.
+    module TimeUtils
+      module_function
+
+      # Converts various time inputs to ISO8601 in UTC.
+      # Accepts Time, String(ISO8601), or String(YYYY-MM-DD) treated as UTC midnight.
+      # Returns nil for nil/blank input. Raises ArgumentError for invalid values.
+      def to_utc_iso8601(val)
+        return nil if val.nil? || val.to_s.strip.empty?
+
+        parse_to_time(val).utc.iso8601
+      rescue ArgumentError
+        raise ArgumentError, "Invalid datetime: #{val} (expected ISO8601 or YYYY-MM-DD)"
+      end
+
+      def parse_to_time(val)
+        return val if val.is_a?(Time)
+        return parse_date_only(val) if val.is_a?(String) && date_only?(val)
+
+        Time.parse(val.to_s)
+      end
+
+      def parse_date_only(str)
+        y, m, d = str.split('-').map(&:to_i)
+        Time.new(y, m, d, 0, 0, 0, '+00:00')
+      end
+
+      def date_only?(str)
+        !!(str =~ /^\d{4}-\d{2}-\d{2}$/)
+      end
+    end
+  end
+end

data/lib/pretty_git/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PrettyGit
-  VERSION = '0.1.4'
+  VERSION = '0.1.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pretty-git
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Pretty Git Authors
@@ -74,8 +74,10 @@ files:
 - lib/pretty_git/app.rb
 - lib/pretty_git/cli.rb
 - lib/pretty_git/cli_helpers.rb
+- lib/pretty_git/constants.rb
 - lib/pretty_git/filters.rb
 - lib/pretty_git/git/provider.rb
+- lib/pretty_git/logger.rb
 - lib/pretty_git/render/console_renderer.rb
 - lib/pretty_git/render/csv_renderer.rb
 - lib/pretty_git/render/json_renderer.rb
@@ -85,6 +87,8 @@ files:
 - lib/pretty_git/render/xml_renderer.rb
 - lib/pretty_git/render/yaml_renderer.rb
 - lib/pretty_git/types.rb
+- lib/pretty_git/utils/path_utils.rb
+- lib/pretty_git/utils/time_utils.rb
 - lib/pretty_git/version.rb
 homepage: https://github.com/MikoMikocchi/pretty-git
 licenses: