git-timemachine

git-timemachine is a command-line tool that helps users record commits on Git repositories at arbitrary timestamps. It allows backdating commits with randomized timestamps while maintaining daily commit limits.

Features

• Record commits at calculated timestamps with random time increments
• Shift commit time forward or backward by days/hours
• Review commit history grouped by date
• Enforce daily commit limits to prevent abuse
• Automatic version checking from PyPI
• Configurable settings via YAML files

Installation

Via pip (Recommended)

pip install --user --upgrade git-timemachine

Via Binary Release

Download the latest release from GitHub Releases and ensure the git-timemachine command is in your $PATH environment variable.

Quick Start

Record a Commit

git-timemachine commit -m "Your commit message"

The commit will be recorded at a calculated timestamp based on your last commit time plus a random increment (between 600-3600 seconds by default).

Shift Commit Time

# Shift forward by 3 days
git-timemachine shift --days 3

# Shift backward by 2 hours
git-timemachine shift --hours -2

# Set timestamp directly
git-timemachine shift --at "2024-06-15T10:30:00"

# Show current timestamp
git-timemachine shift --show

Review Commit History

git-timemachine review

Displays a table showing commit counts grouped by date:

+------------+---------+
|    date    | commits |
+------------+---------+
| 2025-01-15 |    3    |
| 2025-01-16 |    5    |
| 2025-01-17 |    2    |
+------------+---------+

Configuration

Configuration files are stored in ~/.git-timemachine/ by default.

Config File (~/.git-timemachine/config)

States File (~/.git-timemachine/states)

Environment Variables

CLI Reference

git-timemachine [OPTIONS] COMMAND [ARGS]...

Commands:
  commit  Record a commit at specified time node
  shift   Adjust the persisted timestamp forward or backward
  review  Review commit history grouped by date

Global Options:
  -C, --repo-dir PATH  Repository directory (default: current directory)
  --version            Show version

commit

git-timemachine commit [OPTIONS] [ARGS]

Options:
  -m, --message TEXT    Commit message (mutually exclusive with --file)
  -F, --file PATH       Read commit message from file (mutually exclusive with
                        --message)
  --jitter-min INTEGER  Minimum time jitter in seconds (overrides config)
  --jitter-max INTEGER  Maximum time jitter in seconds (overrides config)

Arguments:
  ARGS  Extra arguments passed to git commit

Note: Either --message or --file is required. They are mutually exclusive.

The --jitter-min and --jitter-max options override the config file settings for the current commit only.

shift

git-timemachine shift [OPTIONS]

Options:
  -d, --days FLOAT    Shift by N days (positive=forward, negative=backward)
  -h, --hours FLOAT   Shift by N hours (positive=forward, negative=backward)
  -a, --at TEXT       Directly overwrite timestamp with ISO datetime string
  -s, --show          Display current timestamp without modifying

Note: At least one of --days, --hours, --at, or --show is required.

review

git-timemachine review

Development

Setup

# Clone the repository
git clone https://github.com/garrett-he/git-timemachine.git
cd git-timemachine

# Install dependencies
just init

Common Commands

just lint          # Run ruff
just test          # Run tests with coverage
just build         # Build package

Documentation

• Architecture - System architecture and design
• Design - Design decisions and implementation details

Requirements

• Python 3.12 - 3.14
• Git (command-line tool)

License

Copyright (C) 2025 Garrett HE garrett.he@hotmail.com

The MIT License, see LICENSE.