FreeFileSync Open Source File Synchronization

#Quick Start

Basic Usage:

1. Select left and right folders.
   
2. Compare them.
   
3. Choose synchronization settings.
   
4. Click Synchronize to start the synchronization process.
   

Main Dialog Overview

Command Line Usage

FreeFileSync supports additional synchronization scenarios via a command line interface. To get a syntax overview, open the console, go to the directory where FreeFileSync is installed and type:

1. Run a FreeFileSync batch job

To start a synchronization in batch mode, supply the path of a .ffs_batch configuration file as the first argument after the FreeFileSync executable:
After synchronization, detailed results are written to standard output in JSON format. You can parse this output with a script to add further customizations.

To check if synchronization was successful, evaluate the process exit code:
Windows: A batch script (.cmd/.bat) that evaluates this code may look like this:

2. Start a FreeFileSync GUI configuration

If you pass a .ffs_gui configuration file, FreeFileSync starts in GUI mode and immediately begins comparison (but only if all directories exist):

3. Customize an existing configuration

You can replace the directories of a .ffs_gui or .ffs_batch configuration file by using the -DirPair parameter:

4. Merge multiple configurations

When more than one configuration file is provided, FreeFileSync merges everything into a single configuration with multiple folder pairs and start in GUI mode:

5. Use a different GlobalSettings.xml file

By default, FreeFileSync uses a single GlobalSettings.xml file containing options that apply to all synchronization tasks; for examples, see Expert Settings. If you want FreeFileSync to use a different settings file instead, just add the file path via command line:

Comparison Settings

Comparison Variants

FreeFileSync compares two folders by analyzing the relative paths of the files they contain, i.e. the paths relative to the base folder pair. If the relative path matches, FreeFileSync decides how the file pair is categorized by considering the selected comparison variant:

1. Compare by File Time and Size
This variant considers two files equal when both modification time and file size match. It should be selected when synchronizing files with a backup location. Whenever a file is changed, its file modification time is automatically updated. Therefore, a comparison by file time and size will detect all files that should be synchronized. The following categories are distinguished:

1. file exists on one side only
   • left only
   • right only
2. file exists on both sides
   1. different date
      • left newer
      • right newer
   2. same date
      • equal
      • conflict (same date, different size)

2. Compare by File Content
Two files are marked as equal if they have identical content. This variant should be selected when doing consistency checks to see if the files on both sides are bit-wise identical. This is the slowest of all comparison variants, so its usefulness for synchronization is limited. If used for synchronization, it can serve as a fallback when modification times are not reliable. For example certain mobile phones and legacy FTP servers do not preserve modification times, so when file sizes match, the only reliable way to detect differences is to compare the actual content.

1. file exists on one side only
   • left only
   • right only
2. file exists on both sides
   • equal
   • different content

3. Compare by File size
Two files are considered equal if they have the same file size. Since it's possible for files that have the same size to have different content, this variant should only be used when file modification times are not available or reliable, e.g. in certain MTP and FTP synchronization scenarios, and where a comparison by content would be too slow.

1. file exists on one side only
   • left only
   • right only
2. file exists on both sides
   • equal
   • different size

Symbolic Link Handling

FreeFileSync lets you include symbolic links (also called symlinks or soft links) when scanning directories instead of skipping them. When included, you can select between two ways to handle them:

1. Follow: Treat symbolic links like the object they are pointing to. Links pointing to directories are traversed like ordinary directories, and the target of each link is copied during synchronization.
2. As link: Include the symbolic link object directly. Symbolic links will be shown as separate entities. Links pointing to directories are not traversed and the link object itself is copied during synchronization.

Daylight Saving Time (Windows)

Synchronization software often encounters ±1-hour shifts in file times after a Daylight Saving Time (DST) change. This typically happens when comparing a FAT32 or exFAT volume (referred to as "FAT") with an NTFS volume, such as when synchronizing a USB stick with a local disk. Files that were previously in sync are now shown as offset by one hour, even though they have not been modified.

