Skip to content

CONFIGURATION.md

Latest commit

 

History

History
1052 lines (846 loc) · 24.2 KB

CONFIGURATION.md

File metadata and controls

1052 lines (846 loc) · 24.2 KB

⚙️ gitshift Configuration Guide

Complete guide to configuring gitshift for multi-platform Git account management

📖 Table of Contents

  1. Configuration File Structure
  2. Account Configuration
  3. Global Settings
  4. Environment Variables
  5. SSH Configuration
  6. Zsh Secrets Integration
  7. Project-Specific Configuration
  8. Configuration Management
  9. Advanced Configuration

📁 Configuration File Structure

gitshift stores its configuration in ~/.config/gitshift/config.yaml:

# gitshift Configuration File
# Version: 1.0.0
# Last Updated: 2025-01-16T10:30:00Z

# Account configurations
accounts:
  personal:
    alias: personal
    name: John Doe
    email: john@personal.com
    ssh_key_path: /Users/john/.ssh/id_ed25519_personal
    github_username: johndoe
    description: Personal GitHub account
    is_default: true
    status: active
    created_at: "2025-01-15T10:30:00Z"
    last_used: "2025-01-16T09:15:00Z"
    missing_fields: []

  work:
    alias: work
    name: John Doe
    email: john@company.com
    ssh_key_path: /Users/john/.ssh/id_ed25519_work
    github_username: john-company
    description: Work account for Company Inc
    is_default: false
    status: active
    created_at: "2025-01-15T11:00:00Z"
    last_used: "2025-01-16T08:45:00Z"
    missing_fields: []

# Pending accounts (incomplete setup)
pending_accounts:
  client-project:
    alias: client-project
    github_username: john-client
    partial_data:
      name: "John Doe"
      email: "john@client.com"
    missing_fields: ["ssh_key_path"]
    source: "discovery"
    confidence: 85
    created_at: "2025-01-16T09:00:00Z"

# Current active account
current_account: personal

# Global settings
global_git_config: true
auto_detect: true
config_version: "1.0.0"

👤 Account Configuration

Account Fields

Field Type Required Description
alias string ✅ Unique identifier for the account
name string ✅ Git user.name
email string ✅ Git user.email (must be valid email)
ssh_key_path string ❌ Path to SSH private key file
platform string ❌ Platform type: github, gitlab, bitbucket (default: github)
domain string ❌ Platform domain (e.g., github.com, gitlab.company.com)
username string ✅ Platform-specific username
github_username string ⚠️ Deprecated: Use username with platform: github
api_endpoint string ❌ Custom API endpoint for self-hosted platforms
description string ❌ Human-readable description
is_default boolean ❌ Whether this is the default account
status string ❌ Account status (active, pending, disabled)
created_at timestamp ❌ When the account was created
last_used timestamp ❌ When the account was last used
missing_fields array ❌ List of missing required fields

⚠️ Deprecated Fields

Important: The following fields are deprecated but still supported for backward compatibility:

  • github_username: Use username + platform: github instead
    • Migration: Replace github_username: johndoe with platform: github and username: johndoe
    • Timeline: No removal planned - maintained indefinitely for backward compatibility
    • Recommendation: Update new accounts to use username + platform

Example Migration:

# Old format (deprecated but still works)
personal:
  alias: personal
  github_username: johndoe
  # ... other fields

# New format (recommended)
personal:
  alias: personal
  platform: github
  username: johndoe
  # ... other fields

See Multi-Platform Support Guide for detailed migration instructions.

Account Status Values

  • active: Account is fully configured and ready to use
  • pending: Account needs additional configuration
  • disabled: Account is temporarily disabled

Example Account Configurations

Personal Account

personal:
  alias: personal
  name: John Doe
  email: john@personal.com
  ssh_key_path: /Users/john/.ssh/id_ed25519_personal
  github_username: johndoe
  description: Personal GitHub account
  is_default: true
  status: active
  created_at: "2025-01-15T10:30:00Z"
  last_used: "2025-01-16T09:15:00Z"

Work Account

work:
  alias: work
  name: John Doe
  email: john@company.com
  ssh_key_path: /Users/john/.ssh/id_ed25519_work
  github_username: john-company
  description: Work account for Company Inc
  is_default: false
  status: active
  created_at: "2025-01-15T11:00:00Z"
  last_used: "2025-01-16T08:45:00Z"

Client Account

client-project:
  alias: client-project
  name: John Doe
  email: john@client.com
  ssh_key_path: /Users/john/.ssh/id_ed25519_client
  github_username: john-client
  description: Client project account
  is_default: false
  status: active
  created_at: "2025-01-15T12:00:00Z"

