git-pandas 2.6.0__tar.gz → 2.7.0__tar.gz

git_pandas-2.7.0/.obvious/codebase-map.md

@@ -0,0 +1,18 @@
+# git-pandas — Codebase Map
+
+Folder-level overview (depth 2). `wdm0006/git-pandas`, default branch `master`, library v2.5.0.
+
+| Path | What it is |
+|---|---|
+| `gitpandas/` | The library package. `repository.py` (~3.1k lines) — `Repository` class: single-repo metrics (commit history, blame, cumulative blame, bus factor, hours estimate, rev-to-rev, cache warming, remote fetch). `project.py` (~1.6k lines) — `ProjectDirectory` (multi-repo discovery + aggregation) and `GitHubProfile`. `cache.py` (~860 lines) — `EphemeralCache`, `DiskCache`, `RedisDFCache` + the `_string_handle_to_df` memoization decorator every metric goes through. `logging.py` — verbose-mode logger. |
+| `gitpandas/utilities/` | `plotting.py` — chart helpers (punchcard, lifeline, cumulative blame); `check_api.py` — API-parity checker (CONTRIBUTING asks for Repository/ProjectDirectory parity). |
+| `tests/` | pytest suite. `test_Repository/`, `test_Project/`, `test_utilities/` mirror the package; root-level files cover cache behavior (immutability, threading, warming, key consistency, management), remote fetch, MCP serialization (mocks the `mcp` import — runs without mcp installed), logging, examples smoke (`test_examples.py`, marked `slow`). `conftest.py` builds throwaway git repos in tmp dirs. |
+| `examples/` | One runnable script per analysis (commit_history, bus_analysis, cumulative_blame, punchcard, …). Run from repo root: `make run-example example=<name>`. `definitions.py` locates the git-pandas checkout for self-analysis. |
+| `mcp_server/` | FastMCP **stdio** server exposing gitpandas metrics as MCP tools. Own README. Needs `mcp[cli]<2` + uvicorn (PEP 723 block, not in extras). |
+| `docs/` | Sphinx docs with their own `Makefile` and `requirements.txt`. |
+| `.github/workflows/` | `test-suite.yml` — CI matrix py 3.10–3.12 × pandas 2/3, runs `pytest -m "not slow"` + `ruff check`; `test-docs-build.yml` — PR docs check; `docs.yml` — publishes docs from master; `pypi-publish.yml` — sdist to PyPI on release. |
+| `.cursor/rules/` | Agent/editor guidance: python, pytest, sphinx-docs, testing standards + a project overview. |
+| `img/`, `examples/img/` | Images used by README and examples. |
+
+**Key invariants** (from CONTRIBUTING.md): maintain feature/API parity between `Repository` and
+`ProjectDirectory`; sphinx-format docstrings; memory-heavy functions take a `limit` option.

git_pandas-2.7.0/.obvious/config.yml

@@ -0,0 +1,6 @@
+# Repo policy for obvious workers.
+# Auto-detected from GitHub repo settings (wdm0006/git-pandas) on 2026-09-06.
+defaultBranch: master
+# All three merge methods are enabled on this repo; squash keeps setup PRs to one commit.
+mergeMethod: squash
+requireHumanMerge: true

git_pandas-2.7.0/.obvious/obvious.md

