Configuration¶

Customize gi behavior with configuration options and environment variables.

🔧 Configuration Methods¶

1. Environment Variables¶

Set environment variables to customize behavior:

# Custom cache directory
export GI_CACHE_DIR="/path/to/custom/cache"

# Custom source repository
export GI_SOURCE_URL="custom/gitignore-repo"

# Disable caching
export GI_NO_CACHE="true"

2. Configuration File¶

Create a gi.yml file in your home directory:

# ~/.config/gi.yml or ~/gi.yml
cache:
  directory: ~/.cache/gi
  ttl: 86400  # 24 hours in seconds

source:
  url: github/gitignore
  branch: main

output:
  format: gitignore
  header: true
  comments: true

3. Command Line Options¶

Override settings per command:

# Use custom output
gi main python -o custom/.gitignore

# Force refresh
gi main python --update-index

# Disable cache
gi main python --no-cache

📁 Cache Configuration¶

Default Cache Locations¶

Platform	Cache Directory
Linux	`~/.cache/gi`
macOS	`~/.cache/gi`
Windows	`%LOCALAPPDATA%\gi\cache`

Custom Cache Directory¶

# Set custom cache directory
export GI_CACHE_DIR="/path/to/custom/cache"

# Or use command line
gi main python --cache-dir /path/to/custom/cache

Cache Management¶

# Check cache status
gi doctor

# Clear cache manually
rm -rf ~/.cache/gi  # Linux/macOS
rmdir /s %LOCALAPPDATA%\gi\cache  # Windows

# Refresh cache
gi main python --update-index

🌐 Network Configuration¶

Proxy Settings¶

# HTTP proxy
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# SOCKS proxy
export HTTP_PROXY="socks5://proxy.company.com:1080"
export HTTPS_PROXY="socks5://proxy.company.com:1080"

Custom Source Repository¶

# Use custom repository
export GI_SOURCE_URL="your-org/custom-gitignore"

# Or specify in command
gi main python --from your-org/custom-gitignore

Offline Mode¶

# Disable network requests
export GI_NO_CACHE="true"

# Use only cached templates
gi main python  # Will use cached templates only

🎨 Output Configuration¶

File Format Options¶

# Default .gitignore format
gi main python

# Custom output location
gi main python -o my-project/.gitignore

# Append to existing file
gi main python -a existing/.gitignore

Header Customization¶

The generated .gitignore includes headers by default:

# Generated by gi
# Templates: Python
# Generated: 2024-01-15 10:30:00

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
...

Disable Headers¶

# Disable headers (not currently supported)
# This would require code changes

🔍 Debugging Configuration¶

Verbose Output¶

# Enable verbose logging
export GI_VERBOSE="true"

# Or use debug mode
gi main python --verbose

Diagnostic Information¶

# Show system information
gi doctor

# Show detailed cache info
gi doctor --verbose

🚨 Troubleshooting¶

Common Issues¶

Cache Permission Errors¶

# Fix cache permissions
chmod -R 755 ~/.cache/gi  # Linux/macOS

Network Connection Issues¶

# Check network connectivity
curl -I https://api.github.com/repos/github/gitignore/contents

# Use cached templates
gi main python  # Works offline

Template Not Found¶

# Refresh template index
gi main python --update-index

# Check available templates
gi list

Debug Commands¶

# Check configuration
gi doctor

# Test network connectivity
gi main python --update-index

# Verify cache
ls -la ~/.cache/gi  # Linux/macOS
dir %LOCALAPPDATA%\gi\cache  # Windows

📋 Configuration Examples¶

Development Setup¶

# ~/.config/gi.yml
cache:
  directory: ~/.cache/gi
  ttl: 3600  # 1 hour for development

source:
  url: github/gitignore
  branch: main

output:
  format: gitignore
  header: true

Production Setup¶

# ~/.config/gi.yml
cache:
  directory: /var/cache/gi
  ttl: 86400  # 24 hours

source:
  url: github/gitignore
  branch: main

output:
  format: gitignore
  header: true

Offline Setup¶

# ~/.config/gi.yml
cache:
  directory: ~/.cache/gi
  ttl: 604800  # 1 week

source:
  url: github/gitignore
  branch: main

output:
  format: gitignore
  header: true

🔧 Advanced Configuration¶

Custom Template Sources¶

# Use custom repository
export GI_SOURCE_URL="your-org/custom-gitignore"

# Use specific branch
export GI_SOURCE_BRANCH="custom-branch"

Performance Tuning¶

# Increase cache TTL for better performance
export GI_CACHE_TTL="86400"  # 24 hours

# Use local repository
export GI_SOURCE_URL="file:///path/to/local/repo"

Security Configuration¶

# Use HTTPS only
export GI_HTTPS_ONLY="true"

# Custom CA bundle
export GI_CA_BUNDLE="/path/to/ca-bundle.pem"

📚 FAQ¶

Q: How do I change the cache directory?¶

A: Set the GI_CACHE_DIR environment variable:

export GI_CACHE_DIR="/path/to/custom/cache"

Q: How do I use a custom template repository?¶

A: Set the GI_SOURCE_URL environment variable:

export GI_SOURCE_URL="your-org/custom-gitignore"

Q: How do I disable caching?¶

A: Set the GI_NO_CACHE environment variable:

export GI_NO_CACHE="true"

Q: How do I use a proxy?¶

A: Set the standard proxy environment variables:

export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

Q: How do I debug issues?¶

A: Use the gi doctor command and check the verbose output:

gi doctor --verbose

Next: Advanced Usage to learn about power user features!