This occurs because NTFS stores file times in UTC format, while FAT stores them in local time.

When comparing times from these two formats, one must be converted to the other. Windows uses the current DST status and time zone for these calculations. As a result, the comparison is affected by current system settings, causing file times that were once the same to appear different after a DST change or time zone switch.

For more details on handling DST shifts in file times, see: Beating the Daylight Saving Time Bug

Solutions:

1. In FreeFileSync's comparison settings, you can enter one or more time shifts to ignore during comparison: To handle daylight saving time differences, enter a single one-hour shift. If the differences are caused by changing the time zone, enter one or more time shifts as needed.
   
   
   
   Note
   File times must be equal or differ by exactly the specified time shift to be considered the same. Therefore, the time shift setting should not be confused with a time interval or tolerance.
   
   
2. Alternatively, avoid the problem by only synchronizing FAT to FAT or NTFS to NTFS file systems. For example, since most local disks are NTFS and USB sticks are FAT, this issue can be solved by formatting the USB stick with NTFS as well.

Exclude Files and Folders with Filter

Files and folders are considered for synchronization only if they pass all filter rules: They must match at least one entry in the include list and none in the exclude list as shown in the filter configuration dialog.
 

Example: Filtering Items in a Folder Pair

The following filter phrases assume a folder pair C:\Source <—> D:\Target, and they can be used for both the include and exclude filters.
 

Example: Complex filter rules with exceptions

Complex filter requirements can often be solved by using two folder pairs with the same source and target paths but different local filters. The first folder pair handles the default case. The second folder pair the exception.
Exclude a subfolder except for *.txt files by using two folder pairs:

Example: Exclude empty folders

Set *: as the include filter to match all files, but not folders. During synchronization some excluded folders will still be created if needed, but only if they contain at least one non-excluded item, that is, when they are not empty.

Expert Settings

FreeFileSync includes several special settings that can only be accessed by manually opening the global configuration file GlobalSettings.xml. Note that this file is read once when FreeFileSync starts and saved again on exit. Therefore, you should only apply manual changes when FreeFileSync is not running. For the portable FreeFileSync variant, the file is located in the installation folder. For local installations, go to:

Windows:	%AppData%\FreeFileSync
Linux:	~/.config/FreeFileSync
macOS:	~/Library/Application Support/FreeFileSync

FileTimeTolerance:
By default, file modification times are allowed a 2-second difference and still considered equal. This is required by FAT/FAT32 file systems which store file times only with a 2-second precision.

RunWithBackgroundPriority:
When synchronization is running, other applications accessing the same data locations may experience noticeable slowdowns. Enable this setting to lower FreeFileSync's file access priority at the cost of a slower synchronization speed.

LockDirectoriesDuringSync:
To prevent multiple synchronization tasks from reading and writing the same files, FreeFileSync instances are serialized with lock files (sync.ffs_lock). The lock files are recognized only by FreeFileSync, ensuring that at most one synchronization runs for a folder at a time, while other instances are queued. This ensures that only consistent sets of files are subject to synchronization. The primary use case are network synchronization scenarios where multiple users run FreeFileSync concurrently against a shared network folder.

VerifyCopiedFiles:
When active, FreeFileSync will binary compare source and target files after copying and report verification errors. Note that this may double file copy times and does not guarantee that data was not already corrupted before copying. Also, corruption may be hidden by reading valid data from various buffers in the application or hardware stack:
Does the CopyFile function verify that the data reached its final destination successfully?

External Applications

By default, when you double-click a row in the main dialog, FreeFileSync opens the operating system's file browser:

Windows:	explorer.exe /select, %local_path% & exit 0
macOS:	open -R %local_path%
Linux:	xdg-open "$(dirname %local_path%)"

To customize this behavior or integrate other external applications into FreeFileSync, go to Menu → Tools → Options → Customize context menu and add or replace a command.

You can quickly access all entries by pressing the corresponding numeric keys 0–9 or through the context menu (right-click). The first entry can also be executed by double-clicking on an item.

