git-timemachine 3.0.0

A command-line tool that helps you record commits on Git repositories at any time node.

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)

Setting	Default	Description
max_daily_commits	5	Maximum commits per day
jitter_min	600	Minimum time increment (sec)
jitter_max	3600	Maximum time increment (sec)
update_check_interval	1	Days between version checks

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

State	Description
last_commit_time	Timestamp of last commit
last_update_check	Timestamp of last version check

Environment Variables

Variable	Description
GIT_TIMEMACHINE_CONFIG	Custom config file path
GIT_TIMEMACHINE_STATES	Custom states file path

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 [e-mail]

The MIT License, see LICENSE.