GitHub Contribution Writer

A command-line tool that draws words and text on your GitHub contribution graph by generating commits with strategically backdated timestamps.

How It Works

GitHub's contribution graph is a 7-row by 52-column grid representing your commit activity over the past year. Each cell corresponds to a specific day, with the color intensity reflecting the number of contributions made on that day.

This tool maps text characters to a 5x7 pixel font grid, calculates the corresponding calendar dates, and generates Git commits with backdated timestamps. When pushed to GitHub, these commits render as readable text on your contribution graph.

█   █ █████ █     █      ███
█   █ █     █     █     █   █
█   █ █     █     █     █   █
█████ ████  █     █     █   █
█   █ █     █     █     █   █
█   █ █     █     █     █   █
█   █ █████ █████ █████  ███

Installation

From PyPI

pip install github-contribution-writer

From Source

git clone https://github.com/dinesh-git17/github-contribution-writer.git
cd github-contribution-writer
pip install -e .

Usage

Basic Usage

Preview what commits will be generated:

contribution-writer "HELLO" --year 2025 --dry-run

Generate commits for a word:

contribution-writer "HELLO" --year 2025

Command Line Options

Examples

Render text centered on 2025:

contribution-writer "DINESH" --year 2025

Render text at the beginning of the year with maximum intensity:

contribution-writer "HI" --year 2025 --no-center --intensity 10

Preview the output before generating:

contribution-writer "CODE" --year 2025 --dry-run

Pushing to GitHub

After generating commits, push them to a GitHub repository:

# Create a new repository on GitHub first, then:
git remote add origin git@github.com:USERNAME/REPO.git
git branch -M main
git push -u origin main

The contribution graph updates within a few minutes of pushing.

Technical Details

Font Specifications

• Character dimensions: 5 pixels wide, 7 pixels tall
• Character spacing: 1 pixel
• Supported characters: A-Z, 0-9, space
• Maximum text length: approximately 8 characters (limited by 52-week display)

Commit Generation

Commits are created using Git's GIT_AUTHOR_DATE and GIT_COMMITTER_DATE environment variables to set custom timestamps. Each "pixel" in the rendered text corresponds to one or more commits on that date, with the intensity parameter controlling the exact count.

Date Mapping

The contribution graph displays:

• Rows: Days of the week (Sunday at top, Saturday at bottom)
• Columns: Weeks of the year (oldest on left, newest on right)

Text is rendered by mapping each pixel position to a calendar date and generating the appropriate number of commits for that date.

Project Structure

github-contribution-writer/
├── src/
│   └── contribution_writer/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       └── font.py
├── pyproject.toml
├── README.md
└── .gitignore

Requirements

• Python 3.10 or higher
• Git installed and configured
• A GitHub account with a public repository

Limitations

• Only uppercase letters A-Z, digits 0-9, and spaces are supported
• Text longer than 8 characters may not fit within the 52-week display window
• The contribution graph only shows the past year, so backdated commits must fall within this range
• Private repositories do not contribute to the public contribution graph by default

License

MIT License. See LICENSE file for details.

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.