🌍 Multi-Platform Configuration

gitshift supports multiple Git hosting platforms including GitHub, GitLab, GitHub Enterprise, and self-hosted instances.

Supported Platforms

Platform Value SSH Support API Support Notes
GitHub github ✅ Full ✅ Full Default platform
GitHub Enterprise github ✅ Full ✅ Full Requires custom domain
GitLab gitlab ✅ Full ⚠️ Basic SSH fully functional
GitLab Self-Hosted gitlab ✅ Full ⚠️ Basic Requires custom domain
Bitbucket bitbucket 🚧 Planned 🚧 Planned Coming soon

Platform-Specific Account Examples

GitHub Account (Default)

personal-github:
  alias: personal-github
  name: John Doe
  email: john@personal.com
  ssh_key_path: ~/.ssh/id_ed25519_github_personal
  platform: github  # Can be omitted, defaults to github
  username: johndoe
  description: Personal GitHub account
  is_default: true

GitLab Account

personal-gitlab:
  alias: personal-gitlab
  name: John Doe
  email: john@personal.com
  ssh_key_path: ~/.ssh/id_ed25519_gitlab_personal
  platform: gitlab
  username: johndoe
  domain: gitlab.com  # Optional for gitlab.com
  description: Personal GitLab account

GitHub Enterprise

work-github:
  alias: work-github
  name: John Doe
  email: john@company.com
  ssh_key_path: ~/.ssh/id_ed25519_github_enterprise
  platform: github
  username: jdoe
  domain: github.company.com  # Required for enterprise
  api_endpoint: https://github.company.com/api/v3  # Optional
  description: Work GitHub Enterprise account

Self-Hosted GitLab

company-gitlab:
  alias: company-gitlab
  name: John Doe
  email: john@company.com
  ssh_key_path: ~/.ssh/id_ed25519_gitlab_company
  platform: gitlab
  username: jdoe
  domain: gitlab.company.com  # Required for self-hosted
  api_endpoint: https://gitlab.company.com/api/v4  # Optional
  description: Company GitLab instance

Multi-Platform Configuration Example

Complete configuration with multiple platforms:

accounts:
  # GitHub accounts
  personal-github:
    alias: personal-github
    platform: github
    username: johndoe
    name: John Doe
    email: john@personal.com
    ssh_key_path: ~/.ssh/id_ed25519_github_personal
    is_default: true

  work-github:
    alias: work-github
    platform: github
    username: jdoe-work
    name: John Doe
    email: john@work.com
    ssh_key_path: ~/.ssh/id_ed25519_github_work

  # GitLab accounts
  personal-gitlab:
    alias: personal-gitlab
    platform: gitlab
    username: johndoe
    name: John Doe
    email: john@personal.com
    ssh_key_path: ~/.ssh/id_ed25519_gitlab_personal

  # Self-hosted GitLab
  client-gitlab:
    alias: client-gitlab
    platform: gitlab
    domain: gitlab.client.com
    username: jdoe
    name: John Doe
    email: john@client.com
    ssh_key_path: ~/.ssh/id_ed25519_gitlab_client

current_account: personal-github

Platform Detection

gitshift automatically detects the platform from repository URLs:

# GitHub
git@github.com:user/repo.git       → Platform: github
https://github.com/user/repo.git   → Platform: github

# GitLab
git@gitlab.com:user/repo.git       → Platform: gitlab
https://gitlab.com/user/repo.git   → Platform: gitlab

# Self-hosted
git@gitlab.company.com:user/repo.git  → Platform: gitlab (custom domain)

Platform Usage Examples

# Add GitHub account
gitshift add personal --platform github --email john@personal.com

# Add GitLab account
gitshift add gitlab-personal --platform gitlab --email john@gitlab.com

# Add self-hosted GitLab
gitshift add company-gitlab \
  --platform gitlab \
  --domain gitlab.company.com \
  --email john@company.com

# Switch between platforms
gitshift switch personal-github    # GitHub
gitshift switch gitlab-personal    # GitLab
gitshift switch company-gitlab     # Self-hosted GitLab

Backward Compatibility

Existing GitHub-only configurations work without changes:

# Old format (still works)
personal:
  alias: personal
  github_username: johndoe  # Automatically mapped to username
  # platform defaults to github

Migration: No action required. Add platform and username fields when convenient last_used: "2025-01-16T07:30:00Z"


---

## 🌐 **Global Settings**

