### Quick Start Examples

Source: https://github.com/queelius/repoindex/blob/master/docs/export.md

Demonstrates various ways to use the `repoindex export` command, including default archive creation, filtered archives, and format-based exports.

```bash
# Default: longecho-compliant arkiv archive with HTML browser
repoindex export -o ~/archives/repos/

# Filtered archive
repoindex export -o ~/archives/python/ --language python
repoindex export -o ~/archives/dirty/ --dirty
repoindex export -o ~/archives/work/ --tag "work/*"
repoindex export -o ~/archives/recent/ --recent 30d

# Format-based exports (via exporter plugins)
repoindex export csv -o repos.csv
repoindex export bibtex --language python > refs.bib
repoindex export --list-formats
```

--------------------------------

### Usage Examples

Source: https://github.com/queelius/repoindex/blob/master/docs/events.md

Command-line examples for retrieving and filtering events.

```bash
repoindex events --since 7d                        # Pretty table (default)
repoindex events --type git_tag --since 30d        # Filter by type
repoindex events --type commit --since 7d
repoindex events --repo myproject --since 7d       # Filter by repo name
repoindex events --stats                           # Summary only
repoindex events --json --since 7d                 # JSONL for piping
repoindex events --since 30d --limit 500           # Custom limit
repoindex events --since 365d --limit 0            # Unlimited
```

--------------------------------

### Install repoindex

Source: https://github.com/queelius/repoindex/blob/master/README.md

Install repoindex using pip or from source.

```bash
pip install repoindex         # CLI only
pip install repoindex[mcp]    # CLI + MCP server
```

```bash
git clone https://github.com/queelius/repoindex.git
cd repoindex
make install
```

--------------------------------

### Development - Install

Source: https://github.com/queelius/repoindex/blob/master/README.md

Command to create a virtual environment and install the project in development mode.

```bash
make install
```

--------------------------------

### SQL Examples

Source: https://github.com/queelius/repoindex/blob/master/README.md

Examples of using the SQL interface for querying repository data.

```bash
repoindex sql "SELECT name, forge_id, stars FROM repos WHERE stars > 0 ORDER BY stars DESC LIMIT 10"
repoindex sql "SELECT r.name, p.package_name, p.current_version
               FROM publications p JOIN repos r ON p.repo_id = r.id
               WHERE p.registry = 'pypi' AND p.published = 1"
repoindex sql --info
repoindex sql --schema
```

--------------------------------

### Events Examples

Source: https://github.com/queelius/repoindex/blob/master/README.md

Examples of using the events command to query git events.

```bash
repoindex events --since 7d
repoindex events --type git_tag --since 30d
repoindex events --repo myproject
repoindex events --stats
repoindex events --json --since 7d | jq -r '.type' | sort | uniq -c
```

--------------------------------

### Install repoindex

Source: https://github.com/queelius/repoindex/blob/master/docs/index.md

Install repoindex with or without the MCP server.

```bash
pip install repoindex         # CLI only
pip install repoindex[mcp]    # CLI + MCP server
```

--------------------------------

### Command interface examples

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-04-10-wip-snapshot.md

Examples of how to use the `repoindex ops wip-snapshot` command with different options and filters.

```bash
repoindex ops wip-snapshot                          # all dirty repos
repoindex ops wip-snapshot --dry-run                # preview only
repoindex ops wip-snapshot "language == 'Python'"   # filtered
repoindex ops wip-snapshot --language python         # shorthand
```

--------------------------------

### Commit Message Example

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-html-export-plan.md

Example Git commit message for adding the get_manifest tool.

```bash
git add repoindex/mcp/__init__.py repoindex/mcp/server.py tests/test_mcp.py
git commit -m "feat(mcp): add get_manifest tool"
```

--------------------------------

### Quick Start Commands

Source: https://github.com/queelius/repoindex/blob/master/docs/index.md

Basic commands to initialize configuration, refresh the database, and view status.

