# Zzup Usage Guide

## Overview

Zzup is a tool for managing OCI container images as packages, allowing you to extract specific directories from an image to your local filesystem. This guide covers the usage of the streamlined Zzup commands and configuration format.

## Configuration

Zzup uses a YAML configuration file (`zzup.yaml`) that maps image names to their configuration settings. These settings can override the defaults specified in the image's manifest.

### Configuration Format

```yaml
image-name:
  tag: latest
  sourceDir: /source/dir/ # Overrides manifest's sourceDir
  targetDir: /target/dir/ # Overrides manifest's targetDir
```

Each image entry contains:

- `tag`: The image tag to use (defaults to "latest")
- `sourceDir`: The directory inside the container to extract (overrides manifest)
- `targetDir`: The local directory where files will be extracted (overrides manifest)

## Commands

### Initialize Configuration

```bash
zzup init
```

Creates a new configuration file with default settings.

### List Images

```bash
zzup list [--image-name <name>]
```

Lists all configured images. If `--image-name` is specified, only shows information for that specific image.

### Update Images

```bash
zzup update [--image-name <name>] [--force]
```

Checks for updates and updates images if newer versions are available.

Options:

- `--image-name`: Only update the specified image
- `--force`: Force update even if no newer version is available

### Install Images

```bash
zzup install [--image-name <name>]
```

Installs images directly without checking for updates.

Options:

- `--image-name`: Only install the specified image

## Examples

### Basic Usage

```bash
# Initialize configuration
zzup init

# List all configured images
zzup list

# Update a specific image
zzup update --image-name zondax-make

# Install a specific image
zzup install --image-name zondax-make
```

### Configuration Example

```yaml
zondax-make:
  tag: latest
  sourceDir: .make
  targetDir: .make
```

## Note

The configuration in `zzup.yaml` takes precedence over the settings in the image's manifest file. This allows for local customization while keeping the manifest as the baseline configuration.

## Migration from Previous Versions

If you have a configuration in the old array format, you need to migrate to the new direct mapping format:

### Old Format (Deprecated)

```yaml
images:
  - name: zondax-make
    tag: latest
    sourceDir: /source/dir/
    targetDir: /target/dir/
```

### New Format

```yaml
zondax-make:
  tag: latest
  sourceDir: /source/dir/
  targetDir: /target/dir/
```

The following commands are no longer available:

- `config-add`
- `config-remove`
- `list-versions`
- `check-updates`

Their functionality has been consolidated into the streamlined commands listed above.