Commitose

Markov chain-based commit history simulator for realistic GitHub contribution graphs.

Warning

This tool was developed for educational and testing purposes only. The author does not encourage or endorse any use that involves dishonesty or false pretenses, including:

• Misrepresenting your contribution history to employers or collaborators
• Creating fake activity to game GitHub metrics or streaks
• Deceiving others about your actual work or skill level

Please consider the implications of synthetic commit history, and be transparent about its nature when relevant.

Features

• Markov chain timing: 4-state model (off, quiet, normal, busy) for realistic activity patterns
• Weekly rhythms: Configurable weekday vs. weekend activity
• Activity scaling: Scale commit activity by any factor during specific periods (vacations, sprints, etc.)
• Adaptive visualization: Preview commit graph with automatic terminal width handling

Installation

Prerequisite: Python 3.11+

git clone https://github.com/dnlzro/commitose.git
cd commitose
chmod +x commitose.py

Quick start

Note

Configure your Git user name/email first, or use --user-name/--user-email options.

# Preview a year of commits (no changes made)
./commitose.py --dry-run

# Generate commits for a date range
./commitose.py --start-date 2025-01-01 --end-date 2025-12-31

# Specify identity explicitly
./commitose.py --user-name "Your Name" --user-email "you@example.com"

Examples

# Multiple vacation periods
./commitose.py \
  --break 2025-07-15:2025-07-29 \
  --break 2025-12-20:2026-01-02

# Increased activity during a sprint
./commitose.py --break 2025-03-01:2025-03-15:2.0

# Custom repo location and branch
./commitose.py --repo-path ./my-repo --branch develop

# Reproducible results
./commitose.py --seed 12345

Command line options

Git identity

• --user-name NAME: Git user name
• --user-email EMAIL: Git user email (must match a verified GitHub email to show activity on contribution graph)

Date range

• --start-date YYYY-MM-DD: Start date (default: 365 days ago)
• --end-date YYYY-MM-DD: End date (default: today)

Activity control

• --break START:END[:FACTOR]: Scale activity for a period (repeatable)
  • Default factor: 0 (no commits; i.e., full vacation)
  • Examples: 0.5 = half, 2.0 = double
• --seed INT: Random seed for reproducibility

Repository settings

• --repo-path PATH: Repository location (default: ./commits_repo)
• --branch NAME: Branch name (default: main)

Other

• --dry-run: Preview without creating commits
• --config FILE: Load configuration from TOML file (see Advanced configuration)

Pushing to GitHub

After generating commits:

cd commits_repo  # or your --repo-path
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

Advanced configuration (via TOML)

Any of the CLI flags above may be specified in a TOML config file, as well some more advanced options to modify simulation parameters. For example:

# Date range
start_date = "2025-01-01"
end_date = "2025-12-31"

# Identity
user_name = "Your Name"
user_email = "your.email@example.com"

# Repository
repo_path = "./commits"
branch = "master"
dry_run = false
seed = 42

# Activity patterns
weekday_weights = [1.0, 1.0, 2.0, 1.0, 1.0, 0.75, 0.25]  # Mon-Sun

breaks = [
  { start_date = "2025-07-15", end_date = "2025-07-29", factor = 0 },
  { start_date = "2025-03-01", end_date = "2025-03-15", factor = 2.0 },
]

# Markov chain (4 states: off, quiet, normal, busy)
transition_matrix = [
  [0.65, 0.25, 0.10, 0.00],  # off → [off, quiet, normal, busy]
  [0.15, 0.60, 0.20, 0.05],  # quiet → [...]
  [0.05, 0.15, 0.65, 0.15],  # normal → [...]
  [0.00, 0.05, 0.35, 0.60],  # busy → [...]
]

commit_means = [0, 1, 3, 7]  # Expected number of commits per state
commit_dispersion = 1.0  # Lower = more uniform sampling distribution
commit_zero_inflation = [1.0, 0.3, 0.1, 0.05]  # P(zero commits) per state

Then you can specify the config file with --config FILE:

./commitose.py --config config.toml

Note

If additional CLI flags are provided, they will override the corresponding option in the TOML config file.