🌟 GitHub Commit Generator

Paint your GitHub calendar green with Qqulie, your adorable AI companion! 🎨

---

📖 Table of Contents

• About
• Features
• Getting Started
  • Prerequisites
  • Installation
  • Initial Setup
• Usage
• Configuration
• Important Notes
• Contributing
• Security
• License

---

🎯 About

Qqulie's GitHub Commit Generator is a sophisticated Python CLI tool that creates realistic GitHub contribution patterns. Meet Qqulie, your charming AI companion who guides you through the process of generating backdated commits with beautiful terminal UI and intuitive menus!

Perfect for:

• 🎓 Learning about Git internals
• 🧪 Testing GitHub integrations
• 📊 Creating demonstration repositories
• 🎨 Visualizing contribution patterns

---

✨ Features

• 🤖 Qqulie AI Companion - Interactive and friendly guide (inspired by Astro's Houston)
• 🎨 Beautiful Terminal UI - Rich, colorful interface with icons and panels
• ⚙️ Flexible Configuration - JSON-based settings for complete customization
• 📅 Smart Date Ranges - Configure start dates and working days
• ⏰ Time-Based Commits - Set specific time windows for commits
• 🎲 Random Patterns - Create natural-looking contribution patterns
• 💾 Persistent Config - Save your preferences for future use
• 🚀 Easy to Use - Intuitive menu system, no command-line arguments needed

---

🚀 Getting Started

Prerequisites

• Python 3.7 or higher
• Git installed and configured
• pip (Python package manager)

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/qqulie-commit-generator.git
   cd qqulie-commit-generator

2. Install required dependencies:

   pip install rich

   Or let Qqulie install it automatically on first run! The application will detect missing dependencies and install them for you.

Initial Setup

⚠️ IMPORTANT: Before you start, you MUST change the repository name!

1. Change the project name to something unique:

   # If you haven't already, create a new repository on GitHub
   # Then update your remote URL:
   git remote set-url origin https://github.com/yourusername/your-new-repo-name.git

2. Initialize the repository (if starting fresh):

   mkdir my-awesome-project
   cd my-awesome-project
   git init
   
   # Copy main.py into this directory
   cp /path/to/qqulie-commit-generator/main.py .

3. Create a GitHub repository:

   • Go to GitHub and create a new repository
   • DO NOT initialize it with README, .gitignore, or license
   • Copy the repository URL

4. Link your local repository:

   git remote add origin https://github.com/yourusername/your-repo-name.git

---

💻 Usage

Starting Qqulie

Simply run the main script:

python main.py

Or make it executable:

chmod +x main.py
./main.py

Main Menu Options

When you start Qqulie, you'll see a beautiful menu with these options:

1. 🚀 Generate Commits - Create fake commits based on your configuration
2. ⚙️ Configure Settings - Customize your commit generation parameters
3. 📊 View Current Configuration - See all your current settings
4. 📖 Help & Information - Learn how to use Qqulie
5. 👋 Exit - Say goodbye to Qqulie

Basic Workflow

1. Run the program:

   python main.py

2. Configure your settings (Option 2):

   • Set start date (default: last month)
   • Choose active days (default: Monday-Friday)
   • Set time range (default: 14:00-19:00)
   • Configure commits per day (default: 1-3 random)

3. Generate commits (Option 1):

   • Qqulie will create commits based on your configuration
   • Progress bar shows real-time generation status

4. Push to GitHub:

   git push -f origin main

   ⚠️ Note: Using -f (force) is necessary to push backdated commits

5. Check your GitHub profile! 🎉 Your contribution graph should now display the generated commits!

Example Session

╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║        🌟 Qqulie's GitHub Commit Generator 🌟            ║
║                                                           ║
║          Paint your GitHub calendar green! 🎨            ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

╭────────────── 🎀 Qqulie ───────────────╮
│  Hello there, friend! 🌟 I'm Qqulie,  │
│   your GitHub contribution companion!   │
╰─────────────────────────────────────────╯

Select an option [1/2/3/4/5]: 1

╭────────────── 🎀 Qqulie ───────────────╮
│  Preparing to create 45 commits... 🎯  │
╰─────────────────────────────────────────╯

Creating commits... ━━━━━━━━━━━━━━━ 100%

╭────────────── 🎀 Qqulie ───────────────╮
│ Successfully created 45 commits! 🎊    │
╰─────────────────────────────────────────╯

---

⚙️ Configuration

Configuration is stored in config.json and is automatically created on first run with sensible defaults.

Default Configuration

{
  "start_date": "2024-09-30",
  "days_of_week": [0, 1, 2, 3, 4],
  "time_range": {
    "start_hour": 14,
    "start_minute": 0,
    "end_hour": 19,
    "end_minute": 0
  },
  "commits_per_day": {
    "min": 1,
    "max": 3,
    "random": true
  },
  "random_daily": true,
  "commit_messages": [
    "Update documentation",
    "Fix bug",
    "Add new feature",
    "Refactor code",
    "Improve performance",
    "Update dependencies",
    "Fix typo",
    "Add tests",
    "Update README",
    "Clean up code"
  ]
}

Configuration Options

Setting	Type	Description	Default
start_date	String	Start date for commits (YYYY-MM-DD)	Last month
days_of_week	Array	Active days (0=Mon, 6=Sun)	Mon-Fri [0,1,2,3,4]
time_range	Object	Hours for commits	14:00-19:00
commits_per_day.min	Integer	Minimum commits per day	1
commits_per_day.max	Integer	Maximum commits per day	3
commits_per_day.random	Boolean	Random commits per day	true
random_daily	Boolean	Randomize each day	true
commit_messages	Array	Pool of commit messages	10 default messages

Customizing via Menu

You can change all settings through Qqulie's interactive menu (Option 2):

• Start Date: Choose when to begin generating commits
• Days of Week: Select which days should have commits
• Time Range: Set the hours during which commits are created
• Commits Per Day: Define minimum and maximum commits
• Random Toggle: Enable/disable randomization

Manual Configuration

You can also edit config.json directly before running the program:

nano config.json  # or vim, or your favorite editor

---

⚠️ Important Notes

Ethical Usage

This tool is designed for educational and legitimate purposes only:

• ✅ Learning about Git internals
• ✅ Testing and development
• ✅ Creating demo repositories
• ✅ Personal projects and experimentation
• ❌ DO NOT use to misrepresent your contribution activity
• ❌ DO NOT use for deceptive purposes

Technical Considerations

• Repository Name: Always change the repository name before starting
• Force Push: You'll need to use git push -f to push backdated commits
• Existing Commits: This tool works best on fresh repositories
• Rate Limits: GitHub may rate-limit if you push too many commits at once
• Contribution Graph: It may take a few minutes for GitHub to update your contribution graph

Best Practices

1. Test First: Try on a test repository before using on important projects
2. Backup: Always backup important repositories before running
3. Review Config: Check your configuration before generating commits
4. Commit Messages: Customize the commit message pool for more realistic patterns
5. Time Zones: The tool uses your local timezone

---

🤝 Contributing

We love contributions! Please see our CONTRIBUTING.md file for details on how to help make Qqulie even better!

Quick start:

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

---

🔒 Security

Security is important to us. If you discover a security vulnerability, please see our SECURITY.md file for information on how to report it responsibly.

---

📄 License

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

---

🙏 Acknowledgments

• Rich Library - For the beautiful terminal UI
• Astro's Houston - Inspiration for Qqulie's personality
• Open Source Community - For all the amazing tools and libraries

---

📞 Support

Having issues? Here's how to get help:

1. Check the Help Menu in the application (Option 4)
2. Review this README thoroughly
3. Check existing GitHub Issues
4. Create a new issue with detailed information

---

🌟 Star History

If you find this project helpful, please consider giving it a star! ⭐

---

Made with ❤️ by the Qqulie Team

Happy Committing! 🚀