Configuration

Learn how to configure cpm for your specific workflow and environment.

Configuration File

cpm uses a YAML configuration file located at ~/.cpm/config.yaml.

Default Configuration

After running cpm init, the default configuration looks like:

# cpm Configuration File

# Database settings
database:
  path: ~/.cpm/cpm.db
  backup_enabled: true
  backup_interval: 24h

# Git settings
git:
  default_branch: main
  auto_fetch: true
  auto_push: false
  ssh_key_path: ~/.ssh/id_rsa

# Server settings
servers:
  timeout: 30s
  retry_attempts: 3
  concurrent_syncs: 5

# SSH settings
ssh:
  key_storage: ~/.cpm/ssh
  key_type: ed25519
  key_bits: 256

# Logging
logging:
  level: info
  file: ~/.cpm/cpm.log
  max_size: 10M
  max_backups: 5

# Defaults
defaults:
  organization: ""
  clone_path: ~/repositories

Configuration Options

Database Settings

Configure the SQLite database:

database:
  path: ~/.cpm/cpm.db          # Database location
  backup_enabled: true            # Enable automatic backups
  backup_interval: 24h            # Backup every 24 hours
  backup_path: ~/.cpm/backups   # Backup directory

Git Settings

Control Git behavior:

git:
  default_branch: main           # Default branch name
  auto_fetch: true               # Auto-fetch on sync
  auto_push: false               # Auto-push after commits
  ssh_key_path: ~/.ssh/id_rsa   # Default SSH key
  username: ""                   # Default Git username
  email: ""                      # Default Git email

Server Settings

Configure server connections:

servers:
  timeout: 30s                   # Request timeout
  retry_attempts: 3              # Retry failed requests
  concurrent_syncs: 5            # Parallel sync operations
  rate_limit: 100                # Requests per minute
  user_agent: "cpm/0.1.0"      # HTTP user agent

SSH Settings

Manage SSH keys:

ssh:
  key_storage: ~/.cpm/ssh       # Key storage directory
  key_type: ed25519              # Key algorithm (rsa, ed25519, ecdsa)
  key_bits: 256                  # Key size (4096 for RSA, 256 for ed25519)
  passphrase_protected: false    # Require passphrase
  auto_add_to_agent: true        # Add to ssh-agent

Logging

Configure logging behavior:

logging:
  level: info                    # Levels: debug, info, warn, error
  file: ~/.cpm/cpm.log        # Log file location
  console: true                  # Also log to console
  max_size: 10M                  # Max file size before rotation
  max_backups: 5                 # Number of old logs to keep
  max_age: 30                    # Max days to keep logs
  compress: true                 # Compress old logs

Defaults

Set default values:

defaults:
  organization: myorg            # Default organization
  clone_path: ~/repositories     # Default clone directory
  visibility: private            # Default repo visibility
  auto_init: true               # Auto-initialize repos

Managing Configuration

View Configuration

View the current configuration:

cpm config list

View a specific setting:

cpm config get git.default_branch

Update Configuration

Update a setting:

cpm config set git.default_branch main
cpm config set git.auto_push true
cpm config set logging.level debug

Reset Configuration

Reset to defaults:

cpm config reset

Reset a specific setting:

cpm config reset git.auto_push

Environment Variables

cpm supports environment variables that override configuration:

# Database location
export GITM_DB_PATH=/custom/path/cpm.db

# Log level
export GITM_LOG_LEVEL=debug

# SSH key path
export GITM_SSH_KEY=~/.ssh/custom_key

# Server timeout
export GITM_TIMEOUT=60s

# Default organization
export GITM_DEFAULT_ORG=myorg

Server-Specific Configuration

Configure individual servers:

server_configs:
  github:
    api_url: https://api.github.com
    token: ghp_xxxxxxxxxxxx
    ssh_domain: github.com
    rate_limit: 5000

  gitlab:
    api_url: https://gitlab.com/api/v4
    token: glpat-xxxxxxxxxxxx
    ssh_domain: gitlab.com
    rate_limit: 2000

  gitea:
    api_url: https://git.company.com
    token: xxxxxxxxxxxxxxxx
    ssh_domain: git.company.com
    verify_ssl: false

Advanced Configuration

Custom Hooks

Configure hooks for automation:

hooks:
  pre_clone:
    - echo "Cloning repository..."

  post_clone:
    - cd ${REPO_PATH}
    - npm install

  pre_sync:
    - echo "Starting sync..."

  post_sync:
    - echo "Sync complete"

Templates

Configure repository templates:

templates:
  go_project:
    files:
      - .gitignore
      - README.md
      - go.mod
    commands:
      - go mod init ${REPO_NAME}

  node_project:
    files:
      - .gitignore
      - README.md
      - package.json
    commands:
      - npm init -y

Filters

Configure sync filters:

filters:
  include_organizations:
    - myorg
    - team-alpha

  exclude_repositories:
    - "*/archived-*"
    - "*/test-*"

  include_languages:
    - Go
    - JavaScript
    - Python

Configuration Best Practices

1. Use Environment-Specific Configs

Create different configs for different environments:

# Development
cp ~/.cpm/config.yaml ~/.cpm/config.dev.yaml

# Production
cp ~/.cpm/config.yaml ~/.cpm/config.prod.yaml

# Use specific config
cpm --config ~/.cpm/config.dev.yaml repo list

2. Secure Sensitive Data

Never commit tokens or keys. Use environment variables:

servers:
  github:
    token: ${GITHUB_TOKEN}
  gitlab:
    token: ${GITLAB_TOKEN}

3. Regular Backups

Enable automatic backups:

database:
  backup_enabled: true
  backup_interval: 6h
  backup_path: ~/.cpm/backups
  backup_retention: 7d

4. Optimize for Performance

Adjust concurrent operations:

servers:
  concurrent_syncs: 10           # Increase for faster syncs
  timeout: 60s                   # Increase for slow networks
  rate_limit: 100               # Adjust per server limits

Configuration Examples

Example 1: Multi-Server Setup

server_configs:
  github:
    api_url: https://api.github.com
    token: ${GITHUB_TOKEN}

  gitlab:
    api_url: https://gitlab.com/api/v4
    token: ${GITLAB_TOKEN}

  company:
    api_url: https://git.company.com
    token: ${COMPANY_TOKEN}
    verify_ssl: false

servers:
  concurrent_syncs: 15
  timeout: 45s

Example 2: Development Workflow

git:
  auto_fetch: true
  auto_push: false
  default_branch: develop

defaults:
  clone_path: ~/dev
  organization: myteam

logging:
  level: debug
  console: true

Example 3: Production Deployment

git:
  auto_fetch: true
  auto_push: true
  default_branch: main

database:
  backup_enabled: true
  backup_interval: 1h

logging:
  level: warn
  console: false
  max_backups: 30

servers:
  timeout: 30s
  retry_attempts: 5

Troubleshooting Configuration

Validation

Validate your configuration:

cpm config validate

View Effective Config

See the actual configuration being used (including environment variables):

cpm config show --effective

Debug Configuration Loading

Enable debug logging to see configuration loading:

GITM_LOG_LEVEL=debug cpm config list

Next Steps

See Also