```bash
repoindex config init          # Create ~/.repoindex/config.yaml
repoindex refresh              # Populate the database
repoindex status               # Dashboard overview
```

--------------------------------

### SQL Query Examples

Source: https://github.com/queelius/repoindex/blob/master/docs/index.md

Examples of using the repoindex sql command for database queries and schema inspection.

```bash
repoindex sql "SELECT name, forge_id, stars FROM repos WHERE stars > 0 ORDER BY stars DESC LIMIT 10"
repoindex sql "SELECT r.name FROM publications p JOIN repos r ON p.repo_id=r.id WHERE p.registry='pypi' AND p.published=1"
repoindex sql --info
repoindex sql --schema
```

--------------------------------

### Mirror Configuration Example

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

YAML configuration for setting up mirror targets.

```yaml
forges:
  codeberg:
    source_id: gitea
    host: codeberg.org
    role: mirror
    token_env: CODEBERG_TOKEN
    url_template: "https://codeberg.org/queelius/{repo}.git"
  gitea-gdrive:
    source_id: gitea
    role: mirror
    url_template: "file:///mnt/gdrive/git-mirrors/{repo}.git"
```

--------------------------------

### Commit Message Example

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-html-export-plan.md

Example Git commit message for adding the get_schema tool.

```bash
git add repoindex/mcp/server.py tests/test_mcp.py
git commit -m "feat(mcp): add get_schema tool"
```

--------------------------------

### Ops Examples

Source: https://github.com/queelius/repoindex/blob/master/README.md

Examples of using the ops command for multi-repo git operations and metadata audit.

```bash
# Multi-repo git operations
repoindex ops git push --dry-run
repoindex ops git pull --language python
repoindex ops git status --dirty

# Metadata audit
repoindex ops audit --language python
repoindex ops audit --category essentials --severity critical
```

--------------------------------

### repoindex Configuration File Example

Source: https://github.com/queelius/repoindex/blob/master/docs/index.md

Example YAML configuration file for repoindex, specifying repository directories, GitHub token, forge configurations, and author details.

```yaml
# ~/.repoindex/config.yaml
repository_directories:
  - ~/github/**
  - ~/work

github:
  token: ghp_...

forges:
  github:
    token_env: GITHUB_TOKEN
    role: primary
  codeberg:
    source_id: gitea
    host: codeberg.org
    role: mirror
    token_env: CODEBERG_TOKEN
    url_template: "https://codeberg.org/queelius/{repo}.git"

author:
  name: "Alexander Towell"
  alias: "Alex Towell"
  email: "lex@metafunctor.com"
  orcid: "0000-0001-6443-9897"

repository_tags:
  /home/user/github/myproject:
    - work/active
    - topic:ml

```

--------------------------------

### Install MCP optional dependency

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-html-export-plan.md

Command to install the repository with the mcp optional dependency.

```bash
cd /home/spinoza/github/beta/repoindex && pip install -e ".[mcp]"
```

--------------------------------

### Configuration Example

Source: https://github.com/queelius/repoindex/blob/master/CLAUDE.md

Example of the 'forges' section in the repoindex configuration file.

```yaml
forges:
  github:
    token_env: GITHUB_TOKEN
    role: primary
  codeberg:
    source_id: gitea
    host: codeberg.org
    role: mirror
    token_env: CODEBERG_TOKEN
    url_template: "https://codeberg.org/queelius/{repo}.git"
```

--------------------------------

### Git Operations Examples

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

Shows examples of using `repoindex ops git` for pushing, pulling, and checking the status of multiple repositories, including dry runs and skipping confirmations.

```bash
# Push repos with unpushed commits
repoindex ops git push --dry-run
repoindex ops git push --language python
repoindex ops git push --yes              # Skip confirmation

# Pull updates
repoindex ops git pull
repoindex ops git pull --dirty --dry-run

# Multi-repo status
repoindex ops git status
repoindex ops git status --dirty --json
```

--------------------------------

