A fully automated Python script that runs in Google Colab or as a standalone CLI to generate backdated commits and customize your GitHub contribution graph.

---

Warning

This script creates backdated commits to artificially populate your GitHub contribution graph.

• Use responsibly. Artificially inflating contributions may be viewed negatively by potential employers or collaborators who review your profile.
• You need a GitHub Personal Access Token (classic) with repo scope to push commits.
• The script force-pushes to your repository, overwriting its commit history. Use a dedicated, empty repository to avoid losing important work.
• This tool is intended for educational purposes and personal experimentation only.

---

📖 Table of Contents

• What is This Tool?
• Why Use This Method?
• Prerequisites
• Step-by-Step Guide
• Configuration Options
  • Random Commit Pattern
  • 🎨 Custom Text Mode
• How It Works
• Troubleshooting
• Credits & Acknowledgments
• License & Disclaimer

---

🎯 What is This Tool?

This tool generates backdated commits over a specified date range, allowing you to customize the appearance of your GitHub contribution graph.

Two Modes Available:

1. Random Commit Pattern – Creates a gradually increasing density of commits (ramp‑up effect) over a date range.
2. 🎨 Custom Text Mode – Draws words like HELLO or GITHUB directly onto your contribution graph using a 5×7 pixel font. Each letter is mapped to specific days, creating a clean, pixel‑art style message.

Common Use Cases:

• Experimenting with Git's backdating capabilities for educational purposes.
• Creating a specific visual pattern or message on your contribution graph for fun.
• Understanding how GitHub's contribution tracking works.

Note

This tool does not unlock any GitHub achievement. It is purely a customization utility.

---

✅ Why Use This Method?

Feature	Benefit
☁️ No PC Required	Runs entirely in Google Colab (cloud‑based). Works on any device with a browser.
📅 Flexible Date Range	Specify any start and end date for your commit pattern.
📈 Customizable Density	Control the minimum and maximum commits per day.
🎨 Draw Text	Spell words using the contribution graph's green squares (uppercase, lowercase, digits, symbols).
🔁 Fully Automated	Clones, commits, and force-pushes automatically.
🔍 Dry-Run Preview	See the pattern before committing — no surprises.
⏫ Intermediate Push	Push every N days to avoid losing progress on long runs.
📊 Progress Bar	Visual progress indicator during generation.
📦 Minimal Dependencies	Only uses GitPython and standard libraries.

---

🧰 Prerequisites

Before you begin, make sure you have:

1. A GitHub account.
2. An empty or dedicated repository where you have write access (create a new one to avoid losing real work).
3. A GitHub Personal Access Token (Classic) with repo scope.

🔐 How to Get a Personal Access Token

1. Go to Settings → Developer settings → Personal access tokens → Tokens (classic).
2. Click Generate new token (classic).
3. Give it a name (e.g., Commit Graph Generator).
4. Under Select scopes, check repo (this grants full control of your repositories).
5. Click Generate token and copy the token immediately — you won't see it again.

🔒 Keep this token secret. Never share it with anyone or upload it to a public place.

---

📥 How to Deploy

1️⃣ One‑Click Colab

2️⃣ Fill in the Configuration Form

Inside the Colab notebook, you'll find a single configuration cell with form fields. Choose between the Random Pattern (default) and Custom Text Mode by toggling USE_CUSTOM_TEXT.

3️⃣ Run the Notebook

Click Runtime → Run all (or press Ctrl+F9). The notebook will:

• Install GitPython
• Clone your repository
• Generate backdated commits according to your chosen mode
• Force-push the new history to GitHub

You'll see real‑time output like:

📅 Commit Graph Generator for user 'Shineii86'
Repository: commit-graph-demo

🎨 Drawing text: "HELLO"
   Starting 0 week(s) after 2026-04-01
   3 commit(s) per pixel

📌 2026-04-01: 9 commits
📌 2026-04-02: 6 commits
...
✅ Created commits on 21 days to spell "HELLO".

⏫ Pushing to remote...
✅ Force push complete.

✨ Done! Your contribution graph will update shortly.
📊 Visit: https://github.com/Shineii86

4️⃣ View Your Contribution Graph