@@ -0,0 +1,97 @@
+# git-pandas — Agent Guide
+
+**Repo:** `wdm0006/git-pandas` · **Default branch:** `master` · **Language:** Python (library, v2.5.0)
+
+git-pandas turns Git repository data into pandas DataFrames — a pure Python library with an
+optional MCP stdio server. **No web app, no database, no listening ports, no long-running
+services.** "Local dev is healthy" means: venv installed, test suite green, lint clean,
+examples run.
+
+## Stack
+
+- **Runtime:** Python ≥ 3.10 (CI matrix: 3.10 / 3.11 / 3.12 × pandas 2.x / 3.x)
+- **Package manager:** uv (hatchling build backend; `uv.lock` is gitignored — resolution is fresh from `pyproject.toml`)
+- **Core deps:** gitpython, numpy, pandas (≥2.0), requests
+- **Tooling:** pytest (+ pytest-cov, pytest-mock), ruff (lint + format), sphinx, coverage
+- **Parallelism:** joblib — ⚠️ only in the `dev` extra, **not** in `all`
+- **Optional:** redis (RedisDFCache — its tests are fully mocked, no server needed), matplotlib / lifelines (examples)
+- **MCP server:** `mcp[cli]<2` + uvicorn — in no extras group; declared only in the PEP 723 block of `mcp_server/server.py`
+
+## Environment (baked into the sandbox snapshot)
+
+- `.venv/` at repo root: uv venv on CPython 3.12.14 (uv-managed), git-pandas 2.5.0 installed
+  editable with extras `dev` + `all`, plus `mcp[cli]<2` (1.29.1) and uvicorn
+- uv 0.12.10 at `~/.local/bin` (add to PATH: `export PATH="$HOME/.local/bin:$PATH"`)
+- git identity configured globally — required, tests create repos and make commits
+- Activate: `source .venv/bin/activate` (or prefix commands with `uv run`)
+
+## Commands
+
+| Task | Command |
+|---|---|
+| Fresh install | `uv venv --python 3.12 && uv pip install -e ".[dev,all]"` |
+| Tests (CI parity) | `MPLBACKEND=Agg python -m pytest -m "not slow"` |
+| Tests with coverage (Makefile) | `make test` (reinstalls `.[all]` first — see gotcha #1) |
+| Single test | `make test-single test=tests/test_Repository/test_properties.py` |
+| Lint (read-only, CI gate) | `python -m ruff check .` |
+| Lint (⚠️ mutates files) | `make lint` — `--fix --unsafe-fixes`; run only when asked |
+| Format | `make format` |
+| Run an example | `make run-example example=commit_history` |
+| MCP server (stdio) | `make mcp` → `python mcp_server/server.py` |
+| Docs build | `make docs` (CI also installs `docs/requirements.txt` first) |
+
+## Gotchas
+
+1. **joblib is only in the `dev` extra.** `uv pip install -e ".[all]"` alone → 14 test failures
+   in `parallel_cumulative_blame` / bulk-fetch tests ("Joblib not installed"). CI installs
+   `.[dev]`; the Makefile's `make test` path installs `.[all]`. Install `.[dev,all]` to cover both.
+2. **`make lint` auto-fixes** and can rewrite source files. Use `python -m ruff check .` for a
+   read-only gate (that's what CI runs).
+3. **MCP server needs mcp v1 API** (`from mcp.server.fastmcp import FastMCP`). mcp 2.x renamed
+   FastMCP → MCPServer and breaks the import. Pin `mcp[cli]<2`.
+4. MCP server scans `~/Documents` by default (`Config.SCAN_ROOT_DIR`, hardcoded — not env-configurable).
+5. Redis tests are mocked (`@patch` on `gitpandas.cache`) — no Redis server is needed; the
+   `redis` pytest marker is informational.
+6. Tests marked `remote` fetch from github.com — network required. `slow` (example smoke tests)
+   is deselected by the default `-m "not slow"`.
+7. `make test-all` has a typo (`MPLBACKEmND=Agg`) — harmless, but the env var isn't set.
+8. The Makefile `gitnoc` target points at a `gitnoc/` directory that does not exist in this repo.
+9. `.gitignore` ignores `uv.lock` and `scratch`; `.venv`/`.pytest_cache`/`.ruff_cache` are kept
+   out of git via `.git/info/exclude` in the sandbox, not via `.gitignore`.
+
+## Environment variables
+
+None required for tests, lint, or examples. `GitHubProfile` (in `gitpandas/project.py`) queries
+the public GitHub REST API over the network via `requests` — no token is read by the library.
+
+## Codebase map
+
+See [`codebase-map.md`](codebase-map.md).
+
+## Local verification
+
+The onboarding run's evidence is in the **Local Verification Summary** below and in
+[`skills/local-dev/SKILL.md`](skills/local-dev/SKILL.md).
+
+## Sandbox snapshot
+
+- **Template/snapshot ID:** `b04vxdj9qvlfbrzgb205:default`
+- **Captured:** 2026-09-06T20:25:59.276Z (UTC), from live session `izj5y29hgyt91gu7jjefe`
+- **Contains:** everything in "Environment" above — uv 0.12.10, uv-managed CPython 3.12.14,
+  repo at `/home/user/work/git-pandas` with the populated `.venv`, global git identity
+
+## Local Verification Summary
+
+**Run:** autobuild onboarding, 2026-09-06 (UTC), against `master` @ `e75870c` ("Preserve project revision limit remainder (#87)")
+**Stack:** CPython 3.12.14 · pandas 3.0.5 · numpy 2.5.3 · git 2.47.3 · uv 0.12.10
+
+| Check | Result |
+|---|---|
+| `MPLBACKEND=Agg python -m pytest -m "not slow"` | ✅ **572 passed**, 1 deselected (slow), 2 warnings, 0 failed — exit 0, ~160 s |
+| `python -m ruff check .` | ✅ All checks passed |
+| `make run-example example=commit_history` | ✅ exit 0 — committer stats, file-change and per-extension frames printed |
+| Library API (`Repository`) | ✅ `commit_history` (5 rows), `blame(by="repository")` (5 committers), `bus_factor(by="file")` (120 rows), `bus_factor(by="repository")` (bus factor 2), `hours_estimate` (6 rows) |
+| Library API (`ProjectDirectory`) | ✅ `commit_history` (3 rows, `repository` column populated) |
+| MCP server | ✅ stdio JSON-RPC `initialize` + `tools/list` handshake OK (serverInfo: GitPandas MCP Server; tools incl. `list_available_repos`, `repo_branches`) |
+
+Dev stack healthy: **yes**. No services to keep alive — the venv *is* the dev stack.

git_pandas-2.7.0/.obvious/skills/local-dev/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: local-dev
+description: Stand up and verify a working local dev environment for git-pandas (uv venv, pytest, ruff, examples, MCP server) — recorded from the 2026-09-06 onboarding run
+---
+
+# Local dev onboarding — git-pandas
+
+Durable record of the autobuild onboarding run (2026-09-06 UTC) against `master` @ `e75870c`,
+in sandbox `cmp_aPYkTByo`. The snapshot for that sandbox already contains a working
+environment — this skill also documents how to rebuild it from a bare checkout.
+
+## What "healthy" means here
+
+git-pandas is a pure Python library. There is no app to serve, no database, no ports.
+A healthy dev stack = venv with the right extras + green test suite + clean lint + a
+runnable example. Evidence below.
+
+## Fresh setup (from a bare checkout)
+
+```bash
+# 1. uv (package manager the repo standardizes on — Makefile + CI both use it)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+
+# 2. git identity — tests create repos and make commits
+git config --global user.email "dev@example.com"
+git config --global user.name  "Dev"
+
+# 3. venv on 3.12 (matches the CI matrix; uv downloads its managed CPython)
+uv venv --python 3.12
+
+# 4. deps — dev AND all. dev is not optional: joblib + pytest-mock live only there
+uv pip install -e ".[dev,all]"
+
+# 5. optional, only if you need the MCP server entry point (make mcp)
+uv pip install "mcp[cli]<2" uvicorn
+```
+
+## Verification checklist (all must pass)
+
+1. `source .venv/bin/activate`
+2. `MPLBACKEND=Agg python -m pytest -m "not slow"` → expect **572 passed, 1 deselected
+   (slow), 0 failed** (~160 s; tests marked `remote` fetch from github.com — network required)
+3. `python -m ruff check .` → "All checks passed!"
+4. `MPLBACKEND=Agg python examples/commit_history.py` → exit 0, prints committer stats and
+   file-change frames analyzing the git-pandas repo itself
+5. Optional MCP smoke: pipe an `initialize` + `tools/list` JSON-RPC pair into
+   `python mcp_server/server.py` and check for a `serverInfo` response
+
+## Known traps (cost real time during onboarding)
+
+- **joblib only in `dev` extra.** Installing `.[all]` (what `make test` does via `setup-all`)
+  yields 14 failures in `parallel_cumulative_blame` + bulk-fetch tests, all logging
+  "Joblib not installed". Fix: install `.[dev,all]`. CI avoids this by installing `.[dev]`.
+- **mcp 2.x breaks the server.** `mcp_server/server.py` imports the v1 API
+  (`mcp.server.fastmcp.FastMCP`); mcp 2.x renamed it to `MCPServer`. Pin `mcp[cli]<2`
+  (onboarding used 1.29.1). The pytest suite never hits this — `test_mcp_serialization.py`
+  stubs the import.
+- **`make lint` mutates** (`ruff check --fix --unsafe-fixes`). The CI gate is the read-only
+  `python -m ruff check .` — use that unless asked to auto-fix.
+- API signatures to not mis-guess (verified): `blame(rev, committer, by, ignore_globs,
+  include_globs)` — no `exts` kwarg; `bus_factor(by, ignore_globs, include_globs)` — no
+  `limit` kwarg; `ProjectDirectory(working_dir)` — no `max_depth`, and it has no
+  `repositories()` attribute.
+
+## Evidence from the onboarding run
+
+- CPython 3.12.14 · pandas 3.0.5 · numpy 2.5.3 · git 2.47.3 · uv 0.12.10 · gitpandas 2.5.0 (editable)
+- pytest `-m "not slow"`: **572 passed, 1 deselected, 2 warnings, 0 failed**, exit 0 (~160 s)
+- ruff check: all checks passed
+- `examples/commit_history.py`: exit 0 — repository + project-directory analyses printed
+- Direct API: `commit_history`, `blame(by="repository")`, `bus_factor(by="file")` (120 rows),
+  `bus_factor(by="repository")` (2), `hours_estimate` (6 rows), `ProjectDirectory.commit_history`
+- MCP: stdio JSON-RPC initialize + tools/list handshake OK with mcp 1.29.1
+- Snapshot baked after all checks passed: template `b04vxdj9qvlfbrzgb205:default`
+  @ 2026-09-06T20:25:59.276Z

{git_pandas-2.6.0 → git_pandas-2.7.0}/CHANGELOG.md

@@ -1,6 +1,21 @@
 Unreleased
 ==========
 
+v2.7.0
+======
+
+## New Features
+
+### Author-Date Commit Timing
+
+ * **NEW**: `Repository.commit_history()`, `Repository.hours_estimate()` and the matching `ProjectDirectory` methods accept `date_source="committer"` (default) or `"author"`. With `"author"` the `date` index, the `days` cutoff and the session grouping in `hours_estimate` use the author timestamp, so rebased, cherry-picked or squash-merged history (where every rewritten commit shares one committer timestamp) no longer collapses into a single session. Any other value raises `ValueError`. Default output is unchanged. `date_source` is part of the cache key, so `RedisDFCache` entries written by earlier versions are simply not matched; flush them if you share a cache across versions.
+
+## Bug Fixes
+
+### Blame and Bus Factor Validation
+
+* **FIXED**: Repository and project blame/bus-factor methods reject invalid `by` values with a `ValueError` naming the allowed values before accessing Git or caches.
+
 v2.6.0
 ======
 

{git_pandas-2.6.0 → git_pandas-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: git-pandas
-Version: 2.6.0
+Version: 2.7.0
 Summary: A utility for interacting with data from git repositories as Pandas dataframes
 Project-URL: Documentation, https://gitpandas.mcginniscommawill.com
 Project-URL: Source, https://github.com/wdm0006/git-pandas
@@ -55,23 +55,13 @@ Git-Pandas is a powerful Python library that transforms Git repository data into
 
 ![Cumulative Blame](https://raw.githubusercontent.com/wdm0006/git-pandas/master/examples/img/githubblame.png)
 
-## What's New in v2.6.0
-
-- **📦 Smaller Default Install**: `redis` and `coverage` are no longer installed by
-  `pip install git-pandas`. Use `pip install "git-pandas[redis]"` for `RedisDFCache`
-  and `pip install "git-pandas[coverage]"` for `Repository.coverage()`.
-- **🐼 pandas 3 Support**: The `pandas<3` cap is gone; the suite runs green against
-  pandas 2 and pandas 3.
-- **📈 Usable Cumulative Blame**: `cumulative_blame()` and `parallel_cumulative_blame()`
-  now return only contributor columns on an ascending `DatetimeIndex`, so `df.sum(axis=1)`,
-  date slicing, and `.diff()` work as expected.
-- **🎯 Exact `num_datapoints`**: `revs(num_datapoints=N)` returns exactly `N` evenly
-  spaced revisions instead of over-sampling.
-- **🧮 Honest Project Limits**: `ProjectDirectory.commit_history()`, `file_change_history()`,
-  `hours_estimate()` and `revs()` now split a project-wide `limit` across repositories without
-  dropping the remainder, so small limits no longer return empty or short frames.
-- **🔢 Finite Punchcards**: `punchcard(normalize=...)` no longer emits `NaN` for an
-  all-zero metric.
+## What's New in v2.7.0
+
+- **🕰️ Author-Date Timing**: `commit_history()` and `hours_estimate()` (on `Repository` and
+  `ProjectDirectory`) accept `date_source="author"` so rebased, cherry-picked or squash-merged
+  history is timed by when work was authored. The default (`"committer"`) is unchanged.
+- **🛡️ Clear `by=` Errors**: `blame()` and `bus_factor()` now raise a `ValueError` naming the
+  allowed values instead of `UnboundLocalError` or returning `None`.
 
 See the [changelog](CHANGELOG.md) for the full list, including the migration notes for
 the `cumulative_blame` and `revs` output changes.

{git_pandas-2.6.0 → git_pandas-2.7.0}/README.md

@@ -7,23 +7,13 @@ Git-Pandas is a powerful Python library that transforms Git repository data into
 
 ![Cumulative Blame](https://raw.githubusercontent.com/wdm0006/git-pandas/master/examples/img/githubblame.png)
 
-## What's New in v2.6.0
-
-- **📦 Smaller Default Install**: `redis` and `coverage` are no longer installed by
-  `pip install git-pandas`. Use `pip install "git-pandas[redis]"` for `RedisDFCache`
-  and `pip install "git-pandas[coverage]"` for `Repository.coverage()`.
-- **🐼 pandas 3 Support**: The `pandas<3` cap is gone; the suite runs green against
-  pandas 2 and pandas 3.
-- **📈 Usable Cumulative Blame**: `cumulative_blame()` and `parallel_cumulative_blame()`
-  now return only contributor columns on an ascending `DatetimeIndex`, so `df.sum(axis=1)`,
-  date slicing, and `.diff()` work as expected.
-- **🎯 Exact `num_datapoints`**: `revs(num_datapoints=N)` returns exactly `N` evenly
-  spaced revisions instead of over-sampling.
-- **🧮 Honest Project Limits**: `ProjectDirectory.commit_history()`, `file_change_history()`,
-  `hours_estimate()` and `revs()` now split a project-wide `limit` across repositories without
-  dropping the remainder, so small limits no longer return empty or short frames.
-- **🔢 Finite Punchcards**: `punchcard(normalize=...)` no longer emits `NaN` for an
-  all-zero metric.
+## What's New in v2.7.0
+
+- **🕰️ Author-Date Timing**: `commit_history()` and `hours_estimate()` (on `Repository` and
+  `ProjectDirectory`) accept `date_source="author"` so rebased, cherry-picked or squash-merged
+  history is timed by when work was authored. The default (`"committer"`) is unchanged.
+- **🛡️ Clear `by=` Errors**: `blame()` and `bus_factor()` now raise a `ValueError` naming the
+  allowed values instead of `UnboundLocalError` or returning `None`.
 
 See the [changelog](CHANGELOG.md) for the full list, including the migration notes for
 the `cumulative_blame` and `revs` output changes.

{git_pandas-2.6.0 → git_pandas-2.7.0}/gitpandas/project.py

@@ -17,7 +17,7 @@ import requests
 from git import GitCommandError
 
 from gitpandas.logging import logger  # Import the logger
-from gitpandas.repository import Repository
+from gitpandas.repository import Repository, _validate_date_source
 
 try:
     from joblib import Parallel, delayed
@@ -357,6 +357,7 @@ class ProjectDirectory:
         by=None,
         ignore_globs=None,
         include_globs=None,
+        date_source="committer",
     ):
         """
         Returns a DataFrame containing the estimated hours spent by each committer/author.
@@ -372,10 +373,12 @@ class ProjectDirectory:
             by (Optional[str]): How to group results. One of None, 'committer', 'author'
             ignore_globs (Optional[List[str]]): List of glob patterns for files to ignore
             include_globs (Optional[List[str]]): List of glob patterns for files to include
+            date_source (str): Timestamp used to order and group commits: "committer" (default) or "author"
 
         Returns:
             DataFrame: DataFrame with hours estimates
         """
+        _validate_date_source(date_source)
         logger.info(f"Estimating hours for branch '{branch or self.default_branch}'.")
         if branch is None:
             branch = self.default_branch
@@ -397,6 +400,7 @@ class ProjectDirectory:
                     committer=committer,
                     ignore_globs=ignore_globs,
                     include_globs=include_globs,
+                    date_source=date_source,
                 )
                 if not ch.empty:
                     ch = ch.copy()  # Avoid SettingWithCopyWarning
@@ -424,6 +428,7 @@ class ProjectDirectory:
         days=None,
         ignore_globs=None,
         include_globs=None,
+        date_source="committer",
     ):
         """
         Returns a DataFrame containing the commit history for all repositories.
@@ -434,10 +439,12 @@ class ProjectDirectory:
             days (Optional[int]): If provided, only return commits from last N days
             ignore_globs (Optional[List[str]]): List of glob patterns for files to ignore
             include_globs (Optional[List[str]]): List of glob patterns for files to include
+            date_source (str): Timestamp used for the date index and ``days`` cutoff: "committer" (default) or "author"
 
         Returns:
             DataFrame: DataFrame with commit history
         """
+        _validate_date_source(date_source)
         logger.info(f"Generating commit history for branch '{branch or self.default_branch}'.")
         if branch is None:
             branch = self.default_branch
@@ -455,6 +462,7 @@ class ProjectDirectory:
                     days=days,
                     ignore_globs=ignore_globs,
                     include_globs=include_globs,
+                    date_source=date_source,
                 )
                 if not ch.empty:
                     ch = ch.copy()  # Avoid SettingWithCopyWarning
@@ -620,11 +628,16 @@ class ProjectDirectory:
                     The repository is part of the grouping because file paths are
                     repository-relative and would otherwise collide across repositories.
 
+        Raises:
+            ValueError: If by is not one of the supported grouping values.
+
         Note:
             Results are sorted by lines of code in descending order.
             If both ignore_globs and include_globs are provided, files must match an include pattern
             and not match any ignore patterns to be included.
         """
+        if by not in ("repository", "file"):
+            raise ValueError(f"by must be one of ('repository', 'file'); got {by!r}")
         logger.info(f"Calculating blame grouped by {'committer' if committer else 'author'} and '{by}'.")
         df = None
 
@@ -1086,10 +1099,15 @@ class ProjectDirectory:
                     - bus factor (int): Bus factor for that file
                     - repository (str): Repository name
 
+        Raises:
+            ValueError: If by is not one of the supported grouping values.
+
         Note:
             A low bus factor (e.g. 1-2) indicates high risk as knowledge is concentrated among
             few contributors. A higher bus factor indicates knowledge is better distributed.
         """
+        if by not in ("projectd", "repository", "file"):
+            raise ValueError(f"by must be one of ('projectd', 'repository', 'file'); got {by!r}")
         logger.info(f"Calculating bus factor grouped by '{by}'.")
         if by == "file":
             # Calculate file-wise bus factor across all repositories

{git_pandas-2.6.0 → git_pandas-2.7.0}/gitpandas/repository.py

@@ -9,12 +9,15 @@
 """
 
 import fnmatch
+import functools
+import inspect
 import json
 import logging
 import os
 import shutil
 import tempfile
 import time
+from functools import wraps
 
 import git  # Import the full git module
 import numpy as np
@@ -34,6 +37,44 @@ except ImportError:
 
 __author__ = "willmcginnis"
 
+DATE_SOURCES = ("committer", "author")
+
+
+def _validate_date_source(date_source):
+    if date_source not in DATE_SOURCES:
+        raise ValueError(f"date_source must be one of {DATE_SOURCES}, got {date_source!r}")
+    return date_source
+
+
+def _validates_date_source(func):
+    """Reject an invalid ``date_source`` before the cache layer reads or stores anything."""
+    sig = inspect.signature(func)
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        bound = sig.bind(*args, **{k: v for k, v in kwargs.items() if k != "force_refresh"})
+        _validate_date_source(bound.arguments.get("date_source", "committer"))
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def _validates_by(*allowed):
+    def decorate(func):
+        signature = inspect.signature(func)
+
+        @wraps(func)
+        def validate(self, *args, **kwargs):
+            arguments = signature.bind(self, *args, **{k: v for k, v in kwargs.items() if k != "force_refresh"})
+            arguments.apply_defaults()
+            if arguments.arguments["by"] not in allowed:
+                raise ValueError(f"by must be one of {allowed!r}; got {arguments.arguments['by']!r}")
+            return func(self, *args, **kwargs)
+
+        return validate
+
+    return decorate
+
 
 def _parallel_cumulative_blame_func(self_, x, committer, ignore_globs, include_globs):
     blm = self_.blame(
@@ -283,6 +324,7 @@ class Repository:
             logger.error(f"Unexpected error analyzing coverage data: {e}", exc_info=True)
             return DataFrame(columns=["filename", "lines_covered", "total_lines", "coverage"])
 
+    @_validates_date_source
     @multicache(
         key_prefix="hours_estimate",
         key_list=[
@@ -294,6 +336,7 @@ class Repository:
             "committer",
             "ignore_globs",
             "include_globs",
+            "date_source",
         ],
     )
     def hours_estimate(
@@ -306,6 +349,7 @@ class Repository:
         committer=True,
         ignore_globs=None,
         include_globs=None,
+        date_source="committer",
     ):
         """
         inspired by: https://github.com/kimmobrunfeldt/git-hours/blob/8aaeee237cb9d9028e7a2592a25ad8468b1f45e4/index.js#L114-L143
@@ -322,6 +366,9 @@ class Repository:
         :param committer: (optional, default=True) whether to use committer vs. author
         :param ignore_globs: (optional, default=None) a list of globs to ignore, default none excludes nothing
         :param include_globs: (optinal, default=None) a list of globs to include, default of None includes everything.
+        :param date_source: (optional, default="committer") which timestamp orders and groups commits, "committer" or
+             "author". Use "author" for rebased, cherry-picked or squash-merged history, where every rewritten commit
+             shares one committer timestamp.
         :return: DataFrame
         """
         resolved_branch = self.default_branch if branch is None else branch
@@ -338,6 +385,7 @@ class Repository:
             days=days,
             ignore_globs=ignore_globs,
             include_globs=include_globs,
+            date_source=date_source,
         )
 
         # split by committer|author
@@ -370,7 +418,11 @@ class Repository:
         logger.info(f"Finished hours estimation for branch '{branch}'. Found data for {len(df)} contributors.")
         return df
 
-    @multicache(key_prefix="commit_history", key_list=["branch", "limit", "days", "ignore_globs", "include_globs"])
+    @_validates_date_source
+    @multicache(
+        key_prefix="commit_history",
+        key_list=["branch", "limit", "days", "ignore_globs", "include_globs", "date_source"],
+    )
     def commit_history(
         self,
         branch=None,
@@ -378,6 +430,7 @@ class Repository:
         days=None,
         ignore_globs=None,
         include_globs=None,
+        date_source="committer",
     ):
         """
         Returns a DataFrame containing the commit history for a branch.
@@ -391,6 +444,8 @@ class Repository:
             days (Optional[int]): If provided, only return commits from the last N days
             ignore_globs (Optional[List[str]]): List of glob patterns for files to ignore
             include_globs (Optional[List[str]]): List of glob patterns for files to include
+            date_source (str): Timestamp used for the ``date`` index and the ``days`` cutoff: "committer"
+                (default) or "author". Raises ValueError for anything else.
 
         Returns:
             DataFrame: A DataFrame with columns:
@@ -412,6 +467,8 @@ class Repository:
         if branch is None:
             branch = self.default_branch
 
+        date_attr = "authored_date" if date_source == "author" else "committed_date"
+
         logger.info(f"Fetching commit history for branch '{branch}'. Limit: {limit}, Days: {days}")
 
         # setup the data-set of commits
@@ -422,7 +479,7 @@ class Repository:
                     [
                         x.author.name,
                         x.committer.name,
-                        x.committed_date,
+                        getattr(x, date_attr),
                         x.message,
                         x.hexsha,
                         self.__check_extension(
@@ -443,7 +500,7 @@ class Repository:
                         x = next(commits)
                     except StopIteration:
                         break
-                    c_date = x.committed_date
+                    c_date = getattr(x, date_attr)
                     if c_date > dlim:
                         commit_count += 1
                         if logger.isEnabledFor(logging.DEBUG) and commit_count % 1000 == 0:
@@ -452,7 +509,7 @@ class Repository:
                             [
                                 x.author.name,
                                 x.committer.name,
-                                x.committed_date,
+                                getattr(x, date_attr),
                                 x.message,
                                 x.hexsha,
                                 self.__check_extension(
@@ -468,7 +525,7 @@ class Repository:
                 [
                     x.author.name,
                     x.committer.name,
-                    x.committed_date,
+                    getattr(x, date_attr),
                     x.message,
                     x.hexsha,
                     self.__check_extension(
@@ -1044,6 +1101,7 @@ class Repository:
         logger.debug(f"Finished checking extensions. Filtered files count: {len(out)}")
         return out
 
+    @_validates_by("repository", "file")
     @multicache(key_prefix="blame", key_list=["rev", "committer", "by", "ignore_globs", "include_globs"])
     def blame(
         self,
@@ -1079,6 +1137,9 @@ class Repository:
                     - file (str): File path
                     - loc (int): Lines of code attributed to that person in that file
 
+        Raises:
+            ValueError: If by is not one of the supported grouping values.
+
         Note:
             Results are sorted by lines of code in descending order.
             If both ignore_globs and include_globs are provided, files must match an include pattern
@@ -2263,6 +2324,7 @@ class Repository:
         """
         return str(self.git_dir)
 
+    @_validates_by("repository", "file")
     @multicache(key_prefix="bus_factor", key_list=["by", "ignore_globs", "include_globs"])
     def bus_factor(self, by="repository", ignore_globs=None, include_globs=None):
         """Calculates the "bus factor" for the repository.
@@ -2288,6 +2350,9 @@ class Repository:
                     - bus factor (int): Bus factor for that file
                     - repository (str): Repository name
 
+        Raises:
+            ValueError: If by is not one of the supported grouping values.
+
         Note:
             A low bus factor (e.g. 1-2) indicates high risk as knowledge is concentrated among
             few contributors. A higher bus factor indicates knowledge is better distributed.

{git_pandas-2.6.0 → git_pandas-2.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "git-pandas"
-version = "2.6.0"
+version = "2.7.0"
 description = "A utility for interacting with data from git repositories as Pandas dataframes"
 readme = "README.md"
 requires-python = ">=3.10"

{git_pandas-2.6.0 → git_pandas-2.7.0}/tests/test_Project/test_advanced.py

@@ -124,6 +124,7 @@ class TestProjectDirectoryAdvanced:
                 committer=True,
                 ignore_globs=None,
                 include_globs=None,
+                date_source="committer",
             )
 
     def test_bus_factor(self, repo_directories):