In addition to regular macros, the following special macros are available:

Examples:

• Launch a file content comparison tool: Windows: WinMerge
  
  "C:\Program Files (x86)\WinMerge\WinMergeU.exe" %local_path% %local_path2%
  
  macOS: opendiff (requires Xcode)
  
  opendiff %local_path% %local_path2%
  
  Ubuntu: kompare (sudo apt install kompare)
  
  kompare %local_path% %local_path2%
  
  
• Show file in Windows Explorer:
  
  explorer.exe /select, %local_path% & exit 0
  Note
  Explorer.exe doesn't set an exit code, but FreeFileSync will show an error message if it doesn't find exit code = 0 ("Success"). To mitigate, append (&) command exit 0 to set the exit code explicitly.
  
  
• Open command prompt for the selected item:
  
  start cmd.exe /k cd /D %parent_path%
  Note
  Since FreeFileSync doesn't automatically show a console window, start is used to open one. cmd.exe /k runs the following command without immediately exiting the console. cd navigates to the directory, even if it's on a different volume (/D).
  
  
• Copy the item path to the clipboard (alternative to using CTRL + C)
  
  echo %item_path%| clip
  
  
• Write the list of selected file paths to a text file:
  
  echo %item_path% >> %csidl_Desktop%\file_list.txt
  
  
• Preview files using Quick Look on macOS:
  
  qlmanage -p %local_path%
  
  
• Pass a list of selected files to a script as command line arguments:
  
  C:\my-script.cmd %local_paths%

Macros

All directory paths may contain macros, which are expanded during synchronization. The beginnings and ends of each macro are marked by a % character. In addition to special macros handling time and date, the operating system's environment variables may also be used.

Internal Macros

Environment Variables (Windows)

Special Folder Locations (Windows)

Hint: You can add flexibility to an .ffs_batch configuration file by creating new temporary environment variables in a bat or cmd file that are evaluated by FreeFileSync at runtime:

Example:

The FreeFileSync batch file C:\SyncJob.ffs_batch contains macro %MyVar% instead of an absolute target folder and is invoked by a cmd file:

Performance Improvements

FreeFileSync can perform multiple file accesses simultaneously. This speeds up synchronization times dramatically in cases where single I/O operations have significant latency (e.g. long response times on a slow network connection) or they cannot use the full bandwidth available (e.g. an FTP server enforcing a speed limit for each connection).

You can configure the number of parallel file operations per device in the Comparison Settings dialog. It is evaluated for all folder pairs of a configuration as follows:

• During comparison FreeFileSync groups all folders by their root devices.
  For example, consider a configuration with two folder pairs and parallel file operations set up:

  C:\Source	↔	D:\Target
  C:\Source2	↔	E:\Target

  Device root	Parallel operations
  C:\	1
  D:\	2
  E:\	3

  FreeFileSync will put the folders C:\Source and C:\Source2 into the same group for device root C:\ and allow only 1 file operation at a time. Folder D:\Target will be traversed using 2 operations, and E:\Target using 3 operations at a time. Overall, FreeFileSync will scan all four folders using 6 parallel operations.
  
  
• When synchronizing a folder pair, FreeFileSync will use the maximum of the number of parallel operations supported by the two folders.
  
  In the previous example the folder pair C:\Source ↔ D:\Target will be synchronized using 2 parallel operations, and C:\Source2 ↔ E:\target will be using 3.

RealTimeSync

RealTimeSync executes a command line every time it detects changes in a monitored directory, or when a directory becomes available (e. g. insert of a USB-stick). Usually this command line will trigger a FreeFileSync batch job.

RealTimeSync receives change notifications directly from the operating system, eliminating the need for continuous polling for changes. Each time a file or folder is created/updated/deleted in the monitored directories or their sub directories, RealTimeSync waits until a user-configurable idle time has passed with no further detected changes, then runs the command line. This makes sure the monitored folders are not in heavy use when starting a synchronization.

Example: Real time synchronization using FreeFileSync

