Sync-It for Mutagen

SyncIt is a helper (phar archive) to make it easier to work with sessions when running mutagen.

SyncIt runs from a config file typically located in your project root named: .mutagen_sync_it.yaml. This file should be committed to your version control.

Inside the config file you can define any number of sync tasks. Each task should be a unique combination of a source (the alpha) and a target (beta).

SyncIt requires Mutagen >=0.10.0.

There is support for labels including project prefixes.

SyncIt has only been tested on macOS Mojave.

Features

• simple yaml configuration
• common options and ignore rules that are shared by tasks
• all mutagen create flags are supported
• labels
• multiple tasks per project file
• custom file location via a MUTAGEN_SYNC_IT_CONFIG env param
• phar archive
• support for .env files (including overrides)
• docker container resolution from a specified name
• groups to start/stop multiple tasks at the same time

Setup

Grab the phar archive and copy it to /usr/local/bin or add it to your path. Symlink the phar to syncit or a.n.other name.

Or install via brew:

brew install somnambulist-tech/somnambulist/syncit

In your project root e.g. ~/Projects/my-web-project run: syncit init to create a default, commented config file named .mutagen_sync_it.yaml. Tweak the settings.

Caution: before using mutagen ensure you have read and understood the docs. This is provided as-is without warranty of any kind. Use at your own risk!

Caution: mis-configuring a mutagen session can cause serious data-loss!

Removing SyncIt

Remove any symlinks you have and delete the phar file. No other files are created except for any config yaml files. If you installed using brew, then brew remove syncit. Again: use the following script at your own risk!

unlink /usr/local/bin/syncit && rm -v /usr/local/bin/mutagen-sync-it.phar

Protecting Yourself From File Overwrites

By way of some safe-guards you can configure a global mutagen config by adding a .mutagen.yml file to your home folder cd ~. This file defines global defaults that will be applied to all sessions (see mutagen.io for more details):

sync:
    defaults:
        mode: one-way-replica
        ignore:
            vcs: true
            paths:
                # System files
                - ".DS_Store"
                - "._*"
                  
                # Vim files
                - "*~"
                - "*.sw[a-p]"

                # Common folders and files
                - ".idea"
        symlink:
            mode: ignore
        permissions:
            defaultFileMode: 0644
            defaultDirectoryMode: 0755

The above ensures that all syncs are created using one-way-replica. This ensures that no changes are written back to the source but the target will be overwritten.

Note: that this will happily override your local in the source is set as a remote and the target is a local folder. Be very careful!

.env Files

SyncIt will read a .env file if it finds one in the project root. This is processed using Symfony DotEnv and will support .env.local and other overrides.

Building the phar archive

To build the phar archive, first checkout / clone the sync-it project, run composer install and ensure that phar.readonly is set to 0 in your php.ini.

You can then run: bin/compile which will create a mutagen-sync-it.phar file in the project root. The compile will output the SHA384 hash together with the file location / name.