GitHub Artist 🎨

Create beautiful art in your GitHub contribution graph! Turn your commit history into ASCII art that displays on your GitHub profile.

✨ Features

• 🎨 Create ASCII art in your GitHub contribution graph
• 📅 Automatic date calculation - finds optimal starting points (Sundays for alignment)
• 👀 Live preview - see what your art will look like before creating commits
• 🔤 Extended character set - supports uppercase, lowercase, numbers, and special characters
• 💪 Flexible configuration - customize spacing, commits per day, and more
• 🚀 Modern tooling - uses UV package manager for fast, reliable dependency management
• 📊 Calendar view - visualize your commit pattern week by week
• 🎯 Smart alignment - automatically aligns with GitHub's contribution grid

📦 Installation

Using UV (Recommended)

# Install UV if you haven't already
pip install uv

# Clone the repository
git clone https://github.com/alemazzo/github-artist.git
cd github-artist

# Install the package
uv pip install -e .

Using pip

git clone https://github.com/alemazzo/github-artist.git
cd github-artist
pip install -e .

🚀 Quick Start

Preview your art

# Preview text before creating commits
github-artist preview "HELLO"

Create your art

# Create art in your GitHub contribution graph
github-artist create your-username your-repo "HELLO"

Show supported characters

# List all supported characters
github-artist chars

# Show preview of all characters
github-artist chars --show-all

📖 Usage Guide

Basic Usage

The simplest way to create GitHub art:

github-artist create <username> <repo> <text>

Example:

github-artist create alemazzo my-art-repo "CODE"

Advanced Usage

Customize your art with various options:

github-artist create alemazzo my-art-repo "HELLO" \
  --start-date 2024-01-01 \
  --spacing 2 \
  --commits 3 \
  --protocol ssh \
  --yes

Command Reference

create - Create GitHub art

github-artist create <username> <repo> <text> [OPTIONS]

Arguments:

• username - Your GitHub username
• repo - Repository name (will be cloned if it doesn't exist)
• text - Text to create in the contribution graph

Options:

• --start-date YYYY-MM-DD - Start date (default: auto-calculated to next Sunday)
• --spacing N - Space between letters (default: 1)
• --commits N - Number of commits per day (default: 1, more commits = darker squares)
• --weeks-advance N - Start N weeks from now when auto-calculating (default: 1)
• --protocol {https,ssh} - Clone protocol (default: https)
• --preview - Preview only, don't create commits
• --no-push - Create commits but don't push to GitHub
• -y, --yes - Skip confirmation prompt

Examples:

# Basic usage with auto-calculated start date
github-artist create myusername github-art "HELLO"

# Start on a specific date
github-artist create myusername github-art "2024" --start-date 2024-01-07

# More spacing between letters for better readability
github-artist create myusername github-art "CODE" --spacing 2

# Make darker contributions with more commits per day
github-artist create myusername github-art "HI" --commits 5

# Preview before creating
github-artist create myusername github-art "TEST" --preview

# Skip confirmation prompt (useful for automation)
github-artist create myusername github-art "AUTO" --yes

preview - Preview your art

github-artist preview <text> [OPTIONS]

Arguments:

• text - Text to preview

Options:

• --start-date YYYY-MM-DD - Start date for preview
• --spacing N - Letter spacing
• --commits N - Commits per day
• --weeks-advance N - Weeks in advance

Examples:

# Simple preview
github-artist preview "HELLO WORLD"

# Preview with custom spacing
github-artist preview "CODE" --spacing 2

# Preview with specific start date
github-artist preview "2024" --start-date 2024-01-07

chars - Show supported characters

github-artist chars [OPTIONS]

Options:

• --show-all - Show visual preview of all characters

Examples:

# List supported characters
github-artist chars

# Show preview of each character
github-artist chars --show-all

🎨 Supported Characters

GitHub Artist supports:

• Uppercase letters: A-Z
• Lowercase letters: a-z
• Numbers: 0-9
• Special characters: . , ! ? - _ + = : ; ' " ( ) [ ] / \ @ # & < >
• Symbols: ❤ ★ 👾 (Among Us character)

Use github-artist chars to see the complete list!

📋 Examples

Example 1: Create a simple greeting

github-artist create myusername greeting-repo "HELLO"

Output preview:

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

Example 2: Show your code spirit

github-artist create myusername code-art "CODE" --spacing 2 --commits 3

Example 3: Display the current year

github-artist create myusername year-2024 "2024" --start-date 2024-01-07

Example 4: Create with lowercase for a different style

github-artist create myusername lowercase-art "hello world" --spacing 1

Example 5: Use special characters (Among Us!)

# Create Among Us character art
github-artist create myusername among-us-art "👾" --commits 5

# Preview it first
github-artist preview "👾"

🔧 Configuration

Using Configuration Files

Create a configuration file for reusable settings:

github-artist config --example

This creates github-artist-config.json:

{
  "username": "your-username",
  "repo_name": "github-art",
  "protocol": "https",
  "text": "HELLO",
  "letter_spacing": 1,
  "commits_per_day": 1,
  "auto_calculate_start": true,
  "weeks_in_advance": 1,
  "preview_only": false,
  "auto_push": false
}

🎯 Best Practices

1. Start on Sundays: The auto-calculated start date always picks a Sunday for perfect alignment with GitHub's weekly grid.

2. Preview first: Always use github-artist preview to see how your art will look.

3. Letter spacing: Use --spacing 2 for better readability with longer text.

4. Commits per day: Higher values (3-5) create darker squares, making the art more visible.

5. Repository setup: Create a dedicated repository for your GitHub art to keep it separate from your code projects.

📊 How It Works

1. Character Matrix: Each character is defined as a 7x4 (or similar) binary matrix
2. Date Calculation: Maps the matrix to dates, column by column (each column = 1 week)
3. Commit Creation: Creates commits with backdated timestamps for each active cell
4. GitHub Display: GitHub's contribution graph shows the commits as colored squares

🛠️ Development

Project Structure

github-artist/
├── github_artist/           # Main package
│   ├── __init__.py
│   ├── cli.py              # Command-line interface
│   ├── core/               # Core functionality
│   │   ├── config.py       # Configuration management
│   │   ├── git_ops.py      # Git operations
│   │   └── preview.py      # Preview and visualization
│   ├── data/               # Data files
│   │   └── characters.py   # Character matrix definitions
│   └── utils/              # Utility modules
│       └── dates.py        # Date calculations
├── main.py                 # Entry point
├── pyproject.toml          # Project configuration
└── README.md               # This file

Running Tests

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

Adding New Characters

Edit github_artist/data/characters.py and add your character matrix to CHAR_MATRICES:

"X": [
    [1, 0, 0, 1],
    [1, 0, 0, 1],
    [0, 1, 1, 0],
    [0, 0, 0, 0],
    [0, 1, 1, 0],
    [1, 0, 0, 1],
    [1, 0, 0, 1],
],

⚠️ Important Notes

• GitHub limits: GitHub's contribution graph shows the last year of contributions
• Existing commits: This tool creates new commits and won't affect your existing work
• Repository: Use a dedicated repository for art to avoid cluttering your code projects
• Visibility: Make sure your repository is public for the art to show on your profile
• Time zones: Commits are created with your local timezone

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Areas for Contribution

• Add more character matrices
• Improve character designs
• Add emoji support
• Create themes/templates
• Improve documentation
• Write tests

📝 License

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

👤 Author

alemazzo

• GitHub: @alemazzo

🌟 Acknowledgments

• Inspired by the GitHub contribution graph
• Built with ❤️ and Python
• Powered by UV package manager

📞 Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Documentation

---

Happy Drawing! 🎨

Made with ❤️ by the GitHub community