1. Go to your GitHub profile: https://github.com/YOUR_USERNAME
2. The contribution graph will update within a few minutes to reflect the new commits.

---

💻 Standalone CLI (No Colab Required)

You can run CommitGraph directly from the command line on any machine with Python 3.8+.

Install

git clone https://github.com/Shineii86/CommitGraph.git
cd CommitGraph
pip install -r requirements.txt

Usage

# Custom text mode
python commitgraph.py --token ghp_xxx --repo my-demo --text HELLO

# Random pattern mode
python commitgraph.py --token ghp_xxx --repo my-demo --start 2026-04-01 --end 2026-04-15

# Dry run (preview only)
python commitgraph.py --token ghp_xxx --repo my-demo --text HI --dry-run

# Full options
python commitgraph.py \
  --token ghp_xxx \
  --username MyUser \
  --repo my-demo \
  --text "HELLO WORLD" \
  --commits-per-pixel 4 \
  --offset-weeks 2 \
  --push-every 7

CLI Options

Flag	Description	Default
--token	GitHub Personal Access Token (required)	—
--repo	Target repository name (required)	—
--username	GitHub username	Shineii86
--email	Noreply email (auto-detected if omitted)	auto
--text	Text to draw (enables custom text mode)	—
--random	Use random pattern mode	default
--offset-weeks	Weeks to skip before drawing text	0
--commits-per-pixel	Commits per pixel (higher = darker)	3
--start	Start date (YYYY-MM-DD)	2026-04-01
--end	End date (YYYY-MM-DD)	2026-04-15
--min-start	Min commits/day at start	0
--max-start	Max commits/day at start	5
--min-end	Min commits/day at end	5
--max-end	Max commits/day at end	10
--no-force-push	Don't force push	—
--dry-run	Preview only, no commits created	—
--push-every	Intermediate push every N days	0

---

⚙️ Configuration Options

All parameters are adjustable directly in the Colab form. The form is divided into three sections: Common Settings, Custom Text Mode, and Random Pattern Mode.

Common Settings (Always Required)

Variable	Description	Example Value
GITHUB_USERNAME	Your GitHub handle	"Shineii86"
GITHUB_TOKEN	Personal Access Token (keep secret!)	"ghp_abc123..."
GITHUB_EMAIL	Your noreply email (auto-detected from token if left blank)	"123456+user@users.noreply.github.com"
REPO_NAME	Target repository (must exist under your account)	"commit-graph-demo"
FORCE_PUSH	Overwrite remote history (required)	True
DRY_RUN	Preview mode — shows pattern without creating commits	False
INTERMEDIATE_PUSH_DAYS	Push every N days during long runs (0 = push only at end)	0
USE_CUSTOM_TEXT	Toggle between Custom Text (True) and Random Pattern (False).	False

---

📈 Random Commit Pattern

Used when USE_CUSTOM_TEXT = False. Creates commits with a linear ramp‑up in density.

Parameter	Default	Description
START_DATE	"2026-04-01"	First date to create commits.
END_DATE	"2026-04-15"	Last date to create commits.
MIN_COMMITS_START	0	Minimum commits on the first day.
MAX_COMMITS_START	5	Maximum commits on the first day.
MIN_COMMITS_END	5	Minimum commits on the last day.
MAX_COMMITS_END	10	Maximum commits on the last day.

Commit Density Logic
The script linearly interpolates the commit count ranges from start to end. For a constant density, set the start and end min/max values equal.

---

🎨 Custom Text Mode

Used when USE_CUSTOM_TEXT = True. Draws a word or phrase using the contribution graph as a canvas.

Parameter	Default	Description
CUSTOM_TEXT	"HELLO"	The word to draw. Supported characters: uppercase A-Z, digits 0-9, space, ., !, ?.
START_DATE	"2026-04-01"	The Sunday of the week where drawing begins (the script auto‑adjusts to Sunday if a different day is given).
TEXT_START_OFFSET_WEEKS	0	Number of empty weeks to skip after START_DATE before drawing the text (shifts the text to the right).
COMMITS_PER_PIXEL	3	How many commits to create for each "on" pixel. Higher numbers = darker green squares (max shade usually at 4–5 commits).

How Custom Text Works

