Documentation Download GitHub

Configuring Unisync

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.

A Minimal Config File

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 =

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.

A Full Config File

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 =

# 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

Syntax Details

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:

  • Whitespace around the key and value are ignored, so port=22 is equivalent to port = 22
  • Lines starting with # or ; are treated as comments
  • Certain settings (like ignore) can be used more than once to accumulate settings. For others (like port), using it more than once overrides the previous value.
  • For bool settings (such as 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.

Settings: local, remote

Set the local and remote folders to be synced.

local = /Users/nick/projects/myproject
remote = /home/nick/deploy/myproject

Settings: user, host

Set the SSH user and host for the connection to remote. The user setting has no effect when using method=directtls.

user = nick
host =

Setting: method

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.

Setting: port

Set the SSH (or direct connect) port. Defaults to 22 for method=ssh or method=internalssh, and has no default for method=directtls.

Setting: prefer

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.

Setting: ssh_path

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.

Setting: ssh_opts

The options to run SSH with. Defaults to -e none -o BatchMode=yes -o StrictHostKeyChecking=no. Only relevant if method=ssh.

Setting: timeout

Network timeout (in seconds) while connected. Defaults to 300.

Setting: connect_timeout

Network timeout (in seconds) while connecting. Defaults to 30.

Setting: log

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 =

Setting: symlinks

If set to false, symlinks will be skipped over when syncing. Defaults to false on Windows and true everywhere else.

Setting: tls_key

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.

Setting: debug

If set to true, will output lots of network data about what's goingon. Defaults to false.

Setting: ssh_keys

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.

Setting: ignore

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.

Settings: tmpdir_local, tmpdir_remote

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.

Settings: watch_local, watch_remote, poll_freq

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.

Setting: remote_unisync_path

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).

Settings: chmod_local, chmod_local_dir, chmod_remote, chmod_remote_dir, chmod_mask, chmod_mask_dir

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.