# Options

General
The following options are available in the General pane.

- Rsync Executable

  Under the hood DropSync uses a tool called rsync to perform the actual syncing. Two different versions of rsync are provided, one based on the 3.10.x branch and another based on rsync 2.6.9 that has some OSX specific features enabled. For most situations the default (3.10.x) rsync is best.

- Notifications

  DropSync displays notifications using Notification Centre. The general options pane provides control over when DropSync issues notifications.

- Deletions

  Turn deletions on and off for syncs in specific directions. More detail about how deletions work is available here.

- Allowed Sync Directions

  Syncs are normally allowed for both left and right directions. Use this section if you need to enforce syncing in one direction only.

- Performance - Only scan changed directories

  Use this option if you are performing a one-way sync and want super-fast performance. Instead of scanning through files to find changes DropSync will keep track of changed files as they change, and only include those in the sync. Beware that DropSync cannot monitor changes on the right for ssh folder pairs so in that case changes that occur on the right will be missed.

Copying
The following options are available in the Copying pane.

- File Attributes

  When DropSync updates or copies files it can also set attributes of various types. Support for syncing these attributes varies depending on the nature of the source and destination file systems, and the OS privileges required to set them. DropSync will issue a warning during a sync if it is unable to successfully update a chosen attribute.

  Extended Attributes

  Syncing extended attributes differs substantially depending on the version of rsync chosen in the general options pane. In most cases the default is best, however in rare circumstances (e.g., when extended attribute data is very large, or when syncing to a filesystem that does not support extended attributes) you should choose the 2.6.9 version of rsync. Extended attributes synced using rsync 2.6.9 are stored alongside the original file in a hidden companion file whereas extended attributes synced using rsync 3.10.x are attached to the file using the filesystem's native extended attribute mechanism.

- Symbolic Links

  Symbolic links are a special type of file that simply points to another file or directory. DropSync lets you choose whether to copy these as they are (treat links as links) or to transform them into the file or directory that they point to (transform links into referent file or dir). Because symbolic links can refer to any file path they might sometimes point outside the syncing root, you can choose not to copy links of this type.

- File Matching

  When DropSync performs an update it tries to avoid copying anything that already exists at the destination. This section provides various options for changing the circumstances under which files will be skipped. The default method of matching files is a combination of modification time and size, which is both accurate and fast. On some filesystems, or when communicating with some servers via ssh the modification time matching might be inaccurate (due to different granularity of timestamps or differing clocks). In such cases a fast but rather loose option would be to choose "size only", or a slow but very accurate option would be to compare checksums. Beware that comparing checksums is very slow.

  Dealing with FAT32

  For compatibility with Windows, many USB drives are formatted as FAT32. This is an old filesystem that does not support fine grained timestamps. In order to preserve the ability to skip files based on size and modification time it is necessary to change the accuracy with which times are compared. Entering a value of 1 into the compare mod-times with reduced accuracy box should deal with the issue.

- Performance

  DropSync default settings will usually give excellent performance when syncing. Options available here can be used to tweak performance for special cases. On extremely fast networks, and for local file transfers it can be beneficial to select the Transfer whole files not deltas option. At the opposite extreme, for syncs over a slow network connection it can be beneficial to compress data during the transfer. It is also possible to control which files are transferred based purely on their size.

Filters
DropSync's underlying syncing engine rsync has a powerful filter system to customise which files are included in a sync. The Filter pane allows you too add these rules and provides some conveniences for common patterns. The full pattern rule syntax is described on the rsync man page, but it can be quite daunting to read. Common tasks are easy though as these examples demonstrate:

##### Add an Exclude filter for Photoshop files (.psd)

1. Open the Configure window
2. Select the Filters tab
3. Click the + button to create a new blank filter
4. Enter *.psd into the filter's Pattern field. This rule means "match anything ending with .psd"
5. The filter should now exclude all files with the .psd extension

##### Include only .jpg files

1. Open the Configure window
2. Select the Filters tab
3. Click the + button to create a new blank filter
4. Enter *.jpg into the filter's Pattern field
5. Turn on the Sync only includes option for the direction where the rule should apply

Filter Rule Scoping

Relative filter rules written like this `*.jpg` apply anywhere within a folder hierarchy (selected folders only). Absolute rules start with a `/` and apply matches based on the root folder. For example `/*.jpg` would only match jpg files in the root folder, or `/subdir/*.jpg` would only match jpg files within subdir.