Start RealTimeSync.exe from FreeFileSync's installation directory and select the folders to monitor. Instead of doing this manually you can import an .ffs_batch file via Menu → File → Open or simply via drag and drop. RealTimeSync will extract relevant directories for synchronization and set up the command line to execute the .ffs_batch file when changes are detected. Now press Start to begin monitoring.

Example: Automatic synchronization when a USB stick is inserted

Save an .ffs_batch configuration in the USB stick's root directory, (e.g., H:\) and let FreeFileSync run it when the stick is mounted. But, instead of hard coding the USB drive letter H:\ (which may change occasionally), refer to the USB stick via its volume label instead.

Configure RealTimeSync as follows:

Whenever directory H:\Data becomes available, RealTimeSync executes the command line which starts the batch job located on the stick. RealTimeSync will also trigger each time files are modified in H:\Data.

Example: Log names of changed files and directories

Log all changes to a file: (Windows)

Log all changes to a file: (Linux/macOS)

Limitations:

• If multiple changes occur simultaneously, only the first file's path is written to %change_path%.
  
  
• While RealTimeSync is executing the command line, monitoring for changed files is temporarily inactive.
  
  
• RealTimeSync relies on receiving change notifications from the operating system. In some cases it just doesn't receive any, e.g. a network path with badly-written/incomplete driver implementation. These buggy drivers often do not fail with an error code, but just do nothing.

The command line usually starts a synchronization task using FreeFileSync, which generates additional file change notifications. Therefore, the RealTimeSync change detection has to be deactivated to not go into an endless loop. On the other hand, it is not likely that changes (other than those from FreeFileSync) happen in first place since RealTimeSync runs the command line only after the user-specified idle time has passed. In any case, files changed during the execution of FreeFileSync will be synchronized the next time FreeFileSync runs.

RealTimeSync: Run as Service (Windows)

RealTimeSync runs as a background process, requiring no further interaction. There are several ways to start it automatically, depending on your needs. Generally, the goal is to execute a command line of the form: e.g.:

Example: Run RealTimeSync on Windows login

Create a shortcut with the command line above as target, then place it in the Windows autostart folder. (Type shell:startup in the Windows Explorer address bar to find the folder quickly.)

Example: Start RealTimeSync as a Service

To keep RealTimeSync running irrespective of currently logged-in users: Create a task in Windows task scheduler to run the command line above when the system starts. See Schedule Batch Jobs for an example of how to add a task. Then set the task to run under the SYSTEM account, which is always running in the background.

Schedule Batch Jobs

1. Create a batch job in FreeFileSync by selecting: Menu → File → Save as a batch job...
   
   
   
2. By default, FreeFileSync displays a progress dialog during synchronization and will wait while the summary dialog is shown. If the progress dialog is not needed, enable the Run minimized checkbox and also set Auto-Close if you want to skip the summary dialog at the end.
   
   Note
   You can make the progress dialog visible at any time during synchronization by double-clicking the FreeFileSync icon in the notification area, if it's initially hidden.
   
   
3. To prevent error or warning messages from delaying synchronization when no user is present, either enable Ignore errors or set Cancel to halt at the first error.
    
4. You can start the FreeFileSync batch job by double-clicking the .ffs_batch file or by scheduling it using your operating system's scheduler:
   • Windows: Task Scheduler
   • macOS: Automator and Calendar
   • Linux/macOS: Cron Job

---

Windows: Task Scheduler

5. Open the Task Scheduler either via the start menu, or enter taskschd.msc in the run dialog (keyboard shortcut: Windows + R).
6. Create a new basic task and follow the wizard steps.
7. Make Program/script point to the location of FreeFileSync.exe and insert the .ffs_batch file into Add arguments.
8. Put quotation marks around paths with spaces to prevent misinterpretation as multiple non-existent paths. e.g. like "D:\Backup Projects.ffs_batch"
   

---

macOS: Automator and Calendar

