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
Here is a minimal config file-- let's call it
# this is my project.conf unisync config! local = /Users/nick/mydir remote = /home/nick/mydir user = nick host = 22.214.171.124
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 = 126.96.36.199 # 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=22is equivalent to
port = 22
ignore) 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:
on. The following values are false:
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
user = nick host = 188.8.131.52
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=internalssh, and has no default for
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
The options to run SSH with. Defaults to
-e none -o BatchMode=yes -o StrictHostKeyChecking=no. Only relevant if
Network timeout (in seconds) while connected. Defaults to
Network timeout (in seconds) while connecting. Defaults to
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:
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
If set to
true, will output lots of network data about what's goingon. Defaults to
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
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.
watch_remote settings can be either
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_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.
watch_remote are set to
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.
chmod_remote specify the default mode that files will be given when they are created or updated. They default to
Then we have
chmod_remote_dir, which do the same for directories. They default to
Finally, we have
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.
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.