commit-bot

Generate human-like git contributions to keep your GitHub contribution graph green.

Features

• Pattern analysis — Fetch your existing GitHub contributions and analyze the pattern
• Smart matching — Generate commits that match your real contribution rhythm
• Gap filling — Fill only days where you had zero contributions
• Target mode — Hit a specific contribution total (e.g., 1000/year)
• Manual mode — Full control over date range, commit frequency, and hours
• Human-like — Random commit times, varied messages, realistic rest days
• Fast — No artificial delays, instant generation

Install

git clone https://github.com/mangodxd/commit-bot.git
cd commit-bot
pip install -r requirements.txt

Setup

1. Create a GitHub Personal Access Token:

   • Go to GitHub Settings > Developer settings > Personal access tokens
   • Create token with read:user scope
   • Copy the token

2. Set your token (pick one):

# Option A: environment variable
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Option B: .env file
echo "GITHUB_TOKEN=ghp_xxxxxxxxxxxx" > .env

3. Configure git identity (if not already set):

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Usage

Analyze your pattern

See your contribution stats before generating anything:

python main.py --analyze --user YOUR_USERNAME

Output:

  ANALYSIS - 2025
  Total contributions:  822
  Active days:          310/365
  Fill rate:            84.9%
  Avg per active day:   2.7

  Weekday averages:
    Mon: 3.2 ############
    Tue: 3.5 ##############
    ...

  Monthly breakdown:
    Jan:  85 commits, 28 active ########################...
    ...

  Gap days: 55

Match your pattern (recommended)

Generates commits matching your existing rhythm, fills some gaps:

python main.py --match --user YOUR_USERNAME

Fill all gap days

Add commits to every day you missed:

python main.py --fill-gaps --user YOUR_USERNAME

Hit a target number

Automatically calculates how many gap days to fill:

python main.py --target 1000 --user YOUR_USERNAME

Manual mode

Full control, no GitHub API needed:

python main.py --start 2025-01-01 --end 2025-12-31 \
  --weekday-min 2 --weekday-max 4 \
  --weekend-min 0 --weekend-max 1

Preview first

Always safe to preview:

python main.py --match --user YOUR_USERNAME --dry-run

All Options

GitHub API:
  --user USERNAME       GitHub username
  --token TOKEN         GitHub token (or set GITHUB_TOKEN env)
  --year YEAR           Year to analyze (default: current)

Mode:
  --analyze             Analyze pattern, no commits
  --match               Match existing pattern + fill gaps
  --fill-gaps           Fill all zero-contribution days
  --target N            Hit a specific total

Manual:
  --start YYYY-MM-DD    Start date
  --end YYYY-MM-DD      End date
  --weekday-min N       Min commits weekdays (default: 1)
  --weekday-max N       Max commits weekdays (default: 4)
  --weekend-min N       Min commits weekends (default: 0)
  --weekend-max N       Max commits weekends (default: 2)

Repo:
  --repo PATH           Local repo path (default: ./green-repo)
  --remote URL          GitHub remote URL
  --branch NAME         Branch name (default: main)

Schedule:
  --weekday-start H     Earliest hour weekdays (default: 9)
  --weekday-end H       Latest hour weekdays (default: 20)
  --weekend-start H     Earliest hour weekends (default: 11)
  --weekend-end H       Latest hour weekends (default: 17)
  --vacation M [M...]   Skip months (e.g., --vacation 7 8)
  --fill-chance F       Gap fill probability (default: 0.3)

Flags:
  --no-push             Skip push after commit
  --dry-run             Preview without committing

Examples

# Full green year
python main.py --match --user octocat

# Only fill gaps, don't touch existing days
python main.py --fill-gaps --user octocat --no-push

# Vacation in July and August
python main.py --match --user octocat --vacation 7 8

# Different remote repo
python main.py --match --user octocat --remote https://github.com/octocat/other-repo.git

# Weekdays only
python main.py --start 2025-01-01 --end 2025-12-31 --weekday-min 1 --weekday-max 3

# Hit exactly 500 contributions
python main.py --target 500 --user octocat

How It Works

1. Fetches your contribution calendar via GitHub GraphQL API
2. Analyzes per-day, per-weekday, and monthly patterns
3. Generates a schedule matching your real rhythm with slight variation
4. Creates backdated git commits with realistic timestamps
5. Pushes to your repository (with confirmation)

Commit messages use patterns like tweak data handling, fix commit flow, etc. to sound like real development work.

Important Notes

• Requires GITHUB_TOKEN for API modes (--analyze, --match, --fill-gaps, --target)
• Manual mode (--start/--end) works without any token
• Uses --force push by default — make sure you want to overwrite remote history
• Always use --dry-run first to preview

License

MIT