5. Open Launchpad and launch Automator.
   
    
6. Create a new Calendar Alarm.
   
    
7. Drag and drop the .ffs_batch file on the workflow panel.
   
    
8. Double-click Actions / Files & Folders / Open Finder Items to add it to the workflow.
   
    
9. Go to File → Save... and save the Automator job.
   
    
10. The Calendar app will open automatically with the Automator job scheduled for today. You can now select a different time for synchronization or make it a recurring task.
    

---

Linux/macOS: Cron Job

Cron runs arbitrary commands at specified intervals.

To schedule a FreeFileSync batch job, construct a command line for cron consisting of the path to the FreeFileSync executable followed by the path to the FreeFileSync batch job, e.g.
macOS: The executable is located inside the application package, e.g. for an all-users installation:
Open cron's table of scheduled jobs for editing:
 
Each crontab line begins with conditions for recurring execution of the command line that follows. Cron's basic concept is to run a command every minute unless constraints are applied:

To run every hour, set the minute to a fixed value:
To run once every day, set both minute and hour; e.g. run daily at 17:00:
Multiple items are separated by ",", ranges specified using "-", and interval steps by "/".
To run once after each system startup, use alternative syntax "@reboot":

Scripting

When FreeFileSync is run via the command line, the synchronization result is written to standard output in JSON format. This output can be evaluated by scripts to customize functionality.

Windows: To view FreeFileSync's standard output, the pipe (|) operator is required because the operating system classifies FreeFileSync as a GUI application rather than a console application: The command prints JSON data such as:

Parsing sync result via PowerShell

Windows batch scripts (.cmd/.bat) cannot parse JSON, so PowerShell can be used instead:

Example: Delete unnecessary log files

Parsing sync result via Python

On Linux, the same task can be implemented using Python:

Synchronization Settings

Synchronization Variants

Three basic variants are available:

• If both left and right folders contain files you're working on, and you want changes (creates, updates, and deletes) to flow in both directions, then select Two way.
  Database files ("sync.ffs_db") will be created after the first sync and be used to compare the current file system state against the last synchronization in order to determine the sync directions.
  
  
• If one folder contains your work files and the other is for backup, then select the Mirror variant.
  The left folder is the source and the right folder is the target. The synchronization will create and delete files on the target as needed until it is an exact copy of the source.
  
  
• If you only want to add files to your backup, but never delete, then select the Update variant.
  Files deleted on the source side will not be deleted on the backup drive (e.g. after you've made room for new photos on a digital camera). On the other hand, files deleted on the backup drive will not be copied again (e.g. after you have removed photos you don't want to keep).

In order to handle special synchronization scenarios, you can also set up Custom rules. These can either be based on the categories determined after folder comparison (left/right only, left/right newer), or on detected changes (create, update, delete) if you select Use database file to detect changes.

Detect Moved Files

FreeFileSync is able to detect moved files and apply the same move efficiently on the target side during synchronization instead of a slow copy and delete. To make this work, Use database file to detect changes must be checked and the file system must support file IDs.

SFTP and FTP Setup

FreeFileSync supports synchronization with SFTP and FTP when you enter your login information in the cloud folder selection dialog:

Configure SFTP for Best Performance

By default, FreeFileSync creates one connection to the server with a single SFTP channel, meaning only one SFTP command can be sent or received at a time. Since most of this time is spent waiting due to the high latency of the remote connection, you can speed up reading large folder hierarchies by increasing both the connection and channel count.

The folder reading time is reduced by a factor of N x M when using N connections, each with M channels.

Example: Using 10 connections with 2 channels each can make folder reading up to 20 times faster.

• Creating additional connections and channels takes time. If you're scanning a small remote folder, setting up too many connections and channels might slow down the process. Creating extra connections is slower than creating extra channels.
   
• SFTP servers have internal limits on the number of allowed connections and channels. Generally, servers expect one connection per user, so this number should be kept rather low. If too many connections and channels are used, the server may decide to stop responding.
   
• Unlike connections, additional SFTP channels are only used during folder reading (comparison), not during synchronization.
   