### GitHub Actions Example

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Example of a GitHub Actions workflow step to run new feature tests with coverage.

```yaml
- name: Run new feature tests
  run: |
    pytest tests/test_version_manager.py \
           tests/test_publish.py \
           tests/test_publish_integration.py \
           --cov=ghops/version_manager \
           --cov=ghops/commands/publish \
           --cov-report=xml \
           --maxfail=3 \
           -v

- name: Upload coverage
  uses: codecov/codecov-action@v3
  with:
    files: ./coverage.xml
```

--------------------------------

### Filter Flags Examples

Source: https://github.com/queelius/repoindex/blob/master/docs/export.md

Provides examples of using filter flags with the `export` command.

```bash
repoindex export -o out/ --language python
repoindex export -o out/ --dirty
repoindex export -o out/ --tag "work/*"
repoindex export -o out/ --recent 7d
```

--------------------------------

### Claude Code Plugin Installation

Source: https://github.com/queelius/repoindex/blob/master/docs/index.md

Commands to add the Claude Code Plugin marketplace and install the plugin.

```bash
/plugin marketplace add queelius/claude-code-marketplace
/plugin install repoindex@queelius

```

--------------------------------

### Install Claude Code Plugin

Source: https://github.com/queelius/repoindex/blob/master/README.md

Install the Claude Code plugin to wire the MCP server automatically.

```bash
/plugin marketplace add queelius/claude-code-marketplace
/plugin install repoindex@queelius
```

--------------------------------

### Creating Test Repositories

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Example of how to create a fake repository and file within a test using the 'fs' fixture.

```python
def test_example(fs):
    # Create fake repository
    repo_path = "/test/repo"
    fs.create_dir(repo_path)
    fs.create_file(f"{repo_path}/pyproject.toml", contents="...")

    # Test functionality
    result = some_function(repo_path)
    assert result is True
```

--------------------------------

### Composing with jq

Source: https://github.com/queelius/repoindex/blob/master/docs/events.md

Examples of using `jq` to process JSONL event output.

```bash
# Count by type
repoindex events --json --since 7d | jq -r '.type' | sort | uniq -c | sort -rn

# Unique repos with events
repoindex events --json --since 7d | jq -r '.repo_name' | sort -u

# Process new tags as a stream
repoindex events --json --type git_tag --since 1h | while read event; do
  echo "$(echo $event | jq -r '.repo_name'): $(echo $event | jq -r '.data.tag')"
done
```

--------------------------------

### Filter Flags Example

Source: https://github.com/queelius/repoindex/blob/master/docs/index.md

Examples of using filter flags with the export command.

```bash
repoindex export -o out/ --dirty
repoindex export -o out/ --language python
repoindex export -o out/ --tag "work/*"
repoindex export -o out/ --recent 7d
```

--------------------------------

### Arkiv Export Command Examples

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-export-design.md

Bash command examples for using the `repoindex export arkiv` command, including a full export, filtered export, and dry run.

```bash
# Full archive export
repoindex export arkiv ~/exports/repoindex/

# With query filters (same flags as query command)
repoindex export arkiv ~/exports/python-repos/ --language python

# Dry run
repoindex export arkiv ~/exports/test/ --dry-run
```

--------------------------------

### Example repoindex commands with filter flags

Source: https://github.com/queelius/repoindex/blob/master/CLAUDE.md

Demonstrates how to use filter flags with repoindex ops and copy commands.

```bash
repoindex ops wip-snapshot --language python --tag 'work/*' --recent 14d
repoindex copy --dirty --language rust -d /mnt/backup
```

--------------------------------

### Database Usage Example

Source: https://github.com/queelius/repoindex/blob/master/CLAUDE.md

Python code demonstrating how to interact with the repoindex database using the Database context manager and functions for fetching repositories by flags.