### **Global Configuration Options**

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `current_account` | string | `""` | Currently active account alias |
| `global_git_config` | boolean | `true` | Use global Git configuration |
| `auto_detect` | boolean | `true` | Enable automatic account detection |
| `config_version` | string | `"1.0.0"` | Configuration file version |

### **Global Settings Explained**

#### **global_git_config**
```yaml
global_git_config: true  # Use global Git configuration
global_git_config: false # Use local Git configuration only

When true:

  • Git configuration is set globally (git config --global)
  • All repositories use the same account settings
  • Faster switching between repositories

When false:

  • Git configuration is set locally per repository
  • Each repository can have different account settings
  • More granular control but requires manual setup

auto_detect

auto_detect: true  # Enable automatic account detection
auto_detect: false # Disable automatic account detection

When true:

  • gitshift automatically detects account based on repository
  • Uses .gitshift.yaml files in project directories
  • Provides seamless workflow integration

When false:

  • Manual account switching required
  • No automatic detection or switching
  • More predictable but less automated

🔧 Environment Variables

Core Environment Variables

Variable Default Description
gitshift_CONFIG_PATH ~/.config/gitshift Configuration directory path
gitshift_DEBUG false Enable debug logging
gitshift_SSH_DIR ~/.ssh SSH keys directory
gitshift_LOG_LEVEL info Logging level (debug, info, warn, error)

GitHub Integration Variables

Variable Default Description
GITHUB_CLI_PATH gh Path to GitHub CLI executable
GITHUB_TOKEN "" GitHub API token (managed by zsh_secrets)
GITHUB_API_URL https://api.github.com GitHub API base URL

SSH Configuration Variables

Variable Default Description
SSH_AUTH_SOCK "" SSH agent socket path
SSH_CONFIG_FILE ~/.ssh/config SSH configuration file path
SSH_KEY_DIR ~/.ssh SSH keys directory

Setting Environment Variables

Temporary (Current Session)

# Enable debug logging
export gitshift_DEBUG=true

# Set custom config path
export gitshift_CONFIG_PATH="/custom/path"

# Set custom SSH directory
export gitshift_SSH_DIR="/custom/ssh"

Permanent (Shell Profile)

Add to ~/.zshrc, ~/.bashrc, or ~/.profile:

# gitshift Configuration
export gitshift_CONFIG_PATH="$HOME/.config/gitshift"
export gitshift_DEBUG=false
export gitshift_SSH_DIR="$HOME/.ssh"
export gitshift_LOG_LEVEL="info"

# GitHub CLI Configuration
export GITHUB_CLI_PATH="gh"
export GITHUB_API_URL="https://api.github.com"

Project-Specific (Environment File)

Create .env file in project directory:

# .env
gitshift_DEBUG=true
gitshift_LOG_LEVEL=debug
GITHUB_TOKEN=ghp_your_token_here

🔐 SSH Configuration

SSH Key Configuration

SSH Key Paths

# Recommended SSH key naming convention
ssh_key_path: "/Users/john/.ssh/id_ed25519_personal"
ssh_key_path: "/Users/john/.ssh/id_ed25519_work"
ssh_key_path: "/Users/john/.ssh/id_ed25519_client"

SSH Key Types

# Ed25519 (recommended)
ssh_key_path: "/Users/john/.ssh/id_ed25519_personal"

# RSA (legacy)
ssh_key_path: "/Users/john/.ssh/id_rsa_work"

# ECDSA
ssh_key_path: "/Users/john/.ssh/id_ecdsa_client"

SSH Config Integration

gitshift can generate SSH configuration entries:

# Generate SSH config
gitshift ssh-config generate

Generated SSH Config Example:

# SSH Configuration for gitshift
# Generated automatically - do not edit manually

Host github-personal
    HostName github.com
    User git
    IdentityFile /Users/john/.ssh/id_ed25519_personal
    IdentitiesOnly yes
    UseKeychain yes
    AddKeysToAgent yes

Host github-work
    HostName github.com
    User git
    IdentityFile /Users/john/.ssh/id_ed25519_work
    IdentitiesOnly yes
    UseKeychain yes
    AddKeysToAgent yes

SSH Agent Configuration

SSH Agent Settings

# SSH Agent configuration
ssh_agent:
  auto_start: true
  socket_path: "~/.ssh/socket"
  key_lifetime: "3600"  # seconds
  max_keys: 10

SSH Socket Directories

# gitshift creates these directories automatically
~/.ssh/socket/     # SSH agent sockets
~/.ssh/sockets/    # Additional socket storage
~/.ssh/control/    # SSH control connections

🔒 Zsh Secrets Integration

Zsh Secrets Configuration

gitshift automatically manages GITHUB_TOKEN in your zsh_secrets file:

Supported File Locations

# Priority order (first found is used)
zsh_secrets_locations:
  - "~/.zsh_secrets"
  - "~/.config/zsh_secrets"
  - "~/.secrets/zsh_secrets"
  - "~/.zsh/secrets"

Zsh Secrets File Format

# ~/.zsh_secrets
# gitshift managed file - do not edit manually

# GitHub Token (updated automatically)
export GITHUB_TOKEN="ghp_your_token_here"

# Other secrets
export API_KEY="your_api_key"
export DATABASE_URL="your_database_url"

Zsh Secrets Management

Configuration Options

# Zsh secrets configuration
zsh_secrets:
  auto_update: true
  auto_reload: true
  backup_enabled: true
  backup_count: 5
  file_permissions: "0600"

Manual Management

# Update token manually
gitshift secrets update-token

# Get current token
gitshift secrets get-token

# Validate zsh_secrets file
gitshift secrets validate

# Backup zsh_secrets file
gitshift secrets backup

# Restore from backup
gitshift secrets restore --backup 1

📁 Project-Specific Configuration

Project Configuration File

Create .gitshift.yaml in your project directory:

# .gitshift.yaml
account: work
description: "Work project - use work account"
created_at: "2025-01-16T10:00:00Z"
auto_switch: true
git_config:
  user.name: "John Doe"
  user.email: "john@company.com"
ssh_config:
  host: "github-work"
  identity_file: "/Users/john/.ssh/id_ed25519_work"

Project Configuration Fields

Field Type Required Description
account string ✅ Account alias to use
description string ❌ Project description
created_at timestamp ❌ When config was created
auto_switch boolean ❌ Auto-switch when entering directory
git_config object ❌ Override Git configuration
ssh_config object ❌ Override SSH configuration

Project Configuration Examples

Basic Project Config

# .gitshift.yaml
account: work
description: "Company project"

Advanced Project Config

# .gitshift.yaml
account: client-project
description: "Client project with specific requirements"
auto_switch: true
git_config:
  user.name: "John Doe"
  user.email: "john@client.com"
  core.editor: "code"
  init.defaultBranch: "main"
ssh_config:
  host: "github-client"
  identity_file: "/Users/john/.ssh/id_ed25519_client"
  port: 22
  compression: true

🛠️ Configuration Management

Configuration Commands

View Configuration

# Show current configuration
gitshift config show

# Show specific account
gitshift config show --account work

# Show in different formats
gitshift config show --format yaml
gitshift config show --format json
gitshift config show --format toml

Edit Configuration

# Edit configuration file
gitshift config edit

# Edit specific account
gitshift config edit --account work

# Edit with specific editor
gitshift config edit --editor vim

Set Configuration Values

# Set global settings
gitshift config set global_git_config false
gitshift config set auto_detect true

# Set account-specific settings
gitshift config set --account work email "new@email.com"
gitshift config set --account work ssh_key_path "/new/path"

Validate Configuration

# Validate entire configuration
gitshift config validate

# Validate specific account
gitshift config validate --account work

# Fix configuration issues
gitshift config validate --fix

Configuration Backup and Restore

Backup Configuration

# Create backup
gitshift config backup

# Create backup with description
gitshift config backup --description "Before major changes"

# List backups
gitshift config backup --list

Restore Configuration

# Restore from latest backup
gitshift config restore

# Restore from specific backup
gitshift config restore --backup 1

# Restore with confirmation
gitshift config restore --confirm

🔧 Advanced Configuration

Custom SSH Configuration

SSH Config Templates

# Custom SSH config template
ssh_config_template: |
  Host github-{{.Alias}}
      HostName github.com
      User git
      IdentityFile {{.SSHKeyPath}}
      IdentitiesOnly yes
      UseKeychain yes
      AddKeysToAgent yes
      ServerAliveInterval 60
      ServerAliveCountMax 3

SSH Key Generation Settings

# SSH key generation configuration
ssh_key_generation:
  default_type: "ed25519"
  default_size: 256
  default_comment: "{{.Email}}"
  key_directory: "~/.ssh"
  naming_pattern: "id_{{.Type}}_{{.Alias}}"
  permissions: "0600"

GitHub Integration Settings

GitHub API Configuration

# GitHub API settings
github:
  api_url: "https://api.github.com"
  timeout: 30
  retry_count: 3
  retry_delay: 1
  rate_limit: 5000

GitHub CLI Integration

# GitHub CLI settings
github_cli:
  enabled: true
  path: "gh"
  auth_method: "oauth"
  scopes: ["repo", "read:user", "user:email", "admin:public_key"]

Logging Configuration

Log Settings

# Logging configuration
logging:
  level: "info"  # debug, info, warn, error
  format: "json"  # json, text
  output: "file"  # file, stdout, stderr
  file_path: "~/.config/gitshift/logs/gitshift.log"
  max_size: "10MB"
  max_backups: 5
  max_age: 30
  compress: true

Debug Configuration

# Debug settings
debug:
  enabled: false
  verbose_output: false
  performance_metrics: false
  memory_profiling: false
  cpu_profiling: false

Performance Configuration

Performance Settings

# Performance configuration
performance:
  cache_enabled: true
  cache_ttl: 300  # seconds
  parallel_operations: 4
  timeout: 30  # seconds
  retry_attempts: 3
  retry_delay: 1  # seconds

Validation Settings

# Validation configuration
validation:
  ssh_timeout: 10  # seconds
  github_timeout: 15  # seconds
  git_timeout: 5  # seconds
  retry_count: 3
  parallel_validation: true

🔍 Configuration Validation

Validation Rules

Account Validation

# Account validation rules
account_validation:
  required_fields: ["alias", "name", "email", "github_username"]
  email_format: true
  github_username_format: true
  ssh_key_exists: true
  ssh_key_permissions: "0600"
  unique_alias: true
  unique_email: false
  unique_github_username: true

SSH Validation

# SSH validation rules
ssh_validation:
  key_exists: true
  key_readable: true
  key_permissions: "0600"
  key_format: true
  github_authentication: true
  agent_connection: true

Git Validation

# Git validation rules
git_validation:
  git_installed: true
  config_valid: true
  user_name_set: true
  user_email_set: true
  ssh_command_set: true

Validation Commands

# Validate entire configuration
gitshift config validate

# Validate specific components
gitshift config validate --accounts
gitshift config validate --ssh
gitshift config validate --git

# Validate with fixes
gitshift config validate --fix

# Validate with detailed output
gitshift config validate --verbose

📚 Configuration Examples

Complete Configuration Example

# Complete gitshift Configuration
# This is a comprehensive example showing all available options

# Account configurations
accounts:
  personal:
    alias: personal
    name: John Doe
    email: john@personal.com
    ssh_key_path: /Users/john/.ssh/id_ed25519_personal
    github_username: johndoe
    description: Personal GitHub account
    is_default: true
    status: active
    created_at: "2025-01-15T10:30:00Z"
    last_used: "2025-01-16T09:15:00Z"

  work:
    alias: work
    name: John Doe
    email: john@company.com
    ssh_key_path: /Users/john/.ssh/id_ed25519_work
    github_username: john-company
    description: Work account for Company Inc
    is_default: false
    status: active
    created_at: "2025-01-15T11:00:00Z"
    last_used: "2025-01-16T08:45:00Z"

# Current active account
current_account: personal

# Global settings
global_git_config: true
auto_detect: true
config_version: "1.0.0"

# Advanced configuration
ssh_config:
  auto_generate: true
  template: |
    Host github-{{.Alias}}
        HostName github.com
        User git
        IdentityFile {{.SSHKeyPath}}
        IdentitiesOnly yes
        UseKeychain yes

zsh_secrets:
  auto_update: true
  auto_reload: true
  backup_enabled: true
  file_permissions: "0600"

logging:
  level: "info"
  format: "json"
  file_path: "~/.config/gitshift/logs/gitshift.log"

performance:
  cache_enabled: true
  cache_ttl: 300
  parallel_operations: 4
  timeout: 30

🚨 Configuration Troubleshooting

Common Configuration Issues

Invalid YAML Syntax

# Check YAML syntax
gitshift config validate

# Fix YAML syntax errors
gitshift config validate --fix

Missing Required Fields

# Check for missing fields
gitshift config validate --accounts

# Fix missing fields
gitshift config validate --fix

Invalid File Permissions

# Check file permissions
ls -la ~/.config/gitshift/config.yaml

# Fix permissions
chmod 600 ~/.config/gitshift/config.yaml

Configuration Recovery

Reset to Defaults

# Reset configuration to defaults
gitshift config reset

# Reset specific account
gitshift config reset --account work

Restore from Backup

# List available backups
gitshift config backup --list

# Restore from backup
gitshift config restore --backup 1

Need help with configuration? Check our Troubleshooting Guide or User Guide!