ghops Documentation
Welcome to the documentation for ghops - a powerful, modular CLI tool for managing GitHub repositories at scale.
What is ghops?
ghops
(GitHub Operations) is a robust command-line tool that helps developers and organizations manage multiple GitHub repositories efficiently. Whether you're maintaining dozens of open source projects or managing repositories across a team, ghops
provides automation, insights, and quality tooling to streamline your workflow.
๐ฏ Key Features
๐๏ธ Robust Architecture
- Modular Design: Clean separation of concerns with dedicated command modules
- Extensible: Easy to add new commands and functionality
- Well-Tested: 86% test coverage with 138 comprehensive unit and integration tests
- Error Resilient: Graceful handling of network failures and edge cases
๐ Repository Management
- Clone all your GitHub repositories with a single command
- Update multiple repositories simultaneously with smart conflict resolution
- Track status across all your projects with detailed reporting and progress bars
- Flexible repository discovery with configurable ignore patterns
๐ฆ PyPI Integration
- Automatically detect Python packages from
pyproject.toml
,setup.py
, andsetup.cfg
- Track PyPI publishing status and version information with real-time checking
- Identify outdated packages that need updates
- Performance optimized with optional checking for faster operations
๐ฑ Social Media Automation
- Template-driven content generation for Twitter, LinkedIn, and Mastodon
- Smart sampling of repositories with configurable filters
- Dry-run support to preview posts before publishing
- Rate limiting and posting frequency controls
๐ GitHub Pages Detection
- Multi-method detection for Jekyll, MkDocs, Sphinx, and custom configurations
- Automatically build GitHub Pages URLs from repository metadata
- Track which repositories have active documentation sites
๐ License Management
- GitHub API integration for license template fetching
- Bulk license addition across multiple repositories
- Template customization with automatic placeholder replacement
- Support for all major open source licenses
โ๏ธ Configuration Management
- Support for both JSON and TOML configuration formats
- Environment variable overrides for all settings
- Intelligent merging of defaults, file settings, and overrides
- Built-in configuration template generation
โก Performance & Quality
- Fast operations with real-time progress indicators
- Configurable filtering and performance options
- Rich console output with detailed statistics
- Comprehensive error handling and logging
๐ Quick Start
# Install ghops
pip install ghops
# Generate configuration with examples
ghops config generate
# Clone all your repositories
ghops get
# Check status of all repositories
ghops status -r
# Sample repositories for social media (dry run)
ghops social sample --size 3
ghops social post --dry-run
Use Cases
Open Source Maintainers
- Track all your projects in one place
- Automate social media promotion of releases
- Monitor PyPI package status across projects
- Keep licenses up to date
Development Teams
- Synchronize repository updates across team members
- Track project health and activity
- Maintain consistent licensing and documentation
Individual Developers
- Organize and monitor personal projects
- Automate promotion of your work
- Track your open source contributions
Getting Started
- Installation - Install and configure ghops
- Basic Usage - Learn the core commands
- Configuration - Set up your preferences
- Advanced Features - Explore PyPI and social media features
Documentation Sections
- Usage Guide - Comprehensive command reference and examples
- Future Plans - Roadmap and upcoming features
- Contributing - How to contribute to the project
Recent Updates
Version 0.6.0 ๐
Major Architecture & Quality Overhaul - This release represents a complete transformation of ghops
into a robust, enterprise-ready tool.
๐๏ธ Complete Architecture Redesign
- โ
Modular Command Structure: Separated all commands into dedicated modules (
ghops/commands/
) - โ Clean Separation of Concerns: Utilities, configuration, and API integrations properly separated
- โ Extensible Design: Easy to add new commands and features without breaking existing functionality
- โ Import Optimization: Eliminated circular dependencies and improved startup time
๐งช Comprehensive Testing Framework
- โ 138 Tests: Complete test coverage for all functionality
- โ 86% Code Coverage: Robust testing of edge cases and error conditions
- โ Unit & Integration Tests: Both isolated component testing and end-to-end workflows
- โ Mock Testing: Reliable testing of external API interactions
- โ Error Condition Testing: Comprehensive failure scenario coverage
โก Performance & Reliability Enhancements
- โ
Optional API Checks:
--no-pypi-check
and--no-pages-check
for faster operations - โ Robust Error Handling: Graceful handling of network failures and edge cases
- โ Progress Indicators: Real-time progress bars for long-running operations
- โ Concurrent Operations: Configurable parallel processing for better performance
๐ฑ Advanced Social Media Framework
- โ Template-Driven Content: Customizable post templates for different content types
- โ Multi-Platform Support: Twitter, LinkedIn, and Mastodon integration
- โ Smart Sampling: Configurable repository filtering and random selection
- โ Dry-Run Support: Preview posts before publishing
- โ Rate Limiting: Built-in posting frequency controls and daily limits
โ๏ธ Enhanced Configuration System
- โ Multiple Formats: Support for both JSON and TOML configuration files
- โ Environment Overrides: All settings controllable via environment variables
- โ Intelligent Merging: Proper precedence of defaults, files, and overrides
- โ
Example Generation:
ghops config generate
creates comprehensive examples
๐ Robust License Management
- โ GitHub API Integration: Direct fetching of license templates from GitHub
- โ Template Customization: Automatic placeholder replacement for author details
- โ Bulk Operations: Add licenses to multiple repositories efficiently
- โ All Major Licenses: Support for MIT, Apache, GPL, and many others
๐ Enhanced GitHub Pages Detection
- โ Multi-Method Detection: Scans for Jekyll, MkDocs, Sphinx, and custom configurations
- โ URL Construction: Automatically builds Pages URLs from repository metadata
- โ Documentation Tracking: Monitor which projects have active documentation
๐ฆ Improved PyPI Integration
- โ
Smart Package Detection: Enhanced scanning of
pyproject.toml
,setup.py
,setup.cfg
- โ Version Comparison: Track local vs published version differences
- โ Performance Options: Optional PyPI checking for faster status operations
- โ Error Resilience: Graceful handling of PyPI API issues
Version 0.5.x (Legacy)
- โ PyPI Integration: Automatic detection and tracking of Python packages
- โ Social Media Framework: Generate and post content about your projects
- โ Configuration System: Flexible configuration with example generation
- โ Performance Improvements: Progress bars and faster operations
- โ Enhanced Status: Rich status reporting with PyPI and GitHub Pages info
Community and Support
- GitHub Repository: github.com/queelius/ghops
- Issues and Bug Reports: GitHub Issues
- Feature Requests: GitHub Discussions
License
This project is licensed under the MIT License. See the LICENSE file for details.
Ready to streamline your GitHub workflow? Get started with the installation guide!