README

Laravel Sync

A git-like artisan command to easily sync files and folders between environments via rsync.

Requirements

rsync on both your local machine and the remote host
A working ssh setup between your local machine and the remote host (agent or ~/.ssh/config)

Installation

You can install the package via Composer:

composer require marcorieser/laravel-sync

Publish the config file:

php artisan vendor:publish --tag="laravel-sync-config"

This publishes config/sync.php:

return [

    'remotes' => [

        // 'production' => [
        //     'user' => 'forge',
        //     'host' => '104.26.3.113',
        //     'port' => 22,
        //     'root' => '/home/forge/example.com',
        //     'read_only' => env('SYNC_PRODUCTION_READ_ONLY', true),
        // ],

    ],

    'recipes' => [

        // 'assets' => ['storage/app/assets/', 'storage/app/img/'],

    ],

    'options' => [
        '--archive',
    ],

];

Remotes

Each remote needs a root path. Add user and host to sync with an actual server over ssh; omit both to treat the remote as a plain local path (handy for syncing between two projects on the same machine, no ssh involved).

Key	Description
`user`	The username to log in to the host. Omit together with `host` for a local remote.
`host`	The IP address or hostname of the server. Omit together with `user` for a local remote.
`port`	The SSH port to use. Defaults to `22`.
`root`	The absolute path to the project's root folder.
`read_only`	When `true`, blocks `push` to this remote. Defaults to `false`.

Recipes

Recipes name a set of paths, relative to your project's root, that belong together:

'recipes' => [
    'assets' => ['storage/app/assets/', 'storage/app/img/'],
    'env' => ['.env'],
],

Options

The default rsync options, used whenever --option isn't passed on the command line:

'options' => [
    '--archive',
],

Backup Directory

Relative to your project's root. When --backup is passed on a real pull, the local files of the selected recipes are copied here, into a timestamped folder, before the pull runs:

'backup_dir' => '.sync-backups',

Each backed-up pull adds another timestamped folder; nothing prunes old ones automatically. Add backup_dir to your .gitignore and run php artisan sync:backups-clean to clean it out periodically.

Usage

php artisan sync {push|pull} {remote} {recipe...} [options]

Command	Description
`sync`	Run the sync.
`sync:list`	Preview the origin, target, options, and port in a table, without syncing.
`sync:commands`	Print the `rsync` commands that would be run, without syncing.
`sync:backups-clean`	Delete backup folders created by a backed-up pull.

Option	Description
`-O`, `--option=*`	Override the default rsync options. Repeatable.
`-D`, `--dry`	Perform a dry run, with real-time output. On `sync:backups-clean`, preview which backups would be deleted.
`-A`, `--all`	Sync every configured recipe. On `sync:backups-clean`, delete every backup.
`-B`, `--backup`	Back up local files to `backup_dir` before a real pull.
`-F`, `--force`	`sync:backups-clean` only. Skip the confirmation prompt.
`-v`	Show real-time output while syncing (progress, stats, ...).

Any argument you omit is prompted for interactively (operation, remote, recipes, and rsync options), unless you pass --no-interaction, in which case a missing required value fails fast with a clear error instead of prompting — and any real (non-dry) sync runs immediately without a confirmation prompt.

Use --dry for a dry run, not --option=--dry-run — only --dry skips the confirmation prompt, forces real-time output, and reports it as a dry run instead of a completed sync.

--backup only applies to a real (non-dry) pull — a pull is the only operation that overwrites your local files, so a push (or a dry run) ignores it. Before the pull runs, the local files of the selected recipes are copied into a timestamped folder under backup_dir (e.g. .sync-backups/2026-07-24_134530/), using a fixed --archive --relative copy independent of your chosen rsync options. If you don't pass --backup and you're pulling interactively, you're asked whether to back up before you're asked which rsync options to use.

Cleaning Up Backups

sync:backups-clean deletes timestamped folders under backup_dir, leaving backup_dir itself (and anything in it that isn't a timestamped backup folder) untouched. Run it without options to pick backups from an interactive list (with size and age), or pass --all to select every one. Add --dry to preview what would be deleted without deleting anything, and --force to skip the confirmation prompt.

Running it with --no-interaction and without --all fails fast with a friendly error instead of deleting anything — there's no picker to fall back to, and deleting every backup by default would be surprising. The confirmation prompt only appears when running interactively, so --no-interaction --all (e.g. in a cron job) deletes immediately without needing --force.

Examples

# Pull the "assets" recipe from "staging"
php artisan sync pull staging assets

# Push "assets" to "production" with custom rsync options
php artisan sync push production assets --option=-avh --option=--delete

# Preview a pull as a dry run, with real-time output
php artisan sync pull staging assets --dry

# Back up local "assets" files before pulling
php artisan sync pull staging assets --backup

# Sync every recipe
php artisan sync push production --all

# Preview what would run, without syncing
php artisan sync:list pull staging assets
php artisan sync:commands pull staging assets

# Fully interactive
php artisan sync

# Pick which backups to delete from an interactive list
php artisan sync:backups-clean

# Delete every backup without a confirmation prompt
php artisan sync:backups-clean --all --force

# Preview which backups --all would delete
php artisan sync:backups-clean --all --dry

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Thank you for considering contributing to Laravel Sync! Please review our contributing guide to get started.

marcorieser / laravel-sync

Maintainers

Package info

Fund package maintenance!

Statistics

Security