Unisync
Documentation
Download
GitHub
For each remote point you want to sync with, you will create a config file on the local side. You will put it in the ~/.unisync directory. There are no config files on the remote side.
The UNISYNC_DIR environment variable can be set to a directory path, and unisync will look for config files there instead of ~/.unisync.
Here is a minimal config file-- let's call it ~/.unisync/project.conf.
# this is my project.conf unisync config!
local = /Users/nick/mydir
remote = /home/nick/mydir
user = nick
host = 123.123.123.123
It specifies which directories will be synced, and the user and host that will be used to connect to the remote side through SSH.
Once you've saved this config file, you can run it on the local side with unisync project. It will connect to the remote side and start the syncing.
Now let's extend our project.conf file to use every config option that's available.
# start with our basic settings
local = /Users/nick/mydir
remote = /home/nick/mydir
user = nick
host = 123.123.123.123
# now add every other setting
method = ssh
port = 22
prefer = newest
ssh_path = ssh
ssh_opts = -e none -o BatchMode=yes -o StrictHostKeyChecking=no
timeout = 300
connect_timeout = 30
log = ~/mylog.log
symlinks = true
tls_key = secure.key
debug = false
ssh_keys = ~/.ssh/key1
ssh_keys = ~/.ssh/key2
ignore = /.git
ignore = /tmp
tmpdir_local = /tmp
tmpdir_remote = /tmp
watch_local = true
watch_remote = poll
poll_freq = 0.5
remote_unisync_path = /usr/local/bin/unisync
chmod_local = 0644
chmod_local_dir = 0755
chmod_remote = 0644
chmod_remote_dir = 0755
chmod_mask = 0100
chmod_mask_dir = 0000
The config file format is designed to emulate the classic Windows ini format and be easy to read and write. But if you want some pedantic details, here they are:
port=22 is equivalent to port = 22ignore) can be used more than once to accumulate settings. For others (like port), using it more than once overrides the previous value.symlinks), the following values (case insensitive) are true: 1, t, true, yes, on. The following values are false: 0, f, false, no, off. Everything else will produce an error.Set the local and remote folders to be synced.
local = /Users/nick/projects/myproject
remote = /home/nick/deploy/myproject
Set the SSH user and host for the connection to remote. The user setting has no effect when using method=directtls.
user = nick
host = 123.123.123.123
How to connect to the remote side. Options are:
ssh -- Use the system's SSH client. (default everywhere but Windows)internalssh -- Use unisync's built-in SSH client, helpful if SSH isn't installed locally (default on Windows)directtls -- Use encrypted direct connection, helpful if SSH isn't installed remotely. See Unisync Without SSH for more.Set the SSH (or direct connect) port. Defaults to 22 for method=ssh or method=internalssh, and has no default for method=directtls.
When the local and remote versions of a file are different, unisync will generally consider its internal cache to figure out which is the "right" version of the file. See the How Unisync Works page for more details on this. When the cache is not available (usually on the first sync), the prefer setting tells it which version wins. Options are:
newest -- Whichever one is newer by last-modified time. (default)oldest -- Whichever one is older by last-modified time.local -- Local version always wins.remote -- Remote verion always wins.Again, this setting has no effect when unisync has its cache available to figure out whether the local or remote version of the file is "actually" newer.
The path to look for the SSH binary locally. Defaults to ssh, which means we just look for it in the system PATH. Only relevant if method=ssh.
The options to run SSH with. Defaults to -e none -o BatchMode=yes -o StrictHostKeyChecking=no. Only relevant if method=ssh.
Network timeout (in seconds) while connected. Defaults to 300.
Network timeout (in seconds) while connecting. Defaults to 30.
While running, unisync outputs basic log data to the screen (if attached) and this log file. Defaults to ~/.unisync/[name].log. If you set it to empty string like this, logging will be disabled:
log =
If set to false, symlinks will be skipped over when syncing. Defaults to false on Windows and true everywhere else.
Only has an effect if method=directtls is used. Lets you specify the file containing the TLS key that you copied over from the server. If the path is not absolute, it is assumed to be in the ~/.unisync/ directory. Defaults to secure.key.
If set to true, will output lots of network data about what's goingon. Defaults to false.
Set the SSH keys that will be used to connect. Ignored in method=directtls mode. If omitted, method=ssh mode will cause SSH to do what it does normally, and method=internalssh will check the following locations in the ~/.ssh/ folder: id_rsa, id_dsa, id_ecdsa, id_ed25519, identity.
Can be used more than once if you have multiple keys that you want it to try.
Files or folders matching this will not be synced. Uses the gitignore format. You can use this setting more than once to ignore multiple things, like this:
ignore = /.git
ignore = /tmp
In this example, the .git and tmp folders (or files) at the root of the sync path will be skipped.
When receiving a file, unisync will create a tempfile, write to it, and then move it into place when it's ready. This protects from damaged files if your connection drops halfway through a file transfer. By default, the tempfile will be created in the same directory that the received file will go into. These settings let you choose a different directory on either the local or remote side.
The temp directory you choose must be in the same volume as the directory you're syncing, or it will break.
The watch_local and watch_remote settings can be either on (default), poll, or off.
When you run unisync, it will do a sync and then watch for changes on both the local and remote sides. How it does this is different depending on the operating system -- each one has a different internal API for watching a directory for changes, and those APIs vary in quality. For example, FreeBSD relies on an older system called kqueue which can break with larger folders. Also, some Linux distros come with kernel settings misconfigured in a way that caps the number of files it will watch at the same time. If the directory you're syncing has many thousands of files, this may cause it to break.
If the filesystem watching isn't working right for you, or is causing unisync to crash, watch_local or watch_remote can be set to poll -- this will cause it to watch for changes by repeatedly listing the contents of the sync folder. The only downside to polling is that it may cause higher battery usage on laptops.
If either watch_local or watch_remote are set to poll, then poll_freq controls how often (in seconds) it will check the folder for changes. The default is 0.25, meaning it checks 4 times per second.
Tell unisync where to look for the remote unisync binary. Has no effect if method=directtls. You can use this setting more than once to set multiple locations where it will look for the remote unisync. If omitted, it will check these locations: unisync (in system PATH), ./unisync (in homedir), ~/.unisync/unisync (where our install guides tell you to put it).
These settings control the file and directory mode for files that are transferred. They have no effect on Windows.
First, chmod_local and chmod_remote specify the default mode that files will be given when they are created or updated. They default to 0644.
Then we have chmod_local_dir and chmod_remote_dir, which do the same for directories. They default to 0755.
Finally, we have chmod_mask and chmod_mask_dir, which let you set which bits from the source file mode will override the default. By default, chmod_mask is 0100, which means only the user-executable bit of any files will be synced over-- if you run chmod u+x filename to a watched file on the local side, it will get CHMODed on the remote side and vice-versa. Other mode changes will be ignored, though, and the default mode will control.
By default, chmod_mask_dir is 0, which means the file mode of directories is always ignored, and unisync will create directories with the default mode.
If you set chmod_mask to 0777, for example, then all file mode changes will be synchronized between local and remote.