gitllama 0.1.0

A brief description of your gitLlama project

GitLlama 🦙

Automate git operations with ease

GitLlama is a powerful Python CLI tool that automates common git workflows. Clone repositories, create branches, make changes, commit, and push - all with a single command.

Features

• 🚀 One-command automation - Complete git workflows in a single command
• 🔧 Highly configurable - Customize changes, commit messages, and workflows
• 📁 Modular design - Easy to extend with custom change logic
• 🛡️ Error handling - Robust error handling and rollback capabilities
• 📊 Multiple output formats - JSON and text output support
• 🔍 Dry run mode - Test operations without making actual changes
• 📝 Template system - Predefined change templates for common operations

Installation

From PyPI (Coming Soon)

pip install gitllama

From Source

git clone https://github.com/your-org/gitllama.git
cd gitllama
pip install -e .

Development Installation

git clone https://github.com/your-org/gitllama.git
cd gitllama
pip install -e ".[dev]"

Quick Start

Basic Usage

# Clone a repo, create a branch, make changes, commit and push
gitllama https://github.com/user/repo.git

# Use a custom branch name
gitllama https://github.com/user/repo.git --branch my-feature-branch

# Dry run (no commits or pushes)
gitllama https://github.com/user/repo.git --dry-run

Custom Changes

Create a changes.json file:

{
  "type": "create_file",
  "filename": "hello.txt",
  "content": "Hello from GitLlama!"
}

Then run:

gitllama https://github.com/user/repo.git --changes-file changes.json

Advanced Usage

# Custom commit message
gitllama https://github.com/user/repo.git -m "Add automated documentation"

# Skip pushing to remote
gitllama https://github.com/user/repo.git --no-push

# Verbose output
gitllama https://github.com/user/repo.git --verbose

# JSON output format
gitllama https://github.com/user/repo.git --output-format json

Configuration

Change Types

GitLlama supports several types of changes:

1. Create File

{
  "type": "create_file",
  "filename": "new_file.txt",
  "content": "File content here"
}

2. Modify File

{
  "type": "modify_file",
  "filename": "existing_file.txt",
  "append_content": "\nAppended content"
}

3. Delete File

{
  "type": "delete_file",
  "filename": "file_to_delete.txt"
}

Configuration File

Create ~/.config/gitllama/config.yaml:

git:
  default_branch: "gitllama-automation"
  commit_message_template: "Automated changes by GitLlama"
  auto_push: true

changes:
  default_type: "create_file"
  default_filename: "gitllama_changes.txt"
  default_content: "This file was created by GitLlama automation tool."

logging:
  level: "INFO"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

Change Templates

Use predefined templates for common operations:

# Available templates: add_readme, add_gitignore, modify_readme, add_license_note
gitllama https://github.com/user/repo.git --changes-json '{"template": "add_readme"}'

Python API

You can also use GitLlama programmatically:

from gitllama import GitAutomator

# Basic usage
with GitAutomator() as automator:
    results = automator.run_full_workflow(
        git_url="https://github.com/user/repo.git",
        branch_name="my-branch",
        changes_config={
            "type": "create_file",
            "filename": "api_example.txt",
            "content": "Created via Python API"
        }
    )
    print(f"Success: {results['success']}")

# Advanced usage with custom changes
changes_config = {
    "type": "modify_file",
    "filename": "README.md",
    "append_content": "\n## Added by GitLlama API"
}

with GitAutomator(working_dir="/tmp/gitllama") as automator:
    # Step by step
    repo_path = automator.clone_repository("https://github.com/user/repo.git")
    automator.checkout_branch("api-changes")
    modified_files = automator.make_changes(changes_config)
    commit_hash = automator.commit_changes("API-driven changes")
    push_output = automator.push_changes()

Extending GitLlama

Custom Change Types

Add your own change logic by extending the make_changes method:

from gitllama import GitAutomator

class CustomGitAutomator(GitAutomator):
    def _custom_change_type(self, config):
        """Implement your custom change logic here."""
        # Your implementation
        return ["modified_file.txt"]
    
    def make_changes(self, changes_config=None):
        if changes_config and changes_config.get("type") == "my_custom_type":
            return self._custom_change_type(changes_config)
        return super().make_changes(changes_config)

Custom Workflows

from gitllama import GitAutomator