```python
from repoindex.database import Database
from repoindex.services.flag_query import build_where_and_params, fetch_repos_by_flags

with Database(config=config, read_only=True) as db:
    db.execute("SELECT name FROM repos WHERE language = ?", ("Python",))

where, params = build_where_and_params(language='Python', dirty=True)
repos = fetch_repos_by_flags(config, language='Python', recent='7d')
```

--------------------------------

### Add 'repoindex mcp' CLI command

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-html-export-plan.md

Example of adding the 'mcp' command to the CLI.

```python
cli.add_command(mcp_handler, name='mcp')
```

--------------------------------

### Testing CLI Commands

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Example of testing Click CLI commands using CliRunner.

```python
from click.testing import CliRunner

def test_example(fs):
    runner = CliRunner()
    result = runner.invoke(publish_handler, ['--dry-run'])

    assert result.exit_code == 0
    assert "Dry run" in result.output
```

--------------------------------

### Mirror Preview and Operations

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

Examples of previewing and performing repository mirroring operations.

```bash
# Preview pushing every repo to Codeberg
repoindex ops mirror --to codeberg --dry-run

# Push all Python repos to every configured mirror
repoindex ops mirror --all --language python

# Mirror dirty repos to a local Gitea, initializing bare repos
repoindex ops mirror --to gitea-gdrive --dirty --init

# Force-push (overwrites diverged mirror branches)
repoindex ops mirror --to nas-backup --force
```

--------------------------------

### Sync Preview and Operations

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

Examples of previewing and performing repository synchronization operations.

```bash
# Preview what would be cloned from every enumerable forge
repoindex ops sync --all --dry-run

# Sync from a specific forge
repoindex ops sync --from codeberg

# Override destination root
repoindex ops sync --all --into ~/imports/

# Include archived repos
repoindex ops sync --all --include-archived

# Filter by name pattern
repoindex ops sync --all --filter "tools-*"
```

--------------------------------

### File Generation Examples

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

Illustrates how to use `repoindex ops generate` to create boilerplate files like `codemeta.json`, `LICENSE`, `.gitignore`, and community files, with options for language filtering and dry runs.

```bash
# codemeta.json
repoindex ops generate codemeta --language python --dry-run

# LICENSE
repoindex ops generate license --license mit --dry-run
repoindex ops generate license --license apache-2.0 --dry-run

# .gitignore
repoindex ops generate gitignore --lang python --dry-run
repoindex ops generate gitignore --lang node --dry-run

# Community files
repoindex ops generate code-of-conduct --dry-run
repoindex ops generate contributing --dry-run

# Citation and documentation
repoindex ops generate citation --language python --dry-run
repoindex ops generate zenodo --dry-run
repoindex ops generate mkdocs --language python --dry-run
```

--------------------------------

### Custom Exporter Python Example

Source: https://github.com/queelius/repoindex/blob/master/docs/export.md

A Python script demonstrating how to create a custom exporter by subclassing `repoindex.exporters.Exporter`.

```python
# ~/.repoindex/exporters/my_format.py
from repoindex.exporters import Exporter

class MyExporter(Exporter):
    format_id = "custom"
    name = "My Custom Format"
    extension = ".txt"

    def export(self, repos, output, config=None):
        for repo in repos:
            output.write(f"{repo['name']}: {repo.get('description', '')}\n")
        return len(repos)

exporter = MyExporter()
```

--------------------------------

### Querying Events via SQL

Source: https://github.com/queelius/repoindex/blob/master/docs/events.md

Examples of using `repoindex sql` to perform complex queries on event data.

```sql
# Most active repos in the last 30 days
repoindex sql "
  SELECT r.name, COUNT(*) AS n
  FROM events e JOIN repos r ON e.repo_id = r.id
  WHERE e.type = 'commit' AND e.timestamp > datetime('now', '-30 days')
  GROUP BY r.id
  ORDER BY n DESC
  LIMIT 20
"

# Every tag created since Jan 1
repoindex sql "
  SELECT r.name, e.ref, e.timestamp
  FROM events e JOIN repos r ON e.repo_id = r.id
  WHERE e.type = 'git_tag' AND e.timestamp >= '2026-01-01'
  ORDER BY e.timestamp DESC
"
```

