git-alibi 0.1.0__tar.gz

git_alibi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Light
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_alibi-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: git-alibi
+Version: 0.1.0
+Summary: Rewrite git commit timestamps to fit within or exclude certain time windows
+Author-email: Zach Light <zachary.j.light@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zlight97/git-alibi
+Project-URL: Issues, https://github.com/zlight97/git-alibi/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: gitpython>=3.1
+Requires-Dist: tomlkit>=0.12
+Requires-Dist: git-filter-repo>=2.38
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# git-alibi
+
+Rewrite git commit timestamps to fit within (or avoid) configured time windows.
+
+Useful for keeping commit history clean when you work odd hours, across timezones,
+or want commits to consistently appear within business hours. Alibi saves a backup
+before every rewrite so changes can always be undone.
+
+## Requirements
+
+- Python 3.11 or newer
+- git 2.25 or newer
+
+## Installation
+
+**pip** (simplest):
+```bash
+cd git-alibi
+pip install .
+```
+
+**pipx** (isolated, recommended for CLI tools):
+```bash
+pipx install /path/to/git-alibi
+```
+
+**Virtual environment** (if you prefer not to touch system Python):
+```bash
+cd git-alibi
+python3 -m venv .venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install .
+```
+
+Verify the install:
+```bash
+git-alibi --help
+# git also picks it up automatically:
+git alibi --help
+```
+
+## Uninstallation
+
+```bash
+pip uninstall git-alibi      # if installed with pip
+pipx uninstall git-alibi     # if installed with pipx
+rm -rf .venv                 # if installed into a venv, just delete it
+```
+
+## Quick start
+
+Preview what would change without touching the repo:
+```bash
+git-alibi rewrite --dry-run
+```
+
+Apply the rewrite:
+```bash
+git-alibi rewrite
+```
+
+If the branch was already pushed:
+```bash
+git push --force-with-lease
+```
+
+Undo the last rewrite:
+```bash
+git-alibi restore
+```
+
+## Configuration
+
+Alibi is configured with TOML files. Settings in the local file take precedence
+over the global one.
+
+| File | Scope |
+|------|-------|
+| `~/.config/alibi/config.toml` | Global (all repos) |
+| `.git/alibi/config.toml` | Local (this repo only) |
+
+Open a config file in `$EDITOR` (created with commented-out defaults if it doesn't exist):
+```bash
+git-alibi config local
+git-alibi config global
+```
+
+### Example config
+
+```toml
+[behavior]
+timezone = "America/Chicago"
+out_of_window = "nearest"   # nearest / previous / next / random
+spacing = "preserve"        # preserve / proportional / even / random
+
+[days]
+block = ["SAT", "SUN"]      # never place commits on weekends
+
+[times]
+allow = ["09:00-17:00"]     # only allow commits during business hours
+
+[authors]
+# CURRENT expands to the email in git config user.email
+emails = ["CURRENT"]
+
+[markers]
+# Commits containing this string in their message are never rewritten
+skip = ["[no-alibi]"]
+```
+
+## Commands
+
+### `rewrite`
+
+Rewrites commit timestamps to fit within the configured windows. Operates on
+commits in the current branch since it diverged from `main`/`master` (or the
+upstream tracking branch), for the current git user's commits only.
+
+```bash
+git-alibi rewrite [OPTIONS] [REF]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview changes without modifying the repo |
+| `-v, --verbose` | Show all commits in dry-run output, not just changed ones |
+| `--no-backup` | Skip saving a backup before rewriting |
+| `--shift DURATION` | Shift timestamps by a fixed amount instead of fitting windows (e.g. `+2h`, `-5h30m`, `+5:30`) |
+| `--timezone TZ` | Override the timezone (IANA name, e.g. `America/Chicago`) |
+| `--allow-days DAYS` | Comma-separated days to allow (e.g. `MON,TUE,WED,THU,FRI`) |
+| `--block-days DAYS` | Comma-separated days to block (e.g. `SAT,SUN`) |
+| `--allow-times RANGES` | Time ranges to allow (e.g. `09:00-17:00`, `MON+FRI@09:00-12:00`) |
+| `--block-times RANGES` | Time ranges to block |
+| `--allow-dates DATES` | Dates or ranges to allow (e.g. `2024-03-01:2024-03-31`) |
+| `--block-dates DATES` | Dates or ranges to block (e.g. `2024-12-25`) |
+| `--out-of-window` | How to handle commits outside all windows: `nearest` (default), `previous`, `next`, `random` |
+| `--spacing` | How to distribute commits within a window: `preserve` (default), `proportional`, `even`, `random` |
+| `--author-emails EMAILS` | Comma-separated emails to rewrite; `CURRENT` = git config `user.email` |
+| `--all-authors` | Rewrite commits by all authors, not just the current user |
+| `--all-history` | Rewrite all reachable history, not just the current branch |
+| `--skip-markers MARKERS` | Comma-separated message markers that exempt a commit (default: `[no-alibi]`) |
+| `-f, --force` | Proceed even if signed commits would be rewritten |
+
+#### Timezone correction with `--shift`
+
+If you committed in the wrong timezone, shift all timestamps by a fixed offset:
+
+```bash
+git-alibi rewrite --shift +5:30    # move everything forward 5h30m
+git-alibi rewrite --shift -8h      # move everything back 8 hours
+git-alibi rewrite --dry-run --shift +2h   # preview first
+```
+
+#### Opting out of rewriting
+
+Add `[no-alibi]` anywhere in a commit message to permanently exempt that commit:
+
+```
+fix: correct off-by-one error [no-alibi]
+```
+
+The marker string is configurable via `[markers] skip` in the config file or
+`--skip-markers` on the command line.
+
+### `restore`
+
+Restores commit timestamps from the backup saved before a previous rewrite.
+
+```bash
+git-alibi restore [OPTIONS] [REF]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview what would be restored without applying |
+| `-v, --verbose` | Show all commits, not just changed ones |
+| `--last N` | Undo the Nth most recent rewrite (default: `1` = last) |
+| `--rewrite ID` | Restore a specific rewrite by ID (see `history`) |
+| `-f, --force` | Proceed even if signed commits would be rewritten |
+
+```bash
+git-alibi restore              # undo the last rewrite
+git-alibi restore --last 2    # undo the second-to-last rewrite
+git-alibi restore --rewrite 3 # restore to a specific snapshot ID
+```
+
+### `history`
+
+Shows all recorded rewrites and the exact command to restore each one.
+
+```bash
+git-alibi history [-v]
+```
+
+```
+Rewrite history — 3 snapshots in .git/alibi/backup.json
+
+  ID    WHEN                     COMMITS  --last  RESTORE
+  ───────────────────────────────────────────────────────
+  1     2024-01-06 Sat 09:15:00        5       3  alibi restore --last 3
+  2     2024-01-07 Sun 14:30:00        3       2  alibi restore --last 2
+  3     2024-01-08 Mon 11:15:00        2       1  alibi restore ← latest
+```
+
+Use `-v` to also list the individual commits and their original timestamps.
+
+### `config`
+
+Opens a config file in `$EDITOR`, creating it with commented-out defaults if it
+doesn't exist yet.
+
+```bash
+git-alibi config local    # .git/alibi/config.toml
+git-alibi config global   # ~/.config/alibi/config.toml
+```

git_alibi-0.1.0/README.md

@@ -0,0 +1,215 @@
+# git-alibi
+
+Rewrite git commit timestamps to fit within (or avoid) configured time windows.
+
+Useful for keeping commit history clean when you work odd hours, across timezones,
+or want commits to consistently appear within business hours. Alibi saves a backup
+before every rewrite so changes can always be undone.
+
+## Requirements
+
+- Python 3.11 or newer
+- git 2.25 or newer
+
+## Installation
+
+**pip** (simplest):
+```bash
+cd git-alibi
+pip install .
+```
+
+**pipx** (isolated, recommended for CLI tools):
+```bash
+pipx install /path/to/git-alibi
+```
+
+**Virtual environment** (if you prefer not to touch system Python):
+```bash
+cd git-alibi
+python3 -m venv .venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install .
+```
+
+Verify the install:
+```bash
+git-alibi --help
+# git also picks it up automatically:
+git alibi --help
+```
+
+## Uninstallation
+
+```bash
+pip uninstall git-alibi      # if installed with pip
+pipx uninstall git-alibi     # if installed with pipx
+rm -rf .venv                 # if installed into a venv, just delete it
+```
+
+## Quick start
+
+Preview what would change without touching the repo:
+```bash
+git-alibi rewrite --dry-run
+```
+
+Apply the rewrite:
+```bash
+git-alibi rewrite
+```
+
+If the branch was already pushed:
+```bash
+git push --force-with-lease
+```
+
+Undo the last rewrite:
+```bash
+git-alibi restore
+```
+
+## Configuration
+
+Alibi is configured with TOML files. Settings in the local file take precedence
+over the global one.
+
+| File | Scope |
+|------|-------|
+| `~/.config/alibi/config.toml` | Global (all repos) |
+| `.git/alibi/config.toml` | Local (this repo only) |
+
+Open a config file in `$EDITOR` (created with commented-out defaults if it doesn't exist):
+```bash
+git-alibi config local
+git-alibi config global
+```
+
+### Example config
+
+```toml
+[behavior]
+timezone = "America/Chicago"
+out_of_window = "nearest"   # nearest / previous / next / random
+spacing = "preserve"        # preserve / proportional / even / random
+
+[days]
+block = ["SAT", "SUN"]      # never place commits on weekends
+
+[times]
+allow = ["09:00-17:00"]     # only allow commits during business hours
+
+[authors]
+# CURRENT expands to the email in git config user.email
+emails = ["CURRENT"]
+
+[markers]
+# Commits containing this string in their message are never rewritten
+skip = ["[no-alibi]"]
+```
+
+## Commands
+
+### `rewrite`
+
+Rewrites commit timestamps to fit within the configured windows. Operates on
+commits in the current branch since it diverged from `main`/`master` (or the
+upstream tracking branch), for the current git user's commits only.
+
+```bash
+git-alibi rewrite [OPTIONS] [REF]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview changes without modifying the repo |
+| `-v, --verbose` | Show all commits in dry-run output, not just changed ones |
+| `--no-backup` | Skip saving a backup before rewriting |
+| `--shift DURATION` | Shift timestamps by a fixed amount instead of fitting windows (e.g. `+2h`, `-5h30m`, `+5:30`) |
+| `--timezone TZ` | Override the timezone (IANA name, e.g. `America/Chicago`) |
+| `--allow-days DAYS` | Comma-separated days to allow (e.g. `MON,TUE,WED,THU,FRI`) |
+| `--block-days DAYS` | Comma-separated days to block (e.g. `SAT,SUN`) |
+| `--allow-times RANGES` | Time ranges to allow (e.g. `09:00-17:00`, `MON+FRI@09:00-12:00`) |
+| `--block-times RANGES` | Time ranges to block |
+| `--allow-dates DATES` | Dates or ranges to allow (e.g. `2024-03-01:2024-03-31`) |
+| `--block-dates DATES` | Dates or ranges to block (e.g. `2024-12-25`) |
+| `--out-of-window` | How to handle commits outside all windows: `nearest` (default), `previous`, `next`, `random` |
+| `--spacing` | How to distribute commits within a window: `preserve` (default), `proportional`, `even`, `random` |
+| `--author-emails EMAILS` | Comma-separated emails to rewrite; `CURRENT` = git config `user.email` |
+| `--all-authors` | Rewrite commits by all authors, not just the current user |
+| `--all-history` | Rewrite all reachable history, not just the current branch |
+| `--skip-markers MARKERS` | Comma-separated message markers that exempt a commit (default: `[no-alibi]`) |
+| `-f, --force` | Proceed even if signed commits would be rewritten |
+
+#### Timezone correction with `--shift`
+
+If you committed in the wrong timezone, shift all timestamps by a fixed offset:
+
+```bash
+git-alibi rewrite --shift +5:30    # move everything forward 5h30m
+git-alibi rewrite --shift -8h      # move everything back 8 hours
+git-alibi rewrite --dry-run --shift +2h   # preview first
+```
+
+#### Opting out of rewriting
+
+Add `[no-alibi]` anywhere in a commit message to permanently exempt that commit:
+
+```
+fix: correct off-by-one error [no-alibi]
+```
+
+The marker string is configurable via `[markers] skip` in the config file or
+`--skip-markers` on the command line.
+
+### `restore`
+
+Restores commit timestamps from the backup saved before a previous rewrite.
+
+```bash
+git-alibi restore [OPTIONS] [REF]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview what would be restored without applying |
+| `-v, --verbose` | Show all commits, not just changed ones |
+| `--last N` | Undo the Nth most recent rewrite (default: `1` = last) |
+| `--rewrite ID` | Restore a specific rewrite by ID (see `history`) |
+| `-f, --force` | Proceed even if signed commits would be rewritten |
+
+```bash
+git-alibi restore              # undo the last rewrite
+git-alibi restore --last 2    # undo the second-to-last rewrite
+git-alibi restore --rewrite 3 # restore to a specific snapshot ID
+```
+
+### `history`
+
+Shows all recorded rewrites and the exact command to restore each one.
+
+```bash
+git-alibi history [-v]
+```
+
+```
+Rewrite history — 3 snapshots in .git/alibi/backup.json
+
+  ID    WHEN                     COMMITS  --last  RESTORE
+  ───────────────────────────────────────────────────────
+  1     2024-01-06 Sat 09:15:00        5       3  alibi restore --last 3
+  2     2024-01-07 Sun 14:30:00        3       2  alibi restore --last 2
+  3     2024-01-08 Mon 11:15:00        2       1  alibi restore ← latest
+```
+
+Use `-v` to also list the individual commits and their original timestamps.
+
+### `config`
+
+Opens a config file in `$EDITOR`, creating it with commented-out defaults if it
+doesn't exist yet.
+
+```bash
+git-alibi config local    # .git/alibi/config.toml
+git-alibi config global   # ~/.config/alibi/config.toml
+```

git_alibi-0.1.0/git_alibi/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

git_alibi-0.1.0/git_alibi/backup.py

@@ -0,0 +1,133 @@
+"""Backup of original commit timestamps, organised as rewrite snapshots.
+
+The backup file lives at <git_dir>/alibi/backup.json.
+
+Each call to ``save_rewrite`` appends one snapshot — capturing the before/after
+SHA and pre-rewrite timestamps for every commit touched by that run.  Multiple
+snapshots allow restoring to any previous state via SHA chaining:
+
+  sha_after[n]  ==  sha_before[n+1]
+
+so walking backwards through snapshots traces a commit from its current SHA
+all the way back to its original timestamps.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TypedDict
+
+import git
+
+
+class RewriteCommit(TypedDict):
+    sha_before: str  # SHA of the commit before this rewrite
+    sha_after: str  # SHA of the commit after this rewrite
+    author_date: str  # author timestamp before this rewrite
+    committer_date: str  # committer timestamp before this rewrite
+
+
+class RewriteSnapshot(TypedDict):
+    id: int
+    timestamp: str
+    commits: list[RewriteCommit]
+
+
+def backup_path(repo: git.Repo) -> Path:
+    """Return the absolute path to the backup file for this repository.
+
+    Uses repo.common_dir when available (handles git worktrees correctly —
+    all worktrees share one backup in the main .git directory).  Falls back
+    to repo.git_dir for older GitPython versions.
+    """
+    git_dir = Path(getattr(repo, "common_dir", None) or repo.git_dir)
+    return git_dir / "alibi" / "backup.json"
+
+
+def _load(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise RuntimeError(f"Failed to read backup file {path}: {exc}") from exc
+
+
+def _write(path: Path, data: dict) -> None:
+    """Atomically write data to path (via .tmp → rename)."""
+    tmp = path.with_suffix(".json.tmp")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp.write_text(json.dumps(data, indent=2, ensure_ascii=True), encoding="utf-8")
+        tmp.replace(path)
+    except OSError as exc:
+        raise RuntimeError(f"Cannot write backup file {path}: {exc}") from exc
+
+
+def load_rewrites(repo: git.Repo) -> list[RewriteSnapshot]:
+    """Load all rewrite snapshots from the backup file.
+
+    Raises RuntimeError if no backup file exists or the format is unrecognised.
+    """
+    path = backup_path(repo)
+    if not path.exists():
+        raise RuntimeError(
+            f"No backup file found at {path}. "
+            "Run 'alibi rewrite' (without --no-backup) at least once to create one."
+        )
+    data = _load(path)
+    if "rewrites" not in data:
+        raise RuntimeError(
+            "Backup file is in an old format and cannot be used for restore. "
+            "Run 'alibi rewrite' again to create a new backup."
+        )
+    return data.get("rewrites", [])
+
+
+def save_rewrite(repo: git.Repo, commits: list[RewriteCommit]) -> int:
+    """Append a new rewrite snapshot to the backup file and return its ID.
+
+    Each call records the before/after SHA and pre-rewrite timestamps for
+    every commit touched by one alibi rewrite run.  Returns -1 and writes
+    nothing if commits is empty.
+    """
+    if not commits:
+        return -1
+
+    path = backup_path(repo)
+    data = _load(path)
+    now = datetime.now(timezone.utc).isoformat()
+
+    if not data or "rewrites" not in data:
+        data = {"created_at": now, "updated_at": now, "rewrites": []}
+
+    next_id = (data["rewrites"][-1]["id"] + 1) if data["rewrites"] else 1
+    data["rewrites"].append(
+        {
+            "id": next_id,
+            "timestamp": now,
+            "commits": commits,
+        }
+    )
+    data["updated_at"] = now
+
+    _write(path, data)
+    return next_id
+
+
+def remove_rewrites_from(repo: git.Repo, from_id: int) -> None:
+    """Remove the snapshot with the given ID and all subsequent snapshots.
+
+    Called after a successful restore to prune stale history — snapshots
+    after the restore point no longer reflect any real repo state.
+    """
+    path = backup_path(repo)
+    data = _load(path)
+    if not data or "rewrites" not in data:
+        return
+
+    data["rewrites"] = [r for r in data["rewrites"] if r["id"] < from_id]
+    data["updated_at"] = datetime.now(timezone.utc).isoformat()
+    _write(path, data)