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:

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

   ```bash
   complete -p | grep backup
   ```

2. Reload your shell configuration:

   ```bash
   source ~/.zshrc
   ```

3. Check if bashcompinit is enabled:

   ```bash
   # 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:

```bash
# 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:

```bash
./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:

```bash
_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
}
```