--------------------------------

### Include download counts in PackageMetadata

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-metadata-enrichment.md

Example of how to include fetched download counts in the PackageMetadata object.

```python
downloads = self._fetch_downloads(package_name)
return PackageMetadata(
    ...
    downloads_total=downloads,
)
```

--------------------------------

### Export - Format plugins

Source: https://github.com/queelius/repoindex/blob/master/README.md

Examples of exporting data in different formats like CSV and BibTeX, and listing available formats.

```bash
repoindex export csv -o repos.csv
repoindex export bibtex --language python > refs.bib
repoindex export --list-formats
```

--------------------------------

### WIP Snapshot Operations

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

Examples of creating and previewing WIP snapshots of dirty working trees.

```bash
# Snapshot all dirty repos
repoindex ops wip-snapshot

# Preview first
repoindex ops wip-snapshot --dry-run

# Only Python repos
repoindex ops wip-snapshot --language python
```

--------------------------------

### Metadata Audit Examples

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

Demonstrates various ways to use the `repoindex ops audit` command, including basic usage, filtering by category and severity, auditing subsets, and machine-readable output.

```bash
# Audit all repos (rich table by default)
repoindex ops audit

# Filter by category and severity
repoindex ops audit --category essentials
repoindex ops audit --severity critical

# Audit subset
repoindex ops audit --language python
repoindex ops audit --tag "work/*"

# Machine-readable output
repoindex ops audit --json
```

--------------------------------

### Integration into _process_repo

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-refresh-performance-cli.md

Example of how to integrate the parallel provider calls into the _process_repo function.

```python
# Platform providers (parallel)
if active_platforms:
    repo_dict = {'remote_url': enriched.remote_url, 'name': enriched.name, 'owner': enriched.owner}
    platform_results = _run_platforms_parallel(active_platforms, repo.path, repo_dict, config)
    for fields in platform_results:
        _update_repo_platform_fields(db, repo_id, fields)

```

--------------------------------

### Configuration - Get specific value

Source: https://github.com/queelius/repoindex/blob/master/README.md

Command to retrieve a specific configuration value, e.g., author's name.

```bash
repoindex config get author.name
```

--------------------------------

### GiteaSource Class Definition

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-v015-unified-sources.md

Example of the GiteaSource class, demonstrating detection and fetch methods for Gitea-based platforms.

```python
class GiteaSource(MetadataSource):
    source_id = "gitea"
    name = "Gitea / Codeberg"
    target = "repos"

    def detect(self, repo_path, repo_record=None):
        url = (repo_record or {}).get('remote_url', '')
        hosts = self._get_hosts(config)  # default: ['codeberg.org']
        return any(host in url for host in hosts)

    def fetch(self, repo_path, repo_record=None, config=None):
        # Parse URL, call Gitea API: GET /api/v1/repos/{owner}/{name}
        # Return: {gitea_stars, gitea_forks, gitea_description, ...}
```

--------------------------------

### Troubleshooting Import Errors

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Commands to resolve import errors by installing in development mode or setting PYTHONPATH.

```bash
# Ensure package is installed in development mode
pip install -e .

# Or use PYTHONPATH
PYTHONPATH=/home/spinoza/github/beta/ghops pytest tests/
```

--------------------------------

### MCP Server - Get Manifest Implementation

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-html-export-plan.md

Python implementation for the get_manifest tool, which retrieves an overview of database contents, including table row counts, descriptions, language distribution, and last refresh time.

