shell/completions/README.md

Bash Completion for Shell Scripts

This directory contains bash completion scripts for various shell utilities in this repository.

Overview

The completion system provides intelligent tab completion for command-line flags and options for all backup scripts in this repository. It's automatically installed and configured by the setup scripts.

Supported Scripts

backup-immich.sh

• --help, -h - Show help message
• --dry-run - Preview backup without executing
• --no-upload - Skip B2 upload (local backup only)
• --verbose - Enable verbose logging

backup-plex.sh

• --help, -h - Show help message
• --auto-repair - Automatically attempt to repair corrupted databases
• --check-integrity - Only check database integrity, don't backup
• --non-interactive - Run in non-interactive mode (for automation)
• --no-parallel - Disable parallel verification (slower but safer)
• --no-performance - Disable performance monitoring
• --webhook=URL - Send notifications to webhook URL
• --email=ADDRESS - Send notifications to email address

backup-media.sh

• --help, -h - Show help message
• --dry-run - Show what would be backed up without actually doing it
• --no-verify - Skip backup verification
• --sequential - Run backups sequentially instead of in parallel
• --interactive - Ask for confirmation before each backup
• --webhook URL - Custom webhook URL for notifications

Generic backup scripts (backup-docker.sh, etc.)

• --help, -h - Show help message
• --dry-run - Preview mode
• --verbose - Verbose output
• --no-upload - Skip upload operations
• --webhook - Webhook URL for notifications

Installation

The completion system is automatically installed when you run the setup scripts:

1. bootstrap.sh - Makes completion scripts executable
2. setup.sh - Copies completion scripts to the user's local completion directory (~/.local/share/bash-completion/completions/)
3. .zshrc - Sources the completion scripts in zsh with bash compatibility mode

Automatic Setup Process

When you run ./setup/bootstrap.sh or ./setup/setup.sh, the system will:

• Install bash completion support in zsh
• Copy completion scripts to the standard completion directory
• Ensure completion scripts are executable
• Source the completion in your shell configuration

Manual Installation

If you need to install manually or re-install:

# Enable bash completion compatibility in zsh
autoload -U +X bashcompinit && bashcompinit
autoload -U compinit && compinit -u

# Load custom backup scripts completion
if [ -f "$HOME/shell/completions/backup-scripts-completion.bash" ]; then
    source "$HOME/shell/completions/backup-scripts-completion.bash"
fi

Usage Examples

Basic Tab Completion

# Type the script name and start typing an option
$ backup-immich.sh --<TAB>
--help  --dry-run  --no-upload  --verbose

# Continue typing to filter
$ backup-immich.sh --d<TAB>
$ backup-immich.sh --dry-run

Webhook URL Completion

# For scripts that support webhook URLs
$ backup-plex.sh --webhook <TAB>
https://notify.peterwood.rocks/lab

# Or for inline webhook options
$ backup-plex.sh --webhook=<TAB>
https://notify.peterwood.rocks/lab

Path-based Completion

Completion works with various invocation methods:

# Direct script name (if in PATH)
backup-immich.sh --<TAB>

# Relative path
./backup-immich.sh --<TAB>

# Absolute path  
/home/acedanger/shell/immich/backup-immich.sh --<TAB>

Features

Intelligent Argument Completion

• Flag completion: All available flags for each script
• Value completion: Suggests common values for specific options
• Context-aware: Different completions based on script type

Cross-Script Support

• Specific completions: Tailored for each backup script
• Generic fallback: Common options for any backup script
• Pattern matching: Automatic completion for *backup*.sh scripts

Advanced Features

• Webhook URL suggestions: Common webhook endpoints
• Email address completion: For notification options
• Multi-word option support: Handles --option value and --option=value

Troubleshooting

Completion Not Working

1. Verify the completion script is sourced:

   complete -p | grep backup
   

2. Reload your shell configuration:

   source ~/.zshrc
   

3. Check if bashcompinit is enabled:

   # Should be in your .zshrc
   autoload -U +X bashcompinit && bashcompinit
   

Adding New Scripts

To add completion for a new backup script:

1. Add the script patterns to the completion file
2. Define specific options for the script
3. Register the completion function

Example:

# Add to backup-scripts-completion.bash
complete -F _backup_generic_completion your-new-backup-script.sh

Development

Testing Completions

Use the test script to verify completions work:

./test-completion.sh

Adding New Options

1. Update the relevant completion function in backup-scripts-completion.bash
2. Add the new option to the opts variable
3. Handle any special argument completion if needed
4. Test the completion with compgen -W "options" -- "prefix"

Custom Completion Functions

Each script can have its own completion function following this pattern:

_script_name_completion() {
    local cur prev opts
    COMPREPLY=()
    cur="${COMP_WORDS[COMP_CWORD]}"
    prev="${COMP_WORDS[COMP_CWORD-1]}"
    
    opts="--option1 --option2 --option3"
    
    # Handle special cases
    case "${prev}" in
        --special-option)
            COMPREPLY=( $(compgen -W "value1 value2" -- ${cur}) )
            return 0
            ;;
    esac
    
    # Standard flag completion
    if [[ ${cur} == -* ]]; then
        COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
        return 0
    fi
}