PHPackages                             mikomagni/statamic-asset-sync-pro - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. mikomagni/statamic-asset-sync-pro

ActiveStatamic-addon[DevOps & Deployment](/categories/devops)

mikomagni/statamic-asset-sync-pro
=================================

Statamic Asset Sync Pro - Keep your assets in sync between environments, and keep your Git clean.

1.0.3(11mo ago)054proprietaryPHPPHP ^8.1

Since Jul 25Pushed 7mo agoCompare

[ Source](https://github.com/mikomagni/statamic-asset-sync-pro)[ Packagist](https://packagist.org/packages/mikomagni/statamic-asset-sync-pro)[ Docs](https://clandestina.com.au)[ RSS](/packages/mikomagni-statamic-asset-sync-pro/feed)WikiDiscussions main Synced yesterday

READMEChangelog (4)Dependencies (3)Versions (6)Used By (0)

Statamic Asset Sync Pro
=======================

[](#statamic-asset-sync-pro)

Keep your assets in sync between environments, and keep your Git clean. A powerful rsync-based addon for transferring files between local and remote servers.

Why Use This Addon?
-------------------

[](#why-use-this-addon)

While Statamic Pro includes Git automation for content deployment, this addon is designed for managing **assets, images, and larger files** that you typically don't want to store in Git:

- **Asset Management**: Efficiently sync `public/assets`, `public/images`, and uploaded files
- **Large Files**: Handle media files, downloads, and user-generated content without bloating your Git repository
- **Complementary to Git**: Works alongside Git automation - use Git for code and content, rsync for assets
- **Performance**: Fast incremental transfers only sync changed files, saving time and bandwidth
- **Selective Sync**: Choose exactly which directories to sync with granular control

**Perfect for scenarios like:**

- Multi-environment workflows: Sync assets between local ↔ staging ↔ production environments
- Development with real data: Pull production assets to local for realistic testing
- Content staging: Push curated assets from local to staging before production release
- Production sites with large media libraries
- User-uploaded content that changes frequently
- Asset-heavy sites where Git LFS isn't suitable
- Teams needing separate workflows for code vs. assets

Features
--------

[](#features)

- **Fast file transfers** using rsync
- **Push files** from local to remote server
- **Pull files** from remote to local environment
- **Selective transfers** with `--only-missing` and `--delete` options
- **Dry run mode** to preview changes without transferring
- **Interactive mode** with guided configuration setup
- **Real-time progress bar** with transfer feedback
- **Comprehensive logging** for detailed operation tracking
- **ASCII art** for enhanced terminal experience
- **Automatic cache clearing** for Stache, Glide, and application cache
- **Built-in security** with input validation and safe command execution
- **Language Support** for all command messages, prompts, and error handling

Important Safety Warning
------------------------

[](#important-safety-warning)

**Rsync is a powerful synchronisation tool that can permanently delete or overwrite files. Please read these warnings carefully:**

🚨 **ALWAYS use `--dry-run` first** to preview changes before executing any command:

```
php please assets:pull --dry-run
php please assets:push --dry-run
```

**The `--delete` option is destructive** and will permanently remove files:

- `assets:pull --delete` removes local files not on the remote server
- `assets:push --delete` removes remote files not in local directories
- **There is no undo** - deleted files are gone forever

**Test in development first** before using on production:

- Verify your paths are correct
- Ensure you have backups of important data
- Double-check remote and local path configurations match

**Common scenarios that cause data loss:**

- Wrong path configuration (syncing to wrong directories)
- Mismatched local/remote path counts
- Using `--delete` without understanding its impact
- Not testing with `--dry-run` first

> 💡 **Best Practice**: Always run commands with `--dry-run` first, review the output carefully, then run without `--dry-run` only when you're certain the changes are correct.

Requirements
------------

[](#requirements)

- Statamic 5
- PHP 8.1+
- rsync installed on your system (GPL-licensed, installed separately)
- SSH access to remote server

Installation
------------

[](#installation)

### Via Composer

[](#via-composer)

1. Install the addon:

```
composer require mikomagni/statamic-asset-sync-pro
```

2. Install rsync on your system (required dependency, GPL-licensed):

    - **macOS**: `brew install rsync`
    - **Ubuntu/Debian**: `sudo apt-get install rsync`
    - **Windows**: Use WSL, Cygwin, or Git Bash
    - **More info**:
3. Clear configuration cache:

```
php please config:clear
```

4. Verify installation:

```
php please help assets:pull
```

Configuration
-------------

[](#configuration)

Add the following variables to your `.env` file:

```
# Server Configuration
RSYNC_SERVER_USER=your_username
RSYNC_SERVER_HOST=your_server_ip
RSYNC_REMOTE_APPLICATION_DIR=/path/to/remote/app

# Asset Paths (comma-separated)
RSYNC_REMOTE_ASSETS_PATHS=public/images,public/assets,public/files
RSYNC_LOCAL_ASSETS_PATHS=public/images,public/assets,public/files

# Transfer Options
RSYNC_MAX_TRANSFER_SIZE=100M
RSYNC_EXCLUDE_FILE_EXTENSIONS=txt,log,tmp

# Display & Logging
RSYNC_DISPLAY_OUTPUT_BUFFER=false
RSYNC_DISPLAY_PROGRESS_HINTS=false
RSYNC_ASSETS_LOG=false
RSYNC_DISPLAY_ASCII_ART=true

# Cache Clearing - Remote (after push)
RSYNC_CLEAR_REMOTE_STACHE=false
RSYNC_CLEAR_REMOTE_GLIDE=false
RSYNC_CLEAR_REMOTE_CACHE=false

# Cache Clearing - Local (after pull)
RSYNC_CLEAR_LOCAL_STACHE=false
RSYNC_CLEAR_LOCAL_GLIDE=false
RSYNC_CLEAR_LOCAL_CACHE=false
```

### Example Configuration

[](#example-configuration)

```
RSYNC_SERVER_USER=forge
RSYNC_SERVER_HOST=123.456.789.0
RSYNC_REMOTE_APPLICATION_DIR=/home/forge/myapp.com
RSYNC_REMOTE_ASSETS_PATHS=public/images,public/assets
RSYNC_LOCAL_ASSETS_PATHS=public/images,public/assets
RSYNC_EXCLUDE_FILE_EXTENSIONS=txt,log
RSYNC_MAX_TRANSFER_SIZE=100M
RSYNC_DISPLAY_ASCII_ART=true
RSYNC_ASSETS_LOG=true
```

Usage
-----

[](#usage)

### Interactive Mode (Recommended for First Setup)

[](#interactive-mode-recommended-for-first-setup)

```
php please assets:pull --interactive
php please assets:push --interactive
```

Interactive mode will guide you through configuration setup and provide options for transfer preferences.

### Pull Assets (Remote → Local)

[](#pull-assets-remote--local)

Download assets from remote server to local environment:

```
# Pull all assets
php please assets:pull

# Pull only missing files
php please assets:pull --only-missing

# Delete local files not on remote (🚨 DESTRUCTIVE - test with --dry-run first!)
php please assets:pull --delete

# Preview changes without transferring
php please assets:pull --dry-run

# Combine options
php please assets:pull --only-missing --dry-run
```

### Push Assets (Local → Remote)

[](#push-assets-local--remote)

Upload assets from local environment to remote server:

```
# Push all assets
php please assets:push

# Push only missing files
php please assets:push --only-missing

# Delete remote files not in local (🚨 DESTRUCTIVE - test with --dry-run first!)
php please assets:push --delete

# Preview changes without transferring
php please assets:push --dry-run

# Combine options
php please assets:push --only-missing --dry-run
```

Command Options
---------------

[](#command-options)

OptionDescription`--interactive`Enable interactive mode with guided prompts`--only-missing`Transfer only missing files`--delete`🚨 **DESTRUCTIVE**: Delete files that don't exist in source`--dry-run`**RECOMMENDED**: Preview changes without actual transfer> 🚨 **CRITICAL WARNING**: The `--delete` option will **permanently remove files** with no recovery possible. **ALWAYS** use `--dry-run` first to preview changes, especially with `--delete`.

Configuration Reference
-----------------------

[](#configuration-reference)

### Server Settings

[](#server-settings)

- `RSYNC_SERVER_USER`: SSH username for remote server
- `RSYNC_SERVER_HOST`: Remote server hostname or IP address
- `RSYNC_REMOTE_APPLICATION_DIR`: Full path to remote application directory

### Asset Paths

[](#asset-paths)

- `RSYNC_REMOTE_ASSETS_PATHS`: Comma-separated remote asset directories (relative to remote application directory)
- `RSYNC_LOCAL_ASSETS_PATHS`: Comma-separated local asset directories (relative to project root, must match remote paths order)

> 💡 **Path Format**: Both `public/images` and `/public/images` work identically - leading slashes are automatically normalised.

### Transfer Options

[](#transfer-options)

- `RSYNC_MAX_TRANSFER_SIZE`: Maximum file size limit (e.g., `100M`, `1G`)
- `RSYNC_EXCLUDE_FILE_EXTENSIONS`: File extensions to exclude from sync
- `RSYNC_FILE_TRANSFER_REGEX`: Custom regex for progress bar tracking

### Display & Logging

[](#display--logging)

- `RSYNC_DISPLAY_OUTPUT_BUFFER`: Show rsync output in real-time (`true`/`false`)
- `RSYNC_DISPLAY_PROGRESS_HINTS`: Show file names and transfer details below progress bar (`true`/`false`)
- `RSYNC_ASSETS_LOG`: Enable detailed logging to `storage/logs` (`true`/`false`)
- `RSYNC_DISPLAY_ASCII_ART`: Show ASCII art during operations (`true`/`false`)

### Cache Management

[](#cache-management)

- `RSYNC_CLEAR_REMOTE_*`: Clear remote caches after push operations
- `RSYNC_CLEAR_LOCAL_*`: Clear local caches after pull operations
- Available cache types: `STACHE`, `GLIDE`, `CACHE`

Logging
-------

[](#logging)

When `RSYNC_ASSETS_LOG=true`, detailed logs are written to `storage/logs/laravel.log` including:

- Operation start/completion
- Individual rsync commands executed
- Real-time transfer output
- File-by-file transfer details
- Error messages and debugging info

Customisation
-------------

[](#customisation)

### Custom ASCII Art

[](#custom-ascii-art)

Create custom ASCII art files:

- `resources/ascii/pull.txt` - Displayed during pull operations
- `resources/ascii/push.txt` - Displayed during push operations

### Language File Customisation

[](#language-file-customisation)

The addon includes comprehensive language support for all command messages, prompts, and error handling. You can customise or translate these messages by publishing and modifying the language file.

**Language File Location:**

```
src/resources/lang/en/commands.php

```

**Key Translation Categories:**

- **Operation Messages**: Success, warning, and completion messages
- **Interactive Prompts**: Configuration setup questions and validation
- **Error Handling**: SSH connection errors, path validation, and rsync failures
- **Progress Feedback**: Transfer status and cache clearing messages

**Example Translations:**

```