```python
import subprocess

from ..config import load_config
from ..database.connection import Database


def _get_db():
    """Get a read-only Database instance."""
    config = load_config()
    return Database(config=config, read_only=True)


def _get_manifest_impl() -> dict:
    db = _get_db()
    with db:
        tables = {}
        for table_name, desc in [
            ('repos', 'Repository metadata'),
            ('events', 'Git events (commits, tags)'),
            ('tags', 'Repository tags'),
            ('publications', 'Package registry publications'),
        ]:
            db.execute(f"SELECT COUNT(*) as count FROM {table_name}")
            row = db.fetchone()
            tables[table_name] = {
                'row_count': row['count'] if row else 0,
                'description': desc,
            }

        db.execute(
            "SELECT language, COUNT(*) as cnt FROM repos "
            "WHERE language IS NOT NULL GROUP BY language ORDER BY cnt DESC"
        )
        languages = {r['language']: r['cnt'] for r in db.fetchall()}

        db.execute(
            "SELECT started_at FROM refresh_log ORDER BY started_at DESC LIMIT 1"
        )
        refresh_rows = db.fetchall()
        last_refresh = refresh_rows[0]['started_at'] if refresh_rows else None

    return {
        'description': 'repoindex filesystem git catalog',
        'database': str(db.db_path),
        'tables': tables,
        'summary': {
            'languages': languages,
            'last_refresh': last_refresh,
        },
    }
```

--------------------------------

### Implement MCP server init

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-html-export-plan.md

Initial implementation for the repoindex.mcp package.

```python
# repoindex/mcp/__init__.py
"""MCP server for repoindex."""

```

--------------------------------

### Troubleshooting Fake Filesystem Issues

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Guidance for resolving 'No such file or directory' errors in tests by ensuring the 'fs' fixture is used.

```bash
# If tests fail with "No such file or directory"
# Check that test uses the 'fs' fixture
def test_example(fs):  # <-- Must have 'fs' parameter
    fs.create_dir("/test/repo")
```

--------------------------------

### Development - Build

Source: https://github.com/queelius/repoindex/blob/master/README.md

Command to build the project's wheel and sdist.

```bash
make build
```

--------------------------------

### JSON Output Shape

Source: https://github.com/queelius/repoindex/blob/master/docs/events.md

Examples of the JSON structure for different event types.

```json
{"type": "git_tag", "timestamp": "2024-01-15T10:30:00", "repo_name": "myproject",
 "data": {"tag": "v1.2.0", "message": "Release 1.2.0", "hash": "abc1234"}}

{"type": "commit", "timestamp": "2024-01-15T09:00:00", "repo_name": "myproject",
 "data": {"hash": "abc1234", "message": "Fix auth bug", "author": "dev@example.com"}}

{"type": "branch", "timestamp": "2024-01-15T08:00:00", "repo_name": "myproject",
 "data": {"branch": "feature/new-auth", "action": "created"}}

{"type": "merge", "timestamp": "2024-01-15T11:00:00", "repo_name": "myproject",
 "data": {"hash": "def5678", "message": "Merge 'feature/new-auth'", "merged_branch": "feature/new-auth"}}
```

--------------------------------

### Test a single function

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Demonstrates how to run a single, specific test function.

```bash
# Test major version bumping
pytest tests/test_version_manager.py::TestVersionBumper::test_bump_major_standard_version -v

# Test Python project detection
pytest tests/test_publish.py::TestProjectDetector::test_detect_python_pyproject_toml -v

# Test complete release workflow
pytest tests/test_publish_integration.py::TestPublishIntegrationRealWorldScenarios::test_complete_release_workflow -v
```

--------------------------------

### MCP Server Command

Source: https://github.com/queelius/repoindex/blob/master/docs/index.md

Command to start the MCP server for stdio transport.

```bash
repoindex mcp                  # stdio transport for Claude / MCP-aware agents
```

--------------------------------

### Troubleshooting Mock Not Working

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Explanation on correctly mocking external commands by targeting the module where the function is imported.

```bash
# Ensure you're mocking the right module
# Mock where it's imported, not where it's defined
@patch('ghops.commands.publish.run_command')  # ✅ Correct
@patch('ghops.utils.run_command')             # ❌ Wrong
```