• Enable compression to improve performance if the connection to the SFTP server is slow and the data is mostly uncompressed (e.g. transferring text files over a slow internet connection). However, if the connection is very fast (e.g. a local network) or the data is already compressed (e.g. zip files), the CPU overhead of the zlib compression algorithm might slow transfer speeds. In such cases the option is better left unchecked.

Tips and Tricks

Change settings with a single mouse click: Press and hold the right mouse button until the context menu is shown, then release while over the selection:
Select multiple configurations at a time: Select multiple items with the mouse, and refine the selection by holding the CTRL key while clicking.
Start comparison directly by double-clicking on a configuration: Run a partial synchronization only for the currently selected files: Synchronize multiple folder pairs at a time with different configurations: Start synchronization directly without clicking on compare first: Move a window by clicking on an empty area and holding the mouse button: Open a batch configuration for edit via the Windows Explorer context menu: Drag and drop two folders at a time from Windows Explorer to fill a folder pair in one go: Copy files selected on the main dialog to an alternate folder and thous saving a "diff": Use a volume label instead of a drive letter: Show thumbnail icons via the column header context menu: Save the current view filter selection as default: Remove local settings from individual folder pairs: Remove obsolete paths from the folder drop-down by using mouse hover and Delete key: Select a time span for files to include via the date column context menu: Double-click on comparison and synchronization variants to confirm the dialog: Select multiple files and rename all of them simultaneously (via context menu or F2 key):

Variable Drive Letters

USB memory sticks or external hard disks often get assigned different drive letters than the last time they were plugged into the computer. FreeFileSync offers the following solutions:

Option 1: Specify a path by using a unique volume label instead of a drive letter: instead of E:\folder when the USB stick in drive E: is named "Backup-Disk".
You can change a volume label by right-clicking on the drive letter in Windows Explorer and selecting Rename.

Option 2: Refer to a disk volume by its unique GUID: A volume GUID uniquely identifies a particular drive partition, and will not change over time. To get an overview of all volume GUIDs for mounted drives on the system you can run the mountvol command-line tool.

File Versioning

When you need to preserve files that have been deleted or overwritten, selecting Recycle bin in synchronization settings is often sufficient. However, this is only available for local drives and offers limited control over how files are stored and how long they are kept. FreeFileSync therefore has an additional option, Versioning.

1. Keep only the most recent versions

In synchronization settings, set deletion handling to Versioning and naming convention to Replace. Deleted files are moved to the specified folder without any added decoration, replacing older versions that exist.

2. Keep multiple versions of old files

1. Set deletion handling to Versioning and naming convention to Time stamp [File]. FreeFileSync moves deleted files into the specified folder and appends a time stamp to each file name. The folder structure is preserved, making it easy to access older versions via a file browser. Example: Last versions of the file Folder\File.txt inside folder D:\Revisions
   D:\Revisions\Folder\File.txt 2020-12-11 111111.txt
   D:\Revisions\Folder\File.txt 2020-12-12 122222.txt
   D:\Revisions\Folder\File.txt 2020-12-13 133333.txt
   
   
2. With naming convention Time stamp [Folder] files are moved into a time-stamped subfolder within the versioning folder, while their original names are preserved. This allows you to manually undo a synchronization by moving files from the versioning folder back to their original locations. Example: Last versions of the file Folder\File.txt inside folder D:\Revisions
   D:\Revisions\2020-12-11 111111\Folder\File.txt
   D:\Revisions\2020-12-12 122222\Folder\File.txt
   D:\Revisions\2020-12-13 133333\Folder\File.txt

3. Save versions at certain intervals

Using the Replace naming convention, you can control version granularity by adding Macros to the versioning folder path. For example, to save deleted files daily, add the %date% macro:

Example: Last versions of the file Folder\File.txt inside folder D:\Revisions\%date%

Volume Shadow Copy (Windows only)

FreeFileSync supports copying locked or in-use files by creating a Volume Shadow Copy of the source drive. You can configure this feature via Menu → Tools → Options: Copy locked files.