# How Sideways Copy Videos Works With video_path in docker-icloudpd

> Learn how the sideways copy videos feature in docker-icloudpd duplicates or moves iCloud videos to your video_path directory. Preserve structure and permissions with ease.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**The sideways copy videos feature duplicates or moves downloaded iCloud videos to a secondary directory specified by `video_path`, preserving folder structure and permissions while supporting both incremental and full-archive modes.**

The docker-icloudpd container supports a **sideways copy videos** capability that mirrors your downloaded videos to a separate location using the **`video_path`** environment variable. This feature, implemented in the [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) and [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) scripts, creates a parallel video archive without interfering with iCloud Photo Downloader's primary download directory.

## Configuration Requirements

To enable sideways copying, you must define three environment variables in your `.env` file or [`docker-compose.yml`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/docker-compose.yml):

- `sideways_copy_videos=true` – Activates the feature
- `video_path=/path/to/videos` – The destination directory for video files
- `sideways_copy_videos_mode=copy|move` – Determines whether to duplicate or relocate files

According to [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) at line 381, the container automatically creates the `video_path` directory during initialization and aligns its ownership and permissions with the main download directory. However, if you set `sideways_copy_videos_mode=move`, the script enforces that `delete_after_download` must also be `true` to prevent the same videos from being re-downloaded on subsequent syncs (see [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) lines 20–24).

## Runtime Validation

Before executing any file operations, [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) validates that `video_path` is properly configured. At lines 1526–1534, the script verifies the variable is defined and points to an existing directory. If validation fails, the container aborts with a descriptive error message rather than attempting partial copies.

## How the Copy Process Works

The implementation distinguishes between two workflows: copying only newly downloaded videos or copying the entire existing archive.

### Building the File List

The system uses different methods to identify videos depending on the operation scope:

**Incremental copying (`sideways_copy_videos`)**: At lines 8198–8220 in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh), the script parses the iCloudPD sync log located at `/tmp/icloudpd/icloudpd_sync.log`. It filters for `.mov` and `.mp4` entries while excluding `hevc.mov` files, deduplicates the list, and derives destination sub-folders from the relative paths recorded in the log.

**Full archive copying (`sideways_copy_all_videos`)**: When invoked with the `--sideways-copy-all-videos` flag, the script walks the entire `download_path` tree using the `find` command (lines 1538–1549). It collects all `*.mp4` and `*.mov` files (again excluding `hevc.mov`) and maps the complete folder structure for replication under `video_path`.

### Directory Creation and Permissions

For each required sub-directory under `video_path`, the script creates the directory if it does not exist and mirrors the source folder's ownership and permissions. At lines 1550–1559 in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh), the implementation uses `chown --reference` and `chmod --reference` to ensure the secondary location maintains identical access controls to the primary download directory.

### File Operations

The actual transfer occurs at lines 1665–1672:

- **Copy mode**: Executes `cp --update=none --preserve` to duplicate files while skipping existing entries and preserving timestamps
- **Move mode**: Executes `mv --update=none --preserve` to relocate files, but only when `delete_after_download=true` is confirmed

Each operation is logged via `log_debug` for audit purposes.

## Usage Examples

### Docker Compose Configuration

Mount a dedicated volume for your video archive and reference it in the environment:

```yaml
services:
  icloudpd:
    image: boredazfcuk/docker-icloudpd:latest
    environment:
      - sideways_copy_videos=true
      - video_path=/videos/icloud
      - sideways_copy_videos_mode=copy
    volumes:
      - icloud-data:/data
      - /mnt/media/videos:/videos/icloud

```

### Environment File for Copy Mode

```dotenv
sideways_copy_videos=true
video_path=/videos/icloud
sideways_copy_videos_mode=copy
delete_after_download=false

```

### Environment File for Move Mode

```dotenv
sideways_copy_videos=true
video_path=/videos/icloud
sideways_copy_videos_mode=move
delete_after_download=true

```

### Manual Full Archive Copy

To copy all existing videos without waiting for a new sync, execute inside the container:

```bash
./sync-icloud.sh --sideways-copy-all-videos

```

## Summary

- The **sideways copy videos** feature creates a parallel video archive at the location specified by **`video_path`**
- **[`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh)** handles directory creation and validates that move mode requires `delete_after_download=true`
- **[`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh)** implements two workflows: incremental copying from sync logs and full archive copying via `find`
- File permissions are preserved using `--reference` flags during directory creation
- The feature supports both **copy** (duplicate files) and **move** (relocate files) modes via `sideways_copy_videos_mode`

## Frequently Asked Questions

### What is the difference between copy and move mode?

**Copy mode** duplicates videos to `video_path` while keeping the originals in the iCloud download directory, suitable for creating backups or feeding media servers. **Move mode** relocates videos to `video_path` and removes them from the download directory, requiring `delete_after_download=true` to prevent re-download loops.

### Can I use sideways copy with delete_after_download disabled?

You can use copy mode with `delete_after_download=false`, but move mode explicitly requires `delete_after_download=true`. The validation logic in [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) prevents dangerous configurations that would cause continuous re-downloading of moved files.

### How do I copy existing videos without re-downloading?

Invoke the manual command `./sync-icloud.sh --sideways-copy-all-videos` inside the container. This triggers the `sideways_copy_all_videos()` function which scans your existing `download_path` for all video files and copies them to `video_path` without initiating a new iCloud sync.

### What video file types are supported?

The feature processes files with `.mov` and `.mp4` extensions while explicitly excluding `hevc.mov` files. This filtering occurs whether building the list from sync logs or walking the directory tree with `find`.