--------------------------------

### Advanced Filtering with SQL

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

Example of using SQL for complex filtering before operating.

```bash
# Find repos without license files via SQL, then operate
repoindex sql "SELECT name FROM repos WHERE has_license = 0"
```

--------------------------------

### Per-repo processing loop

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-v015-unified-sources.md

Illustrates the processing of sources for each repository.

```python
for repo in repos:
    for source in sources:
        if source.detect(repo.path, repo_dict):
            data = source.fetch(repo.path, repo_dict, config)
            if data:
                if source.target == "repos":
                    _update_repo_fields(db, repo_id, data)
                elif source.target == "publications":
                    _upsert_publication(db, repo_id, data)

    # After all sources: derive tags
    _derive_tags(db, repo_id, repo_dict)
```

--------------------------------

### Test Go/pkg.go.dev publishing

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Runs tests for publishing Go projects to pkg.go.dev.

```bash
# Test Go/pkg.go.dev publishing
pytest tests/test_publish.py::TestRegistryPublisherGo -v
```

--------------------------------

### Combining Filters with Operations

Source: https://github.com/queelius/repoindex/blob/master/docs/ops.md

Examples demonstrating the use of filter flags across various operations.

```bash
repoindex ops audit --language python --severity critical
repoindex ops git push --tag "work/*" --dry-run
repoindex ops generate license --language rust --dry-run
repoindex ops mirror --to codeberg --recent 7d
```

--------------------------------

### Run all integration tests

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Executes all integration tests that combine version bumping and publishing.

```bash
pytest tests/test_publish_integration.py -v
```

--------------------------------

### Smoke test for --external and --provider github

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-refresh-performance-cli.md

Bash commands to verify --external includes GitHub and that --provider github works.

```bash
# Verify --external now includes GitHub
repoindex refresh --external -d ~/github/beta/repoindex 2>&1 | head -5
# Should show GitHub enrichment happening

# Verify --provider github works
repoindex refresh --provider github -d ~/github/beta/repoindex 2>&1 | head -5

# Verify other providers still work
repoindex refresh --provider pypi -d ~/github/beta/repoindex 2>&1 | head -5
```

--------------------------------

### run_command() Return Value

Source: https://github.com/queelius/repoindex/blob/master/CLAUDE.md

Example of using the `run_command` utility function, which returns a tuple of stdout and the return code.

```python
output, rc = run_command("git status", cwd=repo_path, capture_output=True)
```

--------------------------------

### Commit Message

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-refresh-performance-cli.md

Example commit message for adding the PlatformProvider ABC.

```git
feat: add PlatformProvider ABC for hosting platform enrichment
```

--------------------------------

### Run tests for MCP server

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-html-export-plan.md

Command to run the MCP server tests.

```bash
pytest tests/test_mcp.py -v
```

--------------------------------

### Configuration - Show current config

Source: https://github.com/queelius/repoindex/blob/master/README.md

Command to display the current repoindex configuration.

```bash
repoindex config show
```

--------------------------------

### Mocking run_command return values

Source: https://github.com/queelius/repoindex/blob/master/CLAUDE.md

Examples of setting return values for a mocked run_command function to simulate success or failure.

```python
mock_run_command.return_value = ("output", 0)   # Success
mock_run_command.return_value = (None, 1)        # Failure
```

--------------------------------

### repoindex Configuration Commands

Source: https://github.com/queelius/repoindex/blob/master/docs/index.md

Command-line interface commands for managing repoindex configuration, including showing, getting, and setting values.

```bash
repoindex config show            # Pretty YAML
repoindex config show --json     # JSON
repoindex config get author.name
repoindex config set author.name "Your Name"
repoindex config unset refresh.external_sources.github

```

--------------------------------

### Development - Test

Source: https://github.com/queelius/repoindex/blob/master/README.md

Command to run tests.

```bash
make test
```

--------------------------------

### Test real-world scenarios

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Runs integration tests simulating real-world scenarios.

