Metadata-Version: 2.4
Name: git-timemachine
Version: 3.0.0
Summary: A command-line tool that helps you record commits on Git repositories at any time node.
Project-URL: homepage, https://github.com/garrett-he/git-timemachine
Project-URL: repository, https://github.com/garrett-he/git-timemachine.git
Project-URL: changelog, https://github.com/garrett-he/git-timemachine/blob/main/CHANGELOG.md
Author-email: Garrett HE <garrett.he@outlook.com>
License: BSD-3-Clause
License-File: LICENSE
Keywords: committing,git,timemachine
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.12
Requires-Dist: prettytable>=3.16.0
Requires-Dist: pydantic>=2.11.9
Requires-Dist: pygit2>=1.18.2
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.32.5
Requires-Dist: typer>=0.16.1
Description-Content-Type: text/markdown

<div align="center">
    <img src="https://raw.githubusercontent.com/garrett-he/git-timemachine/refs/heads/main/logo/git-timemachine.png"/>
</div>

![license](https://img.shields.io/github/license/garrett-he/git-timemachine)
![test](https://img.shields.io/github/actions/workflow/status/garrett-he/git-timemachine/test.yml)
![version](https://img.shields.io/pypi/v/git-timemachine)
![python](https://img.shields.io/pypi/pyversions/git-timemachine)
![downloads](https://img.shields.io/pypi/dm/git-timemachine)

# 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)

```bash
pip install --user --upgrade git-timemachine
```

### Via Binary Release

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

## Quick Start

### Record a Commit

```bash
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

```bash
# 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

```bash
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

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

# Install dependencies
just init
```

### Common Commands

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

## Documentation

- [Architecture](docs/architecture.md) - System architecture and design
- [Design](docs/design.md) - 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](./LICENSE).

[1]: https://git-scm.com/
[2]: https://github.com/garrett-he/git-timemachine/releases
