GitHub Activity Manipulator

A Python command-line tool for programmatically creating and managing GitHub commit history and contribution patterns.

⚠️ Important Notice

This tool is intended for legitimate purposes only, such as:

• Portfolio demonstration and testing
• Educational scenarios
• Personal project management
• Testing Git workflows

Please use responsibly and ethically. Misrepresenting your contribution history may violate GitHub's Terms of Service.

Features

• 🕐 Backdated Commits: Create commits with custom timestamps
• 📊 Pattern Generation: Generate linear, random, wave, or custom activity patterns
• 🎨 Contribution Graph Control: Design your GitHub contribution graph
• 📁 File Content Management: Specify custom file content for commits
• 🔍 Preview Mode: Preview patterns before committing
• ⚙️ Configuration Files: Save and reuse complex patterns with YAML/JSON
• 🚀 CLI Interface: Easy-to-use command-line interface

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/github-activity-manipulator.git
cd github-activity-manipulator

# Install dependencies
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Requirements

• Python 3.8 or higher
• Git installed and accessible from command line

Quick Start

1. Initialize a Repository

github-activity init --path ./my-activity-repo --remote https://github.com/username/repo.git

2. Preview a Pattern

github-activity preview --start-date 2024-01-01 --end-date 2024-12-31 --pattern linear

3. Generate Commits

github-activity generate --start-date 2024-01-01 --end-date 2024-12-31 --pattern wave

4. Push to GitHub

github-activity push --force

Usage

Commands

init - Initialize Repository

Initialize a new repository for activity manipulation:

github-activity init --path <path> [--remote <url>] [--author-name <name>] [--author-email <email>]

generate - Generate Commits

Generate commits based on a pattern:

github-activity generate --start-date <date> --end-date <date> --pattern <type> [options]

Pattern Types:

• linear: Evenly distributed commits
• random: Random distribution within bounds
• wave: Sinusoidal pattern
• custom: Load from configuration file

Options:

• --min-commits: Minimum commits per day (default: 1)
• --max-commits: Maximum commits per day (default: 10)
• --config: Load pattern from configuration file

preview - Preview Pattern

Preview the commit distribution without creating commits:

github-activity preview --start-date <date> --end-date <date> --pattern <type>

push - Push Commits

Push generated commits to remote repository:

github-activity push [--force] [--remote <name>] [--branch <name>]

status - Show Repository Status

Display the current status of a repository:

github-activity status --path <path>

Shows information including:

• Repository validation status
• Total commit count
• Current branch
• Configured remotes
• Latest commit details

Configuration Files

Create a configuration file to save complex patterns:

YAML Example (config.yaml):

repository:
  path: ./my-activity-repo
  remote_url: https://github.com/username/repo.git
  author_name: John Doe
  author_email: john@example.com

pattern:
  type: wave
  start_date: 2024-01-01
  end_date: 2024-12-31
  min_commits_per_day: 1
  max_commits_per_day: 10

file_template: |
  Activity log entry
  Date: {date}
  Commit: {commit_number}

commit_message_template: "Daily activity {date}"

Use the configuration:

github-activity generate --config config.yaml

Development

Setup Development Environment

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=github_activity_manipulator

# Run property-based tests
pytest tests/property/

Project Structure

github-activity-manipulator/
├── github_activity_manipulator/
│   ├── cli/              # Command-line interface
│   ├── services/         # Business logic and orchestration
│   ├── generators/       # Pattern generation
│   ├── config/           # Configuration management
│   └── utils/            # Utility functions
├── tests/
│   ├── unit/             # Unit tests
│   └── property/         # Property-based tests
├── pyproject.toml        # Project configuration
└── README.md

Running Tests

# Run all tests
pytest

# Run unit tests only
pytest tests/unit/

# Run property-based tests only
pytest tests/property/

# Run with verbose output
pytest -v

# Run with coverage report
pytest --cov=github_activity_manipulator --cov-report=html

Security Considerations

• Never commit sensitive data: Avoid including passwords, tokens, or private keys in commits
• Use environment variables: Store GitHub tokens in environment variables, not in code
• Force push warning: Force pushing rewrites history and can cause data loss
• Token security: Use GitHub Personal Access Tokens with minimal required permissions

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Disclaimer

This tool is provided as-is for educational and legitimate use cases. Users are responsible for ensuring their use complies with GitHub's Terms of Service and applicable laws.