def my_custom_workflow(git_url, **kwargs):
    with GitAutomator() as automator:
        # Clone repository
        automator.clone_repository(git_url)
        
        # Your custom logic here
        # - Multiple branches
        # - Complex change sequences
        # - Conditional logic
        
        return results

Command Line Reference

usage: gitllama [-h] [--branch BRANCH] [--working-dir WORKING_DIR]
                [--commit-message COMMIT_MESSAGE] [--changes-file CHANGES_FILE]
                [--changes-json CHANGES_JSON] [--dry-run] [--no-push]
                [--verbose] [--quiet] [--config CONFIG]
                [--output-format {text,json}]
                git_url

GitLlama - Automate git operations with ease

positional arguments:
  git_url               Git repository URL to clone and modify

optional arguments:
  -h, --help            show this help message and exit
  --branch BRANCH, -b BRANCH
                        Branch name to create (default: gitllama-automation)
  --working-dir WORKING_DIR, -w WORKING_DIR
                        Working directory for operations (default: temporary directory)
  --commit-message COMMIT_MESSAGE, -m COMMIT_MESSAGE
                        Custom commit message
  --changes-file CHANGES_FILE, -c CHANGES_FILE
                        JSON file containing changes configuration
  --changes-json CHANGES_JSON
                        JSON string containing changes configuration
  --dry-run             Perform all operations except commit and push
  --no-push             Don't push changes to remote repository
  --verbose, -v         Enable verbose logging
  --quiet, -q           Suppress all output except errors
  --config CONFIG       Configuration file path
  --output-format {text,json}
                        Output format (default: text)

Development

Setting up Development Environment

git clone https://github.com/your-org/gitllama.git
cd gitllama
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Running Tests

pytest

Code Quality

# Format code
black src tests

# Lint code
flake8 src tests

# Type checking
mypy src

Pre-commit Hooks

pre-commit install
pre-commit run --all-files

Building and Publishing

Local Build

# Install build dependencies
pip install build twine

# Build the package
python -m build

# Check the build
twine check dist/*

Publishing to PyPI

Test PyPI (Recommended for testing)

# Create account at https://test.pypi.org/
# Create API token in account settings

# Upload to test PyPI
twine upload --repository testpypi dist/*

# Test installation
pip install --index-url https://test.pypi.org/simple/ gitllama

Production PyPI

# Create account at https://pypi.org/
# Create API token in account settings

# Upload to PyPI
twine upload dist/*

# Verify installation
pip install gitllama

GitHub Actions (CI/CD)

Create .github/workflows/ci.yml:

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: [3.8, 3.9, "3.10", "3.11", "3.12"]
    
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v3
      with:
        python-version: ${{ matrix.python-version }}
    
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -e ".[test]"
    
    - name: Run tests
      run: pytest
    
    - name: Run linting
      run: |
        pip install flake8 black mypy
        flake8 src tests
        black --check src tests
        mypy src

  publish:
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
    
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v3
      with:
        python-version: "3.10"
    
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build twine
    
    - name: Build package
      run: python -m build
    
    - name: Publish to PyPI
      env:
        TWINE_USERNAME: __token__
        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
      run: twine upload dist/*

Project Structure

gitllama/
├── src/
│   └── gitllama/
│       ├── __init__.py          # Package initialization
│       ├── cli.py               # Command-line interface
│       ├── git_operations.py    # Core git automation logic
│       └── config.py            # Configuration and logging
├── tests/                       # Test suite
├── docs/                        # Documentation
├── .github/                     # GitHub Actions workflows
├── pyproject.toml              # Package configuration
├── README.md                   # This file
├── LICENSE                     # GPL v3 License
├── .gitignore                  # Git ignore rules
├── .flake8                     # Flake8 configuration
└── .pre-commit-config.yaml     # Pre-commit hooks

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Run the test suite (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Changelog

v0.1.0 (Initial Release)

• Basic git automation functionality
• CLI interface with comprehensive options
• Configuration system with YAML/JSON support
• Change templates system
• Dry run and no-push modes
• JSON and text output formats
• Comprehensive error handling
• Python API for programmatic usage

Roadmap

• Web interface for managing workflows
• Integration with popular CI/CD platforms
• Plugin system for custom change types
• Database storage for workflow history
• Parallel processing for multiple repositories
• Advanced conflict resolution
• Integration with code review tools

Support

• 📖 Documentation
• 🐛 Bug Reports
• 💬 Discussions
• 📧 Email Support

---

Made with ❤️ by the GitLlama team