Filter Rule Order

When using several filter rules together it is important to keep in mind that their order matters. Rules are examined in order (top first) and the first match encountered is used.

Scheduled and Automated Syncs
DropSync can run syncs automatically on a schedule, or in response to changes in a source directory.

##### Run syncs on a timer

1. Open the Configure window
2. Select the Schedule tab
3. Check the Sync every check box
4. Choose the timing units (e.g., minutes)
5. Enter the number of (seconds, minutes, hours) between syncs
6. Choose the direction for the automatic sync

Timer drift

Syncing on a timer should only be used if you don't care about syncs running at a precise time. Timers don't sync themselves to a calendar clock so a timer set to go off every 24 hours will gradually shift to a different time of day. At present the only way to schedule syncs at a precise time is to use Applescript and the OSX Calendar.

Syncs don't run when your Mac is asleep

##### Sync automatically when files change

1. Open the Configure window
2. Select the Schedule tab
3. Check the Whenever a change occurs check box

SSH Login
The SSH Login tab is available for Folder Pairs setup to connect via SSH.

##### Setup an SSH connection

1. Open the Configure window
2. Select the SSH Login tab
3. Enter connection details. The screenshot below shows an example of a simple setup for a site that uses password based authentication. Key based authentication is also supported.

4. If using a password you should typically select Add password to keychain to avoid typing the password every time. This stores your password securely using the OSX Keychain application.
5. The Path setting allows specifying the root path of the sync on the server. Clicking the button to the right of this setting will attempt to connect to the server and launch a filesystem browser that will allow you to choose a folder.
6. In most cases the SFTP Chroot setting should be left blank. This is needed for servers where sftp connections only see files relative to a root path. One common class of servers with this issue are Synology NAS systems. Please contact support if you are having difficulty with this setting.

##### Configuring a Private Key

DropSync optionally supports key based authentication via the Private Key setting. Clicking the choose button opens a file picker to allow you to specify the location of your key. Make sure you select the Private key (eg `id_rsa` or `id_dsa` or `key.pem`) rather than the public key. DropSync will never transmit your private key itself but needs to be able to read the private key in order to authenticate the connection.
Rescue
When DropSync performs a sync it will overwrite destination files that have changes at the source, and (depending on the deletion setting) it can delete destination files that are missing at the source. To help prevent accidental data loss, these files can be sent to a special Rescue folder. Rescue is off by default because it can easily fill your hard drive if used when syncing large folders. For Folder Pairs that connect via Finder DropSync manages the location of rescue items itself, but for Folder Pairs that connect via SSH a rescue folder on the remote server can also be used.

##### Turn on rescue for a Finder Folder Pair

1. Open the Configure window
2. Select the Rescue tab
3. Ensure that both left and right facing arrow buttons are selected

##### Turn on rescue for an SSH Folder Pair

1. Open the Configure window
2. Select the Rescue tab
3. Turn on rescue when syncing from right to left by selecting the left facing arrow. This will place rescue items in a folder managed internally by DropSync
4. Turn on rescue when syncing from left to right by selecting the right facing arrow. If you stop at this step and don't complete step 4 rescue files will still be made on the server, but they will not go into a special folder. Instead rescue files will be kept alongside existing files by appending `~` to the name.
5. Check the choose button to open an sftp browser where a rescue folder can be selected. It's best to create an empty folder exclusively for this purpose on the server.

Consider the Size of Rescue data

Keeping rescue data around can consume alot of disk space if you make frequent changes. If this is the case its probably best to turn off rescue, or perform regular cleaning. To clean out the rescue folder simply open it in finder and drag items to the trash.

Security concerns with SSH Folder Pairs

Keeping a rescue folder for an SSH Folder Pair can be really useful, but if your SSH server is a production web server it is important to ensure that this folder does not introduce any security issues. The rescue folder should be given the same security considerations as the rest of your system.

Advanced
The Advanced tab allows users who know rsync and its many options to directly modify the options used when DropSync runs. Separate panes are provided for each syncing direction, and items can be added by typing them directly as text.

- Enter items as you would on the command-line

  Start typing an item (for example to add the Append option start typing `--a`) and a list will appear with options that valid options corresponding to what was typed.

- Drag and drop to reorder items
- Core Options

  DropSync uses these core options. Consider how custom options might function when combined with these.

  `"--dry-run",--itemize-changes","--recursive","--verbose","--progress","--stats"`