```bash
# Test real-world scenarios
pytest tests/test_publish_integration.py::TestPublishIntegrationRealWorldScenarios -v
```

--------------------------------

### MCP tools

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-v015-unified-sources.md

Lists the available MCP (Metadata Curation Platform) tools, including existing ones and the newly added 'tag' and 'export' functionalities.

```bash
get_manifest()           # overview (exists)
get_schema(table?)       # introspection (exists)
run_sql(query)           # read-only SQL (exists)
refresh(sources?)        # sync metadata (exists)
tag(repo, action, tag)   # manage user tags (NEW)
export(output_dir, query?) # arkiv archive (NEW)
```

--------------------------------

### User Extension Directories

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-05-09-v2-source-hierarchy.md

User-specific directories for extending repoindex with custom sources for forges, registries, and scanners.

```bash
~/.repoindex/sources/forges/        # GitForge subclasses
~/.repoindex/sources/registries/    # Registry subclasses
~/.repoindex/sources/scanners/      # LocalScanner subclasses
```

--------------------------------

### Add keywords column to schema

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-metadata-enrichment.md

Example of adding a 'keywords' column to the database schema for storing extracted keywords.

```python
from sqlalchemy import Column, Integer, String, JSON

def upgrade():
    op.add_column('repos', Column('keywords', JSON, nullable=True))

def downgrade():
    op.drop_column('repos', 'keywords')
```

--------------------------------

### Rewire refresh command for MetadataSource

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-v015-unified-sources.md

Illustrates the new single loop for discovering and processing sources, including prefetching batch sources.

```python
sources = discover_sources(only=active_source_names)

# Prefetch batch sources
for s in sources:
    if s.batch:
        s.prefetch(config)
```

--------------------------------

### Mocking External Commands

Source: https://github.com/queelius/repoindex/blob/master/tests/README_NEW_TESTS.md

Example of mocking an external command using '@patch' decorator and verifying its call.

```python
@patch('ghops.commands.publish.run_command')
def test_example(mock_run_command, fs):
    # Setup mock
    mock_run_command.return_value = ("success", 0)

    # Test functionality
    publisher = RegistryPublisher("/test/repo")
    success, message = publisher.publish_python_pypi()

    # Verify mock was called
    assert success is True
    mock_run_command.assert_called_once()
```

--------------------------------

### Test MCP get_manifest

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-02-28-mcp-arkiv-html-export-plan.md

Python code for testing the get_manifest tool, including setup for mock database and assertions.

```python
def test_get_manifest_all_tables(mock_db):
    mock_db.fetchall.side_effect = [
        [{'count': 100}],
        [{'count': 1000}],
        [{'count': 50}],
        [{'count': 200}],
        [{'language': 'Python', 'cnt': 500}, {'language': 'JavaScript', 'cnt': 300}],
        [{'started_at': '2023-01-01T10:00:00Z'}],
    ]
    with patch('repoindex.mcp.server._get_db', return_value=mock_db):
        from repoindex.mcp.server import _get_manifest_impl
        result = _get_manifest_impl()
    assert result['tables']['repos']['row_count'] == 100
    assert result['summary']['languages']['Python'] == 500
    assert result['summary']['last_refresh'] == '2023-01-01T10:00:00Z'
```

--------------------------------

### Built-in Source Directories

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-05-09-v2-source-hierarchy.md

Directory structure for built-in source implementations within the repoindex library.

```bash
repoindex/sources/forges/__init__.py     # github.py, gitea.py
repoindex/sources/registries/__init__.py # pypi, cran, zenodo, ...
repoindex/sources/scanners/__init__.py   # citation_cff, keywords, local_assets
```

--------------------------------

### Run full test suite

Source: https://github.com/queelius/repoindex/blob/master/docs/plans/2026-03-15-metadata-enrichment.md

Command to execute the full test suite with a maximum of 5 failures and quiet output.

```bash
pytest --maxfail=5 -q
```