A modern, cross-platform rewrite of the original 1990-script in Rust, designed to create GitHub repositories with backdated commits. Enhance your contribution graph by showing activity in earlier years.

Core Features

• Rust-powered: Fast, reliable, and memory-safe performance.
• Cross-platform: Single binary works on macOS, Windows, and Linux.
• Interactive CLI: User-friendly prompts guide you through the process.
• Secure: Uses GitHub personal access tokens for auth and performs all operations locally.
• Zero Dependencies: No runtime requirements needed for the executable.

Installation & Usage

Note: The npm package is published on npmjs.com. GitHub Packages and npmjs.com are separate registries; only packages published to GitHub Packages appear in the GitHub "Packages" tab.

Recommended: npx

The easiest way to run the tool without a manual installation.

npx git-timetraveler --year 1990

You can also specify a custom repository name using the --repo flag:

npx git-timetraveler --year 1990 --repo Git-Timetraveler

To create commits for a range of years, use the --years flag:

npx git-timetraveler --years 1990-2001 --repo Git-Timetraveler

If --repo is not provided, the repository name defaults to the year.

• --year and --years are mutually exclusive. Use only one at a time.

Manual Installation

Download the appropriate binary for your system from the Releases Page.

Run Interactively

Simply execute the command to be guided by interactive prompts.

git-timetraveler

You will be asked for your GitHub username, a personal access token, and the desired date.

GitHub Setup

1. Create a Repository: On GitHub, create a new, empty repository. The name should ideally match the year (e.g., 1990).
2. Generate a Token: Go to Settings → Developer settings → Personal access tokens → Tokens (classic).
   • Click "Generate new token (classic)".
   • Grant the repo scope (Full control of private repositories).
   • Copy the generated token to use in the tool.

How It Works

The tool automates the git process for creating a commit with a specific, historical date.

1. Clones your newly created empty repository.
2. Creates a README.md file within the local clone.
3. Commits the file using a custom author and committer date based on your input.
   • This is done by setting the GIT_AUTHOR_DATE and GIT_COMMITTER_DATE environment variables.
4. Pushes the backdated commit to your GitHub repository.
5. Cleans up the local directory.

GitHub's contribution graph renders commits based on the author date, which is how the historical square appears on your profile.

Usage

Interactive Menu (Recommended for Local Terminals)

Run the CLI in a supported terminal (e.g., bash, zsh, Terminal.app, iTerm2) to use the beginner-friendly interactive menu:

npx git-timetraveler

You will be guided through all required options with prompts and validation.

Non-Interactive Mode (For npx, CI, or Scripts)

If you are running in a non-interactive environment (e.g., npx, CI, or a script), use the --no-menu flag and provide all required arguments:

npx git-timetraveler --no-menu --username <user> --token <token> --repo <repo> --year <year>

Or for a range of years:

npx git-timetraveler --no-menu --username <user> --token <token> --repo <repo> --years 2000-2005

Required arguments for --no-menu:

• --username (GitHub username)
• --token (GitHub personal access token)
• --repo (Repository name)
• --year or --years (Year or range)

Other options:

• --branch (target branch, default: main)
• --month, --day, --hour, --force, etc.

If any required argument is missing, the CLI will print an error and exit.

Note:

• The interactive menu requires a real TTY. If you see a panic or error about min <= max or TTY, use --no-menu mode.
• For automation, always use --no-menu and supply all arguments.