# ghops
[](https://pypi.org/project/ghops/)
[](https://pypi.org/project/ghops/)
[](https://github.com/queelius/ghops)
[](https://github.com/queelius/ghops)
[](https://github.com/queelius/ghops/blob/main/LICENSE)
A powerful, local-first git project management system that helps developers manage the full lifecycle of their projects across multiple platforms - from local development through hosting, distribution, documentation, and promotion. Your local git repositories are the ground truth, and remote platforms (GitHub, GitLab, PyPI, etc.) are services that enrich and distribute your projects.
## ✨ Features
### 🎯 **Core Philosophy**
- **Local-First**: Your local git repositories are the source of truth
- **JSONL by Default**: All commands output newline-delimited JSON for Unix pipeline composition
- **Tag-Based Organization**: Powerful tagging system with implicit tags from metadata
- **Query Language**: Fuzzy search with simple boolean expressions
- **Multi-Platform**: Works with GitHub, GitLab, Bitbucket, and more (coming soon)
### 🏗️ **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
- **Streaming Output**: Memory-efficient processing of large repository collections
### 📦 **Repository Management**
- **Multi-Repository Operations**: Clone, update, and monitor multiple repositories efficiently
- **Intelligent Sync**: Smart pull with rebase, conflict detection, and resolution strategies
- **Progress Tracking**: Real-time progress bars and detailed operation summaries
- **Flexible Discovery**: Recursive repository scanning with configurable ignore patterns
### 📄 **License Management**
- **GitHub Integration**: Fetch license templates directly from GitHub API
- **Bulk Operations**: Add licenses to multiple repositories at once
- **Template Customization**: Automatic placeholder replacement for author details
- **Multiple Formats**: Support for all major open source licenses
### 🌐 **GitHub Pages Detection**
- **Multi-Method Detection**: Scans for Jekyll, MkDocs, Sphinx, and custom configurations
- **URL Construction**: Automatically builds GitHub Pages URLs from repository metadata
- **Documentation Tracking**: Monitor which projects have active documentation sites
### 📱 **Social Media Automation**
- **Content Generation**: Template-driven post creation for Twitter, LinkedIn, and Mastodon
- **Smart Sampling**: Random repository selection with configurable filters
- **Dry Run Support**: Preview posts before publishing
- **Rate Limiting**: Built-in posting frequency controls and daily limits
### ⚙️ **Configuration Management**
- **Flexible Formats**: Support for both JSON and TOML configuration files
- **Environment Overrides**: All settings can be controlled via environment variables
- **Default Merging**: Intelligent combination of defaults, file settings, and overrides
- **Example Generation**: Built-in config template generation
### 🤖 **Automated Service Mode**
- **Scheduled Posting**: Run ghops as a background service for automated social media posting
- **Multi-Directory Support**: Configure multiple repository locations with glob pattern support
- **Periodic Reporting**: Generate comprehensive repository status reports
- **Email Notifications**: Automated email alerts and daily summaries
- **Error Monitoring**: Built-in error detection and email alerts
### 🔍 **Repository Discovery & Organization**
- **Tag-Based Catalogs**: Organize repos with explicit tags and auto-generated implicit tags
- **Powerful Query Language**: Find repos with fuzzy matching: `ghops query "language ~= 'pyton'"`
- **Metadata Store**: Local database of all repository information for fast queries
- **Implicit Tags**: Automatic tags like `repo:name`, `lang:python`, `has:docs`, `dir:parent`
### 🛡️ **Repository Auditing**
- **Comprehensive Health Checks**: Audit repos for licenses, READMEs, security issues, and more
- **Auto-Fix Capabilities**: Automatically fix common issues with `--fix` flag
- **Security Scanning**: Detect hardcoded secrets and security vulnerabilities
- **Dependency Auditing**: Check for missing or outdated dependency management
- **Documentation Health**: Verify documentation setup and configuration
### 📄 **Portfolio Export**
- **Multiple Formats**: Export to Markdown, Hugo, HTML, JSON, CSV, LaTeX, and PDF
- **Interactive HTML**: Generated HTML includes live search, filtering, and sorting
- **Hugo Integration**: Create complete Hugo site structure with taxonomies
- **Grouping & Organization**: Group exports by language, directory, or custom tags
- **Component-Based System**: Modular export components with customization hooks
- **Format Flexibility**: Support for CSV, TSV, YAML output with field projection
### 📚 **Documentation Management**
- **Multi-Tool Support**: Works with MkDocs, Sphinx, Jekyll, Hugo, and more
- **Status Checking**: See documentation health across all repos
- **Build & Serve**: Build and preview documentation locally
- **Deploy to GitHub Pages**: One-command deployment to GitHub Pages
- **Bulk Operations**: Manage docs across multiple repos simultaneously
## 🚀 Installation
You can install `ghops` via `pip`:
```bash
pip install ghops
```
Or from source:
```bash
git clone https://github.com/queelius/ghops.git
cd ghops
make install
```
## ⚡ Quick Start
```bash
# Generate a configuration file with examples
ghops config generate
# Clone all your repos
ghops get
# Update all repos in the current directory
ghops update -r
# Check the status of all repos (includes PyPI and GitHub Pages info)
ghops status -r
# Quick status check without PyPI detection
ghops status --no-pypi-check
# Sample repositories for social media posting
ghops social sample --size 3
# Create social media posts (dry run)
ghops social post --dry-run
```
### New Command Examples
```bash
# Repository Organization & Discovery
ghops catalog add awesome-project python ml research # Tag a repo
ghops catalog show -t python # Show Python repos
ghops query "stars > 10 and language ~= 'python'" # Fuzzy query
ghops list -t "dir:work" -t "lang:python" # Filter by multiple tags
# Repository Auditing
ghops audit all -t "lang:python" --pretty # Audit all Python repos
ghops audit security --fix # Fix security issues
ghops audit license --fix --type MIT # Add missing licenses
ghops audit deps -q "has:package.json" # Audit JS dependencies
# Documentation Management
ghops docs status -t "has:docs" # Check docs status
ghops docs build -t "tool:mkdocs" # Build MkDocs projects
ghops docs serve repo:myproject # Preview docs locally
ghops docs deploy -t "lang:python" --dry-run # Deploy to GitHub Pages
# Portfolio Export
ghops export generate -f hugo --group-by lang # Export for Hugo site
ghops export generate -f html -o ./portfolio # Interactive HTML portfolio
ghops export generate -q "stars > 5" -f pdf # Export popular repos to PDF
ghops export generate -t "dir:work" -f markdown # Work portfolio in Markdown
ghops export generate -f csv --fields name,language,stars # CSV with specific fields
ghops export generate -f yaml --include-readme # YAML with README content
# Metadata Management
ghops metadata refresh --github # Update from GitHub
ghops metadata show repo:ghops --pretty # Show repo metadata
ghops metadata stats # Repository statistics
```
### JSONL Output & Unix Pipelines
All ghops commands output newline-delimited JSON (JSONL) by default, making them perfect for Unix pipelines. You can also set the output format globally with the `GHOPS_FORMAT` environment variable:
```bash
# Set default output format
export GHOPS_FORMAT=csv # or json, yaml, tsv
# Find repositories with uncommitted changes
ghops status | jq 'select(.status.uncommitted_changes == true)'
# Count repositories by language
ghops list | jq -s 'group_by(.language) | map({language: .[0].language, count: length})'
# Export repository URLs to a file
ghops list | jq -r '.remote.url' > repo-urls.txt
# Find outdated PyPI packages
ghops status | jq 'select(.package.outdated == true)'
# Audit repositories and get failed checks
ghops audit all | jq 'select(.status == "fail") | {name, checks: .checks | to_entries | map(select(.value.status == "fail")) | map(.key)}'
# Chain commands - audit Python repos without docs
ghops list -t "lang:python" | jq -r '.path' | xargs -I {} ghops audit docs {} | jq 'select(.status == "fail")'
```
## 📋 Commands
### Repository Operations
- **`ghops get [options]`** - Clone all repositories from your GitHub account
- `--users USER [USER ...]` - Specify GitHub usernames to clone from
- `--dir DIRECTORY` - Target directory for cloning
- `--ignore REPO [REPO ...]` - Skip specific repositories
- `--license LICENSE` - Add license files during cloning
- `--dry-run` - Preview operations without making changes
- **`ghops update [options]`** - Update local repositories
- `-r, --recursive` - Search for repositories recursively
- `--auto-commit` - Commit changes before pulling
- `--commit-message MESSAGE` - Custom commit message
- `--conflicts {abort,ours,theirs}` - Conflict resolution strategy
- `--prompt` - Ask before pushing changes
- `--license LICENSE` - Add/update license files during update
- **`ghops status [options]`** - Comprehensive repository status
- `-r, --recursive` - Search recursively
- `--pretty` - Display as formatted table (default: JSONL)
- `--no-pypi-check` - Skip PyPI status checks (faster)
- `--no-pages-check` - Skip GitHub Pages detection
- `--summary` - Show summary statistics
### Configuration Management
- **`ghops config generate`** - Create example configuration file
- **`ghops config show`** - Display current configuration with all merges applied
### Repository Organization & Discovery
- **`ghops catalog add REPO TAG [TAG ...]`** - Add tags to a repository
- **`ghops catalog remove REPO TAG [TAG ...]`** - Remove tags from a repository
- **`ghops catalog show [options]`** - Show tagged repositories
- `-t, --tag TAG` - Filter by specific tags
- `--all-tags` - Require all specified tags
- `--pretty` - Display as formatted table
- **`ghops query EXPRESSION`** - Query repositories with fuzzy matching
- Supports: `==`, `!=`, `~=`, `>`, `<`, `contains`, `in`
- Examples: `"stars > 10"`, `"language ~= 'pyton'"`, `"'ml' in topics"`
- **`ghops list [options]`** - List repositories with filtering
- `-t, --tag TAG` - Filter by tags
- `-q, --query EXPR` - Filter by query expression
- `--pretty` - Display as formatted table
### Repository Auditing
- **`ghops audit COMMAND [options]`** - Comprehensive repository health checks
- **`all`** - Run all audit checks
- **`license`** - Check for license files
- **`readme`** - Check for README files
- **`security`** - Scan for security issues
- **`deps`** - Audit dependencies
- **`docs`** - Check documentation setup
- **`gitignore`** - Verify .gitignore files
Common options:
- `--fix` - Automatically fix issues found
- `-t, --tag TAG` - Filter repositories by tag
- `-q, --query EXPR` - Filter by query expression
- `--dry-run` - Preview fixes without applying
### Documentation Management
- **`ghops docs status [options]`** - Check documentation status
- **`ghops docs build [options]`** - Build documentation
- **`ghops docs serve [options]`** - Preview documentation locally
- **`ghops docs deploy [options]`** - Deploy to GitHub Pages
All support tag/query filtering with `-t` and `-q` options
### Portfolio Export
- **`ghops export generate [options]`** - Export repository portfolios
- `-f, --format FORMAT` - Output format: markdown, hugo, html, json, csv, pdf, latex
- `-o, --output DIR` - Output directory
- `--single-file` - Export to single file
- `--group-by PREFIX` - Group by tag prefix (e.g., "dir", "lang")
- `--template NAME` - Use custom template
- `-t, --tag TAG` - Filter by tags
- `-q, --query EXPR` - Filter by query
### Metadata Management
- **`ghops metadata refresh [options]`** - Update repository metadata
- `--github` - Fetch from GitHub API
- `--path PATH` - Refresh specific repository
- `--max-age AGE` - Only refresh if older than (e.g., "7d", "12h")
- **`ghops metadata show REPO`** - Display repository metadata
- Accepts repository path or tag selector (e.g., `repo:ghops`)
- **`ghops metadata stats`** - Show metadata statistics
### Social Media Automation
- **`ghops social create [options]`** - Generate social media posts
- **`ghops social post [options]`** - Generate and post content
- `-t, --tag TAG` - Filter repositories by tag
- `-q, --query EXPR` - Filter by query expression
- `--sample-size N` - Number of repos to sample
- `--dry-run` - Preview without posting
### Service Mode
- **`ghops service start`** - Start automated posting service
- `--dry-run` - Run service in preview mode
- **`ghops service run-once`** - Execute single posting cycle
- `--dry-run` - Preview what would be posted
## 🔧 Advanced Configuration
`ghops` uses a configuration file located at `~/.ghopsrc` (JSON or TOML format). Set custom location with `GHOPS_CONFIG` environment variable.
### Key Configuration Sections
#### Repository Directories
```toml
[general]
# Multiple directories with glob pattern support
repository_directories = [
"~/github", # Direct path
"~/projects/*/repos", # Glob pattern
"~/work/code" # Another direct path
]
github_username = "your_username"
```
#### Service Configuration
```toml
[service]
enabled = true # Enable scheduled posting service
interval_minutes = 120 # Minutes between posting cycles
start_time = "09:00" # Preferred start time
[service.reporting]
enabled = true # Enable periodic reports
interval_hours = 24 # Hours between reports
include_stats = true # Include operation statistics
include_status = true # Include repository status
include_recent_activity = true # Include recent activity
[service.notifications.email]
enabled = true # Enable email notifications
smtp_server = "smtp.gmail.com" # SMTP server
smtp_port = 587 # SMTP port
username = "your@email.com" # Email username
password = "app_password" # Email password/app password
from_email = "your@email.com" # From address
to_email = "your@email.com" # To address
daily_summary = true # Send daily reports
error_alerts = true # Send error alerts
```
#### Social Media Platforms
```toml
[social_media.platforms.twitter]
enabled = false
api_key = "your_api_key"
api_secret = "your_api_secret"
access_token = "your_access_token"
access_token_secret = "your_access_token_secret"
[social_media.platforms.twitter.templates]
pypi_release = "🚀 New release: {package_name} v{version} is now available on PyPI! {pypi_url} #{package_name} #python #opensource"
github_pages = "📖 Updated documentation for {repo_name}: {pages_url} #docs #opensource"
random_highlight = "✨ Working on {repo_name}: {description} {repo_url} #{language} #coding"
```
#### Posting Rules
```toml
[social_media.posting]
random_sample_size = 3 # Number of repos to randomly highlight
daily_limit = 5 # Maximum posts per day
min_hours_between_posts = 2 # Minimum time between posts
exclude_private = true # Don't post about private repos
exclude_forks = true # Don't post about forked repos
```
## 💡 Examples
### Check Repository Status
```bash
# Full status with PyPI and GitHub Pages (JSONL output)
ghops status -r
# Pretty-print table format for human reading
ghops status -r --pretty
# Fast status check
ghops status --no-pypi-check
# Filter and transform with jq
ghops status | jq 'select(.license.type == "MIT")'
```
### Social Media Promotion
```bash
# See what repositories would be selected
ghops social sample --size 5
# Preview social media posts
ghops social post --dry-run --size 3
# Actually post (requires configured API credentials)
ghops social post --size 2
```
### Repository Management
```bash
# Clone all your repositories
ghops get --dir ~/projects
# Update repositories recursively
ghops update -r --dir ~/projects
# Add MIT license to repositories during update
ghops update -r --license mit --license-name "Your Name" --license-email "you@example.com"
```
### Service Mode Operations
```bash
# Start automated service (background posting and reporting)
ghops service start
# Test service with dry-run
ghops service start --dry-run
# Run single cycle for testing
ghops service run-once --dry-run
# Create systemd service (see examples/ghops.service)
sudo systemctl enable ghops
sudo systemctl start ghops
```
### Multi-Directory Management
```bash
# Configure multiple repository locations
ghops config generate # Edit to add repository_directories
# Status across all configured directories
ghops status
# Update repositories in all configured locations
ghops update -r
```
## ⚡ Performance & Advanced Usage
### Performance Options
- Use `--no-pypi-check` for faster status checks when you don't need PyPI information
- Use `--no-pages-check` to skip GitHub Pages detection
- Configure `max_concurrent_operations` in config for better performance
## 🧪 Testing & Quality
- **138 comprehensive tests** covering all major functionality
- **86% test coverage** with unit and integration testing
- **Continuous integration** with automated testing
- **Error handling** for network failures and edge cases
- **Performance benchmarks** for large repository sets
- **Mock testing** for reliable external API testing
### Test Coverage by Module
- **CLI & Commands**: Complete argument parsing and execution testing
- **Configuration System**: All file formats and environment override scenarios
- **PyPI Integration**: Package detection, API calls, and error conditions
- **Social Media**: Content generation, platform integration, and rate limiting
- **License Management**: GitHub API integration and template processing
- **Status Reporting**: Repository scanning, progress tracking, and output formatting
## 🏗️ Architecture
`ghops` follows a clean, modular architecture designed for maintainability and extensibility:
```text
ghops/
├── cli.py # Main CLI entry point with click
├── __main__.py # Python module execution entry
├── commands/ # Modular command implementations
│ ├── get.py # Repository cloning logic
│ ├── update.py # Repository updating and syncing
│ ├── status.py # Status reporting and analytics
│ └── license.py # License management operations
├── config.py # Configuration loading and merging
├── utils.py # Shared utilities and helpers
├── pypi.py # PyPI package detection and API
└── social.py # Social media content generation
```
### Design Principles
- **Separation of Concerns**: Each module has a single, well-defined responsibility
- **Error Resilience**: Graceful handling of network failures and edge cases
- **Performance**: Optional API checks and concurrent operations
- **Extensibility**: Easy to add new commands and features
- **Testability**: Comprehensive test coverage with mocking for external services
## 🤝 Contributing
Contributions are welcome! Please see the [Contributing Guide](contributing.md) for more details.
## 📄 License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
© 2025 [Alex Towell](https://github.com/queelius)
Raw data
{
"_id": null,
"home_page": null,
"name": "ghops",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "automation, cli, devops, git, github",
"author": null,
"author_email": "Alex Towell <lex@metafunctor.com>",
"download_url": "https://files.pythonhosted.org/packages/96/dc/60ffcab6fa23b3ef69d01e453fb035ad08db5123331057da608a941b838c/ghops-0.7.0.tar.gz",
"platform": null,
"description": "# ghops\n\n[](https://pypi.org/project/ghops/)\n[](https://pypi.org/project/ghops/)\n[](https://github.com/queelius/ghops)\n[](https://github.com/queelius/ghops)\n[](https://github.com/queelius/ghops/blob/main/LICENSE)\n\nA powerful, local-first git project management system that helps developers manage the full lifecycle of their projects across multiple platforms - from local development through hosting, distribution, documentation, and promotion. Your local git repositories are the ground truth, and remote platforms (GitHub, GitLab, PyPI, etc.) are services that enrich and distribute your projects.\n\n## \u2728 Features\n\n### \ud83c\udfaf **Core Philosophy**\n\n- **Local-First**: Your local git repositories are the source of truth\n- **JSONL by Default**: All commands output newline-delimited JSON for Unix pipeline composition\n- **Tag-Based Organization**: Powerful tagging system with implicit tags from metadata\n- **Query Language**: Fuzzy search with simple boolean expressions\n- **Multi-Platform**: Works with GitHub, GitLab, Bitbucket, and more (coming soon)\n\n### \ud83c\udfd7\ufe0f **Robust Architecture**\n\n- **Modular Design**: Clean separation of concerns with dedicated command modules\n- **Extensible**: Easy to add new commands and functionality \n- **Well-Tested**: 86% test coverage with 138 comprehensive unit and integration tests\n- **Error Resilient**: Graceful handling of network failures and edge cases\n- **Streaming Output**: Memory-efficient processing of large repository collections\n\n### \ud83d\udce6 **Repository Management**\n\n- **Multi-Repository Operations**: Clone, update, and monitor multiple repositories efficiently\n- **Intelligent Sync**: Smart pull with rebase, conflict detection, and resolution strategies\n- **Progress Tracking**: Real-time progress bars and detailed operation summaries\n- **Flexible Discovery**: Recursive repository scanning with configurable ignore patterns\n\n### \ud83d\udcc4 **License Management**\n\n- **GitHub Integration**: Fetch license templates directly from GitHub API\n- **Bulk Operations**: Add licenses to multiple repositories at once\n- **Template Customization**: Automatic placeholder replacement for author details\n- **Multiple Formats**: Support for all major open source licenses\n\n### \ud83c\udf10 **GitHub Pages Detection**\n\n- **Multi-Method Detection**: Scans for Jekyll, MkDocs, Sphinx, and custom configurations\n- **URL Construction**: Automatically builds GitHub Pages URLs from repository metadata\n- **Documentation Tracking**: Monitor which projects have active documentation sites\n\n### \ud83d\udcf1 **Social Media Automation**\n\n- **Content Generation**: Template-driven post creation for Twitter, LinkedIn, and Mastodon\n- **Smart Sampling**: Random repository selection with configurable filters\n- **Dry Run Support**: Preview posts before publishing\n- **Rate Limiting**: Built-in posting frequency controls and daily limits\n\n### \u2699\ufe0f **Configuration Management**\n\n- **Flexible Formats**: Support for both JSON and TOML configuration files\n- **Environment Overrides**: All settings can be controlled via environment variables\n- **Default Merging**: Intelligent combination of defaults, file settings, and overrides\n- **Example Generation**: Built-in config template generation\n\n### \ud83e\udd16 **Automated Service Mode**\n\n- **Scheduled Posting**: Run ghops as a background service for automated social media posting\n- **Multi-Directory Support**: Configure multiple repository locations with glob pattern support\n- **Periodic Reporting**: Generate comprehensive repository status reports\n- **Email Notifications**: Automated email alerts and daily summaries\n- **Error Monitoring**: Built-in error detection and email alerts\n\n### \ud83d\udd0d **Repository Discovery & Organization**\n\n- **Tag-Based Catalogs**: Organize repos with explicit tags and auto-generated implicit tags\n- **Powerful Query Language**: Find repos with fuzzy matching: `ghops query \"language ~= 'pyton'\"`\n- **Metadata Store**: Local database of all repository information for fast queries\n- **Implicit Tags**: Automatic tags like `repo:name`, `lang:python`, `has:docs`, `dir:parent`\n\n### \ud83d\udee1\ufe0f **Repository Auditing**\n\n- **Comprehensive Health Checks**: Audit repos for licenses, READMEs, security issues, and more\n- **Auto-Fix Capabilities**: Automatically fix common issues with `--fix` flag\n- **Security Scanning**: Detect hardcoded secrets and security vulnerabilities\n- **Dependency Auditing**: Check for missing or outdated dependency management\n- **Documentation Health**: Verify documentation setup and configuration\n\n### \ud83d\udcc4 **Portfolio Export**\n\n- **Multiple Formats**: Export to Markdown, Hugo, HTML, JSON, CSV, LaTeX, and PDF\n- **Interactive HTML**: Generated HTML includes live search, filtering, and sorting\n- **Hugo Integration**: Create complete Hugo site structure with taxonomies\n- **Grouping & Organization**: Group exports by language, directory, or custom tags\n- **Component-Based System**: Modular export components with customization hooks\n- **Format Flexibility**: Support for CSV, TSV, YAML output with field projection\n\n### \ud83d\udcda **Documentation Management**\n\n- **Multi-Tool Support**: Works with MkDocs, Sphinx, Jekyll, Hugo, and more\n- **Status Checking**: See documentation health across all repos\n- **Build & Serve**: Build and preview documentation locally\n- **Deploy to GitHub Pages**: One-command deployment to GitHub Pages\n- **Bulk Operations**: Manage docs across multiple repos simultaneously\n\n## \ud83d\ude80 Installation\n\nYou can install `ghops` via `pip`:\n\n```bash\npip install ghops\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/queelius/ghops.git\ncd ghops\nmake install\n```\n\n## \u26a1 Quick Start\n\n```bash\n# Generate a configuration file with examples\nghops config generate\n\n# Clone all your repos\nghops get\n\n# Update all repos in the current directory\nghops update -r\n\n# Check the status of all repos (includes PyPI and GitHub Pages info)\nghops status -r\n\n# Quick status check without PyPI detection\nghops status --no-pypi-check\n\n# Sample repositories for social media posting\nghops social sample --size 3\n\n# Create social media posts (dry run)\nghops social post --dry-run\n```\n\n### New Command Examples\n\n```bash\n# Repository Organization & Discovery\nghops catalog add awesome-project python ml research # Tag a repo\nghops catalog show -t python # Show Python repos\nghops query \"stars > 10 and language ~= 'python'\" # Fuzzy query\nghops list -t \"dir:work\" -t \"lang:python\" # Filter by multiple tags\n\n# Repository Auditing\nghops audit all -t \"lang:python\" --pretty # Audit all Python repos\nghops audit security --fix # Fix security issues\nghops audit license --fix --type MIT # Add missing licenses\nghops audit deps -q \"has:package.json\" # Audit JS dependencies\n\n# Documentation Management\nghops docs status -t \"has:docs\" # Check docs status\nghops docs build -t \"tool:mkdocs\" # Build MkDocs projects\nghops docs serve repo:myproject # Preview docs locally\nghops docs deploy -t \"lang:python\" --dry-run # Deploy to GitHub Pages\n\n# Portfolio Export\nghops export generate -f hugo --group-by lang # Export for Hugo site\nghops export generate -f html -o ./portfolio # Interactive HTML portfolio\nghops export generate -q \"stars > 5\" -f pdf # Export popular repos to PDF\nghops export generate -t \"dir:work\" -f markdown # Work portfolio in Markdown\nghops export generate -f csv --fields name,language,stars # CSV with specific fields\nghops export generate -f yaml --include-readme # YAML with README content\n\n# Metadata Management\nghops metadata refresh --github # Update from GitHub\nghops metadata show repo:ghops --pretty # Show repo metadata\nghops metadata stats # Repository statistics\n```\n\n### JSONL Output & Unix Pipelines\n\nAll ghops commands output newline-delimited JSON (JSONL) by default, making them perfect for Unix pipelines. You can also set the output format globally with the `GHOPS_FORMAT` environment variable:\n\n```bash\n# Set default output format\nexport GHOPS_FORMAT=csv # or json, yaml, tsv\n\n# Find repositories with uncommitted changes\nghops status | jq 'select(.status.uncommitted_changes == true)'\n\n# Count repositories by language\nghops list | jq -s 'group_by(.language) | map({language: .[0].language, count: length})'\n\n# Export repository URLs to a file\nghops list | jq -r '.remote.url' > repo-urls.txt\n\n# Find outdated PyPI packages\nghops status | jq 'select(.package.outdated == true)'\n\n# Audit repositories and get failed checks\nghops audit all | jq 'select(.status == \"fail\") | {name, checks: .checks | to_entries | map(select(.value.status == \"fail\")) | map(.key)}'\n\n# Chain commands - audit Python repos without docs\nghops list -t \"lang:python\" | jq -r '.path' | xargs -I {} ghops audit docs {} | jq 'select(.status == \"fail\")'\n```\n\n## \ud83d\udccb Commands\n\n### Repository Operations\n\n- **`ghops get [options]`** - Clone all repositories from your GitHub account\n - `--users USER [USER ...]` - Specify GitHub usernames to clone from\n - `--dir DIRECTORY` - Target directory for cloning\n - `--ignore REPO [REPO ...]` - Skip specific repositories\n - `--license LICENSE` - Add license files during cloning\n - `--dry-run` - Preview operations without making changes\n\n- **`ghops update [options]`** - Update local repositories\n - `-r, --recursive` - Search for repositories recursively\n - `--auto-commit` - Commit changes before pulling\n - `--commit-message MESSAGE` - Custom commit message\n - `--conflicts {abort,ours,theirs}` - Conflict resolution strategy\n - `--prompt` - Ask before pushing changes\n - `--license LICENSE` - Add/update license files during update\n\n- **`ghops status [options]`** - Comprehensive repository status\n - `-r, --recursive` - Search recursively\n - `--pretty` - Display as formatted table (default: JSONL)\n - `--no-pypi-check` - Skip PyPI status checks (faster)\n - `--no-pages-check` - Skip GitHub Pages detection\n - `--summary` - Show summary statistics\n\n### Configuration Management\n\n- **`ghops config generate`** - Create example configuration file\n- **`ghops config show`** - Display current configuration with all merges applied\n\n### Repository Organization & Discovery\n\n- **`ghops catalog add REPO TAG [TAG ...]`** - Add tags to a repository\n- **`ghops catalog remove REPO TAG [TAG ...]`** - Remove tags from a repository\n- **`ghops catalog show [options]`** - Show tagged repositories\n - `-t, --tag TAG` - Filter by specific tags\n - `--all-tags` - Require all specified tags\n - `--pretty` - Display as formatted table\n\n- **`ghops query EXPRESSION`** - Query repositories with fuzzy matching\n - Supports: `==`, `!=`, `~=`, `>`, `<`, `contains`, `in`\n - Examples: `\"stars > 10\"`, `\"language ~= 'pyton'\"`, `\"'ml' in topics\"`\n\n- **`ghops list [options]`** - List repositories with filtering\n - `-t, --tag TAG` - Filter by tags\n - `-q, --query EXPR` - Filter by query expression\n - `--pretty` - Display as formatted table\n\n### Repository Auditing\n\n- **`ghops audit COMMAND [options]`** - Comprehensive repository health checks\n - **`all`** - Run all audit checks\n - **`license`** - Check for license files\n - **`readme`** - Check for README files\n - **`security`** - Scan for security issues\n - **`deps`** - Audit dependencies\n - **`docs`** - Check documentation setup\n - **`gitignore`** - Verify .gitignore files\n \n Common options:\n - `--fix` - Automatically fix issues found\n - `-t, --tag TAG` - Filter repositories by tag\n - `-q, --query EXPR` - Filter by query expression\n - `--dry-run` - Preview fixes without applying\n\n### Documentation Management\n\n- **`ghops docs status [options]`** - Check documentation status\n- **`ghops docs build [options]`** - Build documentation\n- **`ghops docs serve [options]`** - Preview documentation locally\n- **`ghops docs deploy [options]`** - Deploy to GitHub Pages\n \n All support tag/query filtering with `-t` and `-q` options\n\n### Portfolio Export\n\n- **`ghops export generate [options]`** - Export repository portfolios\n - `-f, --format FORMAT` - Output format: markdown, hugo, html, json, csv, pdf, latex\n - `-o, --output DIR` - Output directory\n - `--single-file` - Export to single file\n - `--group-by PREFIX` - Group by tag prefix (e.g., \"dir\", \"lang\")\n - `--template NAME` - Use custom template\n - `-t, --tag TAG` - Filter by tags\n - `-q, --query EXPR` - Filter by query\n\n### Metadata Management\n\n- **`ghops metadata refresh [options]`** - Update repository metadata\n - `--github` - Fetch from GitHub API\n - `--path PATH` - Refresh specific repository\n - `--max-age AGE` - Only refresh if older than (e.g., \"7d\", \"12h\")\n\n- **`ghops metadata show REPO`** - Display repository metadata\n - Accepts repository path or tag selector (e.g., `repo:ghops`)\n\n- **`ghops metadata stats`** - Show metadata statistics\n\n### Social Media Automation\n\n- **`ghops social create [options]`** - Generate social media posts\n- **`ghops social post [options]`** - Generate and post content\n - `-t, --tag TAG` - Filter repositories by tag\n - `-q, --query EXPR` - Filter by query expression\n - `--sample-size N` - Number of repos to sample\n - `--dry-run` - Preview without posting\n\n### Service Mode\n\n- **`ghops service start`** - Start automated posting service\n - `--dry-run` - Run service in preview mode\n- **`ghops service run-once`** - Execute single posting cycle\n - `--dry-run` - Preview what would be posted\n\n## \ud83d\udd27 Advanced Configuration\n\n`ghops` uses a configuration file located at `~/.ghopsrc` (JSON or TOML format). Set custom location with `GHOPS_CONFIG` environment variable.\n\n### Key Configuration Sections\n\n#### Repository Directories\n\n```toml\n[general]\n# Multiple directories with glob pattern support\nrepository_directories = [\n \"~/github\", # Direct path\n \"~/projects/*/repos\", # Glob pattern\n \"~/work/code\" # Another direct path\n]\ngithub_username = \"your_username\"\n```\n\n#### Service Configuration\n\n```toml\n[service]\nenabled = true # Enable scheduled posting service\ninterval_minutes = 120 # Minutes between posting cycles\nstart_time = \"09:00\" # Preferred start time\n\n[service.reporting]\nenabled = true # Enable periodic reports\ninterval_hours = 24 # Hours between reports\ninclude_stats = true # Include operation statistics\ninclude_status = true # Include repository status\ninclude_recent_activity = true # Include recent activity\n\n[service.notifications.email]\nenabled = true # Enable email notifications\nsmtp_server = \"smtp.gmail.com\" # SMTP server\nsmtp_port = 587 # SMTP port\nusername = \"your@email.com\" # Email username\npassword = \"app_password\" # Email password/app password\nfrom_email = \"your@email.com\" # From address\nto_email = \"your@email.com\" # To address\ndaily_summary = true # Send daily reports\nerror_alerts = true # Send error alerts\n```\n\n#### Social Media Platforms\n\n```toml\n[social_media.platforms.twitter]\nenabled = false\napi_key = \"your_api_key\"\napi_secret = \"your_api_secret\"\naccess_token = \"your_access_token\"\naccess_token_secret = \"your_access_token_secret\"\n\n[social_media.platforms.twitter.templates]\npypi_release = \"\ud83d\ude80 New release: {package_name} v{version} is now available on PyPI! {pypi_url} #{package_name} #python #opensource\"\ngithub_pages = \"\ud83d\udcd6 Updated documentation for {repo_name}: {pages_url} #docs #opensource\"\nrandom_highlight = \"\u2728 Working on {repo_name}: {description} {repo_url} #{language} #coding\"\n```\n\n#### Posting Rules\n\n```toml\n[social_media.posting]\nrandom_sample_size = 3 # Number of repos to randomly highlight\ndaily_limit = 5 # Maximum posts per day\nmin_hours_between_posts = 2 # Minimum time between posts\nexclude_private = true # Don't post about private repos\nexclude_forks = true # Don't post about forked repos\n```\n\n## \ud83d\udca1 Examples\n\n### Check Repository Status\n\n```bash\n# Full status with PyPI and GitHub Pages (JSONL output)\nghops status -r\n\n# Pretty-print table format for human reading\nghops status -r --pretty\n\n# Fast status check\nghops status --no-pypi-check\n\n# Filter and transform with jq\nghops status | jq 'select(.license.type == \"MIT\")'\n```\n\n### Social Media Promotion\n\n```bash\n# See what repositories would be selected\nghops social sample --size 5\n\n# Preview social media posts\nghops social post --dry-run --size 3\n\n# Actually post (requires configured API credentials)\nghops social post --size 2\n```\n\n### Repository Management\n\n```bash\n# Clone all your repositories\nghops get --dir ~/projects\n\n# Update repositories recursively\nghops update -r --dir ~/projects\n\n# Add MIT license to repositories during update\nghops update -r --license mit --license-name \"Your Name\" --license-email \"you@example.com\"\n```\n\n### Service Mode Operations\n\n```bash\n# Start automated service (background posting and reporting)\nghops service start\n\n# Test service with dry-run\nghops service start --dry-run\n\n# Run single cycle for testing\nghops service run-once --dry-run\n\n# Create systemd service (see examples/ghops.service)\nsudo systemctl enable ghops\nsudo systemctl start ghops\n```\n\n### Multi-Directory Management\n\n```bash\n# Configure multiple repository locations\nghops config generate # Edit to add repository_directories\n\n# Status across all configured directories\nghops status\n\n# Update repositories in all configured locations\nghops update -r\n```\n\n## \u26a1 Performance & Advanced Usage\n\n### Performance Options\n\n- Use `--no-pypi-check` for faster status checks when you don't need PyPI information\n- Use `--no-pages-check` to skip GitHub Pages detection\n- Configure `max_concurrent_operations` in config for better performance\n\n## \ud83e\uddea Testing & Quality\n\n- **138 comprehensive tests** covering all major functionality\n- **86% test coverage** with unit and integration testing\n- **Continuous integration** with automated testing\n- **Error handling** for network failures and edge cases\n- **Performance benchmarks** for large repository sets\n- **Mock testing** for reliable external API testing\n\n### Test Coverage by Module\n\n- **CLI & Commands**: Complete argument parsing and execution testing\n- **Configuration System**: All file formats and environment override scenarios\n- **PyPI Integration**: Package detection, API calls, and error conditions\n- **Social Media**: Content generation, platform integration, and rate limiting\n- **License Management**: GitHub API integration and template processing\n- **Status Reporting**: Repository scanning, progress tracking, and output formatting\n\n## \ud83c\udfd7\ufe0f Architecture\n\n`ghops` follows a clean, modular architecture designed for maintainability and extensibility:\n\n```text\nghops/\n\u251c\u2500\u2500 cli.py # Main CLI entry point with click\n\u251c\u2500\u2500 __main__.py # Python module execution entry\n\u251c\u2500\u2500 commands/ # Modular command implementations\n\u2502 \u251c\u2500\u2500 get.py # Repository cloning logic\n\u2502 \u251c\u2500\u2500 update.py # Repository updating and syncing\n\u2502 \u251c\u2500\u2500 status.py # Status reporting and analytics\n\u2502 \u2514\u2500\u2500 license.py # License management operations\n\u251c\u2500\u2500 config.py # Configuration loading and merging\n\u251c\u2500\u2500 utils.py # Shared utilities and helpers\n\u251c\u2500\u2500 pypi.py # PyPI package detection and API\n\u2514\u2500\u2500 social.py # Social media content generation\n```\n\n### Design Principles\n\n- **Separation of Concerns**: Each module has a single, well-defined responsibility\n- **Error Resilience**: Graceful handling of network failures and edge cases\n- **Performance**: Optional API checks and concurrent operations\n- **Extensibility**: Easy to add new commands and features\n- **Testability**: Comprehensive test coverage with mocking for external services\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see the [Contributing Guide](contributing.md) for more details.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n\u00a9 2025 [Alex Towell](https://github.com/queelius)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A CLI tool for managing GitHub repos",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/queelius/ghops",
"Issues": "https://github.com/queelius/ghops/issues",
"Source": "https://github.com/queelius/ghops"
},
"split_keywords": [
"automation",
" cli",
" devops",
" git",
" github"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cefa1fca20e3b35c6a1e9ffd515de93b45eaeaaf440892c70e612398ec224403",
"md5": "893b829904d8d401fdf64213232b821b",
"sha256": "5e52eab57f756ee882aec2260dcc89edf896c171ca12eea32d597b596e00dba1"
},
"downloads": -1,
"filename": "ghops-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "893b829904d8d401fdf64213232b821b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 150562,
"upload_time": "2025-08-20T11:48:35",
"upload_time_iso_8601": "2025-08-20T11:48:35.106140Z",
"url": "https://files.pythonhosted.org/packages/ce/fa/1fca20e3b35c6a1e9ffd515de93b45eaeaaf440892c70e612398ec224403/ghops-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "96dc60ffcab6fa23b3ef69d01e453fb035ad08db5123331057da608a941b838c",
"md5": "eb06e28535b5e94d9144fe3f47155fef",
"sha256": "60f56f712538ddd08dfe17d748569b1f5ffbd1a29de3fa0d2addd0ed5e57d1d7"
},
"downloads": -1,
"filename": "ghops-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "eb06e28535b5e94d9144fe3f47155fef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 191992,
"upload_time": "2025-08-20T11:48:36",
"upload_time_iso_8601": "2025-08-20T11:48:36.232025Z",
"url": "https://files.pythonhosted.org/packages/96/dc/60ffcab6fa23b3ef69d01e453fb035ad08db5123331057da608a941b838c/ghops-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 11:48:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "queelius",
"github_project": "ghops",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "packaging",
"specs": [
[
">=",
"21.0"
]
]
},
{
"name": "toml",
"specs": []
},
{
"name": "rapidfuzz",
"specs": []
},
{
"name": "Jinja2",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "tweepy",
"specs": []
},
{
"name": "mkdocs",
"specs": [
[
">=",
"1.4.0"
]
]
},
{
"name": "mkdocs-material",
"specs": [
[
">=",
"9.0.0"
]
]
},
{
"name": "ghp-import",
"specs": [
[
">=",
"2.1.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "pytest-mock",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "pyfakefs",
"specs": [
[
">=",
"5.0.0"
]
]
},
{
"name": "build",
"specs": []
},
{
"name": "twine",
"specs": []
}
],
"lcname": "ghops"
}
JSON