• Each character is rendered using a 5×7 pixel font. The top row corresponds to Sunday, the bottom row to Saturday.
• Characters are placed side‑by‑side with a 1‑column gap.
• The script calculates the exact days that need commits and pushes them with backdated timestamps.

Example: Drawing "HI"

Setting	Value
CUSTOM_TEXT	"HI"
START_DATE	"2026-04-05" (a Sunday)
COMMITS_PER_PIXEL	3

The result on your graph:

Sun Mon Tue Wed Thu Fri Sat
  █  █              █  █     ← 'H' (first week)
  █  █              █  █
  █  █              █  █
  ████              ████
  █  █              █  █
  █  █              █  █
  █  █              █  █

Sun Mon Tue Wed Thu Fri Sat
  ████                ██     ← 'I' (second week)
   ██                 ██
   ██                 ██
   ██                 ██
   ██                 ██
   ██                 ██
  ████                ██

💡 Tip: Because GitHub contribution weeks start on Sunday, choose a START_DATE that is a Sunday for predictable alignment.

---

📁 Project Structure

CommitGraph/
├── commitgraph.py          # Standalone CLI entry point
├── requirements.txt        # Python dependencies
├── src/
│   ├── __init__.py         # Package metadata
│   ├── config.py           # Configuration dataclasses & validation
│   ├── font.py             # 5×7 pixel font bitmaps (A-Z, a-z, 0-9, symbols)
│   ├── generator.py        # Core commit generation engine
│   └── utils.py            # Progress bars, estimation, graph preview
├── notebooks/
│   └── CommitGraph.ipynb   # Google Colab notebook (uses src/ modules)
├── images/
│   └── CommitGraph.png     # Banner image
├── CHANGELOG.md
├── README.md
└── LICENSE

---

🔬 How It Works (Technical Overview)

The script performs the following steps:

1. Clones the Repository: Uses your Personal Access Token to clone the specified repository into the Colab environment.
2. Configures Git User: Sets the commit author and email to your GitHub identity.
3. Generates Commits:
   • Random Mode: Iterates through each day, calculates a random number of commits, and creates them with backdated timestamps.
   • Custom Text Mode: Converts the input string to pixel coordinates, groups them by day, and creates the required number of commits per day.
4. Force Pushes: Overwrites the remote repository's history with the new commit chain. This is necessary because backdating changes the commit timestamps, altering the existing history.

⚠️ Force push is destructive. It replaces the entire commit history on the remote branch. Always use a dedicated repository.

---

🆘 Troubleshooting

Issue	Solution
github.GithubException.BadCredentialsException	Your Personal Access Token is incorrect or expired. Generate a new one.
Permission denied or Authentication failed	Ensure your token has the repo scope checked.
Repository not found	Verify the repository name is correct and exists under your account.
Contribution graph not updating	Wait a few minutes—GitHub's graph updates are not instant. Also ensure the repository is public or that you've enabled private contributions in your profile settings.
GitCommandError: cannot push	Make sure FORCE_PUSH is set to True. Backdated commits require force-pushing.
Commits not showing on contribution graph	Verify GITHUB_EMAIL matches your noreply email (ID+username@users.noreply.github.com). The script auto-detects this from your token, but if it fails, set it manually at https://github.com/settings/emails.
Commits appear on wrong dates	Verify the date format is YYYY-MM-DD. For Custom Text mode, ensure START_DATE is a Sunday or let the script auto‑adjust.
Custom text characters are missing or misaligned	Only uppercase letters, digits, and the symbols . ! ? are supported. The script will skip unsupported characters.

---

📄 License & Disclaimer

This project is licensed under the MIT License – see the LICENSE file for details.

Warning

This script is intended for educational purposes and personal experimentation only. Artificially inflating your contribution graph may be viewed negatively by potential employers or collaborators. The author is not responsible for any consequences arising from misuse of this tool, including but not limited to damage to professional reputation or violation of platform terms.

---

🔗 Quick Links

• Google Colab
• GitHub Personal Access Tokens
• GitPython Documentation

---

💕 Loved My Work?

🚨 Follow me on GitHub

⭐ Give a star to this project

For inquiries or collaborations

^{Copyright © 2026 Shinei Nouzen All Rights Reserved}