Folder Comparison and Synchronization

Usage:

  1. Choose left and right directories.

  2. Compare them.

  3. Select synchronization settings.

  4. Press Synchronize to begin synchronization.

Main Dialog Overview

  1. Start comparison

  2. Change comparison settings

  3. Change synchronization settings

  4. Start synchronization

  5. Tree overview panel

  6. Add additional folder pairs

  7. Select left and right folders

  8. Synchronization preview

  9. Save/load configuration

  10. Include/exclude specific files

  11. Select categories to show on grid

  12. Synchronization statistics


Command line

FreeFileSync enables 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:

FreeFileSync -h

1. Run a FreeFileSync batch job

In order to start synchronization in batch mode, supply the path of a *.ffs_batch configuration as the first argument for FreeFileSync.exe:

FreeFileSync "D:\Backup Projects.ffs_batch"

After synchronization one of the following status codes is returned:

Return Codes
0 - Synchronization completed successfully
1 - Synchronization completed with warnings
2 - Synchronization completed with errors
3 - Synchronization was aborted

You can evaluate these codes from a script (e.g. a *.cmd or *.bat file on Windows) and check if synchronization completed successfully:

"C:\Program Files\FreeFileSync\FreeFileSync.exe" "D:\Backup Projects.ffs_batch"
if errorlevel 1 (
  ::if return code is 1 or greater, something went wrong, add special treatment here
  echo Errors occurred during synchronization...
  pause
)

Instead of displaying "An error occurred!" you can also send an email notification (using a third party tool).

Attention
Make sure your script is not blocked by a popup dialog. Consider the following options when setting up a FreeFileSync batch job:

  • Disable checkbox Show progress dialog or have On completion automatically close the results dialog after synchronization.

  • Set error handling to Exit instantly or Ignore errors.

    2. Start a FreeFileSync GUI configuration

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

    FreeFileSync "D:\Manual Backup.ffs_gui"

    3. Customize an existing configuration

    You can replace the directories of a given *.ffs_gui or *.ffs_batch configuration by using the -leftdir and -rightdir parameters:

    FreeFileSync "D:\Manual Backup.ffs_gui" -leftdir C:\NewSource -rightdir D:\NewTarget

    4. Merge multiple configurations

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

    FreeFileSync "D:\Manual Backup.ffs_gui" "D:\Backup Projects.ffs_batch"


Comparison settings

I. Compare by "File time and size"

This variant considers two files with the same name as equal when both modification time and file size match. 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)

II. Compare by "File content"

Two files with the same name are marked as equal if and only if they have the same content. This option is more useful for consistency checks rather than backup operations since it is naturally slower. The file modification time is not taken into account at all.

  1. file exists on one side only

      • left only

      • right only

  2. file exists on both sides

      • equal

      • different content

Symbolic link handling

FreeFileSync offers three options to configure handling of symbolic links (also called symlinks or soft links):

  1. Exclude: Skip symbolic links while scanning directories.

  2. Direct: Evaluate the symbolic link object directly. Symbolic links will be shown as a separate entity on grid. Links pointing to directories are not traversed and the link object is copied directly during synchronization.

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

Note

  • Under Windows the symbolic link options apply to symbolic links, volume mount points and NTFS junction points.

  • Copying symbolic links requires FreeFileSync to be started with administrator rights.


Daylight saving time (Windows)

A common problem synchronization software has to deal with are +-1 hour file time shifts after a Daylight Saving Time (DST) switch has occurred. This can be observed for example when a FAT-formatted volume is compared against an NTFS volume as frequently happens with USB memory sticks. Files that previously appeared to be in sync are now shown with a one hour modification time offset, although they have not been modified by the user or by other means.

The reason for this strange behavior lies in the way NTFS and FAT drives store file times: NTFS stores time in UTC format, while FAT uses local time.

When times stored in these two different formats are compared, one format has to be converted into the other first. In both cases Windows uses the current DST status as well as current time zone information for its calculations. Consequently the result of this comparison is dependent from current system settings and in particular file times that used to be the same can show up as different after a DST switch.

For a detailed discussion about this issue refer to: http://www.codeproject.com/KB/datetime/dstbugs.aspx

Solution:

Luckily FreeFileSync users need not to worry about this issue. Each file on a FAT volume automatically gets additional meta data encoded in its creation date that enables a correct file time calculation. This not only solves all DST issues but also time shifts that occur due to travel between different time zones.

Note

  • In order for FreeFileSync to start handling DST and timezone differences, an initial full synchronization is required. Subsequent syncs will never show a time difference again.

  • If a FAT volume is scanned the first time by FreeFileSync this will take longer than usual since additional meta data is written for each file.


Exclude items

Files and directories are only considered for synchronization if they pass the filter. They have to match at least one entry in the include list and none of the entries in the exclude list:

  • Each list item must be a file or directory path relative to synchronization base directories.

  • Multiple items must be separated by ; or a new line.

  • Wild cards * and ? may be used: * means zero or more characters while ? represents exactly one character.

    Example: Exclude items for mirror-sync from C:\Source to D:\Target

    Description

    Exclude

    Single file C:\Source\file.txt

    \file.txt

    Single folder C:\Source\subfolder

    \subfolder\

    All files (and folders) named thumbs.db

    *\thumbs.db

    All *.tmp files located in subfolder only

    \subfolder\*.tmp

    Files and folders containing temp somewhere in their path

    *temp*

    Multiple entries separated by semicolon

    *.tmp; *.doc; *.bak

    Exclude all files and folders located in subdirectories of base directories

    \*\*

    Exclude only *.txt files located in subdirectories of base directories

    \*\*.txt

    Note

  • For simple exclusions just right-click and exclude one item or a list of items directly on main grid via context menu.

  • A filter phrase is compared against both file and directory paths. If you want to consider directories only, you can give a hint by appending a path separator (\).


Expert settings

FreeFileSync has a number of special purpose settings that can only be accessed directly via the global configuration file "GlobalSettings.xml". To locate this file enter "%appdata%\FreeFileSync" in the Windows Explorer address bar or go to the FreeFileSync installation folder if you are using the portable installation.

<?xml version="1.0" encoding="UTF-8"?>
<FreeFileSync XmlType="GLOBAL">
    <Shared>
        <FileTimeTolerance Seconds="2"/>
        <RunWithBackgroundPriority Enabled="false"/>
        <LockDirectoriesDuringSync Enabled="true"/>
        <VerifyCopiedFiles Enabled="false"/>
        <LastSyncsLogSizeMax Bytes="100000"/>

FileTimeTolerance:
By default file modification times are allowed to have a 2 second difference while still being considered equal. This is required by FAT/FAT32 file systems which store file times with a 2 second precision only.
This setting can also be used to simulate a "compare by file size", ignoring last modification times: If tolerance is set to some high value, e.g. 2000000000, then changed files will be detected as a conflict (same date, different file size) and the synchronization direction for conflicts can be set accordingly.

RunWithBackgroundPriority:
While synchronization is running, other applications which are accessing the same data locations may experience a noticeable slowdown. Enable this setting to lower FreeFileSync's resource consumption at the cost of a significantly slower synchronization speed.

LockDirectoriesDuringSync:
In order to avoid race conditions of multiple FreeFileSync instances writing to the same folder at the same time, accesses are serialized by lock files ("sync.ffs_lock"). This allows to operate FreeFileSync with an arbitrary number of users in a network out of the box.

VerifyCopiedFiles:
If active, FreeFileSync will binary-compare source and target files after copying and report verification errors. Note that this may double file copy times and is no guarantee that data has not already been corrupted prior to copying and corruption is not hidden by deceptively reading valid data from various buffers in the application and hardware stack.
Does the CopyFile function verify that the data reached its final destination successfully?

LastSyncsLogSizeMax:
The progress logs of the most recent synchronizations (for both GUI and batch jobs) are collected automatically in the file "LastSyncs.log". The maximum size of this log file can be set here.


External applications

By default FreeFileSync opens the operating system's file browser on each mouse double-click by invoking "explorer /select, "%item_path%"" on Windows and "xdg-open "%item_folder%"" on Linux.

However you may integrate other external applications into FreeFileSync: navigate to Menu → Advanced → Global settings: External Applications and add or replace a command. The first entry is executed when double-clicking a row or pressing ENTER on main grid while all other entries can only be accessed via the context menu shown after a right-click. The following internal macros are available:

%item_path%     - full file or folder name
%item_folder%   - folder part only
%item2_path%    - Counterpart of %item_path% on the opposite grid
%item2_folder%  - Counterpart of %item_folder% on the opposite grid

Examples:

  • Start visual difference tool:
    "C:\Program Files\WinMerge\WinMergeU.exe" "%item_path%" "%item2_path%"

  • Show file in Windows Explorer:
    explorer /select, "%item_path%"

  • Open file in associated application:
    cmd /c start "" "%item_path%" or simply "%item_path%"

  • Open console dialog:
    cmd /k cd /D "%item_folder%"

Note
Don't forget to use quotation marks if file names contain spaces!


Macros

All directory names may contain macros that are expanded during synchronization. Begin and end of each macro is marked by a % character. Besides special macros handling time and date, the operating system's environment variables can also be used.

Internal macros:

%date%       e. g. 2012-12-22        format [YYYY-MM-DD]
%time%       e. g. 123044            format [hhmmss]
%timestamp%  e. g. 2012-12-22 123044 format [YYYY-MM-DD hhmmss]

%year%       e. g. 2012
%month%      e. g. 12
%day%        e. g. 22

%hour%       e. g. 12
%min%        e. g. 30
%sec%        e. g. 44

%weekday%    e. g. Monday day of the week
%week%       e. g. 28     calendar week

Environment variables: (Windows)

%AllUsersProfile%   e. g. C:\ProgramData
%AppData%           e. g. C:\Users\<username>\AppData\Roaming
%ComputerName%      e. g. Zenju-PC
%LocalAppData%      e. g. C:\Users\<username>\AppData\Local
%ProgramData%       e. g. C:\ProgramData
%ProgramFiles%      e. g. C:\Program Files
%ProgramFiles(x86)% e. g. C:\Program Files (x86)
%Public%            e. g. C:\Users\Public
%Temp%              e. g. C:\Windows\Temp
%UserName%          e. g. Zenju
%UserProfile%       e. g. C:\Users\<username>
%WinDir%            e. g. C:\Windows

Special folder locations (Windows)

%csidl_Desktop%     e. g. C:\Users\<username>\Desktop
%csidl_Downloads%   e. g. C:\Users\<username>\Downloads
%csidl_Favorites%   e. g. C:\Users\<username>\Favorites
%csidl_MyDocuments% e. g. C:\Users\<username>\Documents
%csidl_MyMusic%     e. g. C:\Users\<username>\Music
%csidl_MyPictures%  e. g. C:\Users\<username>\Pictures
%csidl_MyVideos%    e. g. C:\Users\<username>\Videos
%csidl_Nethood%     e. g. C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Network Shortcuts
%csidl_Programs%    e. g. C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs
%csidl_Quicklaunch% e. g. C:\Users\<username>\AppData\Roaming\Microsoft\Internet Explorer\Quick Launch
%csidl_Resources%   e. g. C:\Windows\Resources
%csidl_StartMenu%   e. g. C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Start Menu
%csidl_Startup%     e. g. C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\StartUp
%csidl_Templates%   e. g. C:\Users\<username>\AppData\Roaming\Microsoft\Windows\Templates

Note: Most macros listed here also have a variant for public folders. E.g. csidl_MyMusic → csidl_PublicMusic

Hint:

You can add a great amount of flexibility to batch synchronization (*.ffs_batch) by creating new temporary environment variables in a *.bat/*.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:

set MyVar=C:\Target
"C:\Program files\FreeFileSync\FreeFileSync.exe" C:\SyncJob.ffs_batch
::%MyVar% is resolved as C:\Target during synchronization

Note
Temporary environment variables created with the "set" command are only valid if the batch job is started by calling the executable directly! Using "start /wait" or relying on Shell Execute creates a new program context without these temporal variables.


Schedule a batch job

  1. Create a new batch job via FreeFileSync's main dialog: Menu → Program → Save as batch job...

  2. If the batch job shall run without user interaction or as part of an unattended batch script, make sure that no popup dialog stops the progress:
    Disable checkbox Show progress dialog to avoid blocking while showing the result after synchronization. Alternatively you can select the "On completion" action Close progress dialog located in synchronization settings.
    Note: Even if the progress dialog is not shown at the beginning, a user can make it visible during synchronization by double-clicking the FreeFileSync systray icon.

  3. In order to prevent error or warning popup messages from stopping progress, set Error handling to either Ignore or Exit.

  4. Setup your operating system's scheduler

    1. Windows 7 Task Scheduler:

      • Go to Start and run taskschd.msc.

      • Create a new basic task and follow the wizard.

      • Make Program/script point to the location of FreeFileSync.exe and insert the *.ffs_batch file into Add arguments.

      • Use quotation marks to protect spaces in path names, e.g.: "D:\Backup Projects.ffs_batch"

    Note
    Beginning with Windows Vista the "Program/script" always needs point to an executable file like "FreeFileSync.exe" even if ffs_batch file associations have been set!     If a ffs_batch file were entered instead the task would return with error code 0xC1, "%1 is not a valid Win32 application".

    2. Windows XP Scheduled Tasks:

      • Go to Start → Control Panel → Scheduled Tasks and select Add Scheduled Task.

      • Follow the wizard and select FreeFileSync.exe as program to run.

      • Fill input field Run: as: <FreeFileSync installation folder>\FreeFileSync.exe <job name>.ffs_batch

    3. Ubuntu Linux Gnome-schedule:

      • Install Gnome-schedule, if necessary: sudo apt-get install gnome-schedule

      • Go to System → Preferences → Scheduled tasks

      • Enter the command as: <FreeFileSync installation folder>/FreeFileSync <job name>.ffs_batch


Synchronize with FTP/WebDAV (Windows)

FreeFileSync does not support accessing FTP volumes directly. But this functionality can be integrated by mapping the FTP web space to a drive letter:

Example: Use the free utility NetDrive (http://www.netdrive.net)

  • Add a New Site and specify site name, site URL, drive letter, account and password.

  • Use the newly created drive as if it were a normal hard disk.

Note
Most FTP drives set a file's time stamp to the current time when synchronizing ignoring the source file's time and date. As a workaround you can do a Compare by File Size.

Synchronize with SFTP (Linux)

An SFTP share can be easily mapped onto a local folder for use with FreeFileSync:

  • Install:
    sudo apt-get install sshfs

  • Mount SFTP share:
    sshfs ssh-account@ssh-server:<path> mountpoint

  • Unmount:
    fusermount -u mountpoint


Variable drive letters

USB memory sticks or external hard disks often get different drive letters assigned when plugged into distinct computers. FreeFileSync offers two solutions to handle this problem:

Option 1: Specify a folder path by using the volume name:

Use "[ZENJU-USB]\folder" instead of "G:\folder" where "ZENJU-USB" is the volume name of the USB stick which is currently mounted in drive G:\.

Note
It is not required to look up and enter the volume name manually. Just select the corresponding entry in the drop down menu.

Option 2: Use a relative directory name:

  • Use "\folder" instead of "G:\folder"

  • Save and copy synchronization settings to the USB stick: "G:\Backup.ffs_gui"

  • Start FreeFileSync by double-clicking on "G:\Backup.ffs_gui"
    → The working directory is automatically set to "    G:\" by the operating system so that the relative path "\folder" will be resolved as "G:\folder" during synchronization.


File versioning

When you need to preserve files that have been deleted or overwritten it's often sufficient to select Recycle Bin in synchronization settings. However this is only available on local drives and offers little control on how to store and how long to keep the files. FreeFileSync therefore has an additional option, Versioning.

1. Keep all versions of old files

In synchronization settings set deletion handling to Versioning and naming convention to Time stamp. FreeFileSync will move deleted files into the provided folder and add a time stamp to each file name. The structure of the synchronized folders is preserved so that old versions of a file can be conveniently accessed via a file browser.

Example: A file "Folder\File.txt" was updated three times and old versions were moved to folder "C:\Revisions"

C:\Revisions\Folder\File.txt 2012-12-12 111111.txt
C:\Revisions\Folder\File.txt 2012-12-12 122222.txt
C:\Revisions\Folder\File.txt 2012-12-12 133333.txt

2. Save only most recent version

Set deletion handling to Versioning and naming convention to Replace. Deleted files will be moved to the specified folder without any decoration and will replace already existing older versions.

3. Save versions at certain intervals

With naming convention Replace it's possible to refine the granularity of versions to keep by adding macros to the versioning folder path. For example you can save deleted files on a per sync session basis by adding the %timestamp% macro:

Example: Using the dynamically generated folder name "C:\Revisions\%timestamp%"

C:\Revisions\2012-12-12 111111\Folder\File.txt
C:\Revisions\2012-12-12 122222\Folder\File.txt
C:\Revisions\2012-12-12 133333\Folder\File.txt

This allows for a simple manual undo by moving the deleted files from the last synchronization session back to their original folders. Other macros like %date% or %weekday% can be used to reduce the granularity to days and weeks.


Volume Shadow Copy Service (Windows only)

FreeFileSync supports copying locked or shared files by creating a Volume Shadow Copy of the source drive. This feature can be configured via Menu → Advanced → Global settings: Copy locked files.

Note

  • The volume snapshot created by the Volume Shadow Copy Service is used when copying locked files only.

  • Accessing the Volume Shadow Copy Service requires FreeFileSync to be started with administrator rights.

    Troubleshooting

    If you experience problems using the Volume Shadow Copy Service a renewal of registration might help. Create and execute a *.cmd batch file with the follow content or enter directly via command line:

    cd /d %windir%\system32
    Net stop vss
    Net stop swprv
    regsvr32 ole32.dll
    regsvr32 oleaut32.dll
    regsvr32 vss_ps.dll
    Vssvc /register
    regsvr32 /i swprv.dll
    regsvr32 /i eventcls.dll
    regsvr32 es.dll
    regsvr32 stdprov.dll
    regsvr32 vssui.dll
    regsvr32 msxml.dll
    regsvr32 msxml3.dll
    regsvr32 msxml4.dll

    Reference: http://support.microsoft.com/kb/940032


Automated Synchronization

RealtimeSync is a small tool which executes a command line each time it detects changes in one of the monitored directories or a directory becomes available (e. g. insert of a USB-stick). Usually this command line will simply trigger a FreeFileSync batch job.

Example: Real time synchronization - in combination with FreeFileSync

Start RealtimeSync.exe located in FreeFileSync's installation directory. Then specify all folders that shall be monitored. Instead of doing this manually you can import a *.ffs_batch file via Menu → Program → Open. This not only extracts all directories relevant for synchronization but also sets up the command line to execute the *.ffs_batch file each time changes are detected. Now press Start to begin monitoring.

Note

  • The command should not block progress. Make sure the FreeFileSync batch job does not show any popup dialogs. See notes in Batch Scripting.

  • The settings dialog can be skipped by passing a RealtimeSync configuration file (*.ffs_real) or a FreeFileSync batch file (*.ffs_batch) as first command line argument to RealtimeSync.exe. This can be integrated into the operating system's auto start facility:
    "C:\Program Files\FreeFileSync\RealtimeSync.exe" "D:\Backup Projects.ffs_real"
     "C:\Program Files\FreeFileSync\RealtimeSync.exe" "D:\Backup Projects.ffs_batch"

  • Using RealtimeSync is not restricted to starting FreeFileSync. It can also be used in other scenarios, like sending an email whenever a certain directory is modified.

    Example: Automatic synchronization when USB stick is inserted

    Save a ffs_batch configuration into the USB stick's root directory and have it called when the stick is mounted. Then configure RealtimeSync as shown in the following:

    Whenever directory "H:\Data" becomes available, the command line executes and starts the batch job on the stick. Additionally it also starts the batch job each time files are modified in "H:\Data".

    Note
    The full path of the last changed file and the action that triggered the change notification (create, update or delete) are written to the environment variables %change_path% and %change_action%.

    Example: Show names of changed files or directories. (Windows)

    Show which file or directory has triggered a change. Enter command line:
        cmd /c echo %change_action% "%change_path%" & pause

    Write a list of all changes to a logfile:
        cmd /c echo %change_action% "%change_path%" >> c:\log.txt

    Note
    During execution of a Windows Batch file (*.bat/*.cmd) a black console window is shown. You can hide it using the Visual Basic script "HideConsole.vbs" located in FreeFileSync's installation directory:

    wscript "C:\Program files\FreeFileSync\HideConsole.vbs" C:\MyBatchFile.cmd

    Limitations:

    • If multiple changes happen at the same time, only the name of the first file is written to variable "changed_file".

    • While RealtimeSync is executing the command line, monitoring is inactive and changes occurring during this time are lost.


Run as service (Windows)

RealtimeSync is designed as a background process which does not need further attention once it is running. Depending on your requirements there are a number of ways to start it together with the operating system. Generally the goal is to execute a command line like the following: <installation folder>\RealtimeSync.exe <path to *.ffs_real or *.ffs_batch file>

Example:

    "C:\Program Files\FreeFileSync\RealtimeSync.exe" "D:\Backup Projects.ffs_real"

  1. RealtimeSync should be monitoring only while a specific user is logged in: Create a new shortcut, enter the command line from above as target and place it into the user's autostart folder.

  2. RealtimeSync should be monitoring while Windows is online irrespective of currently logged in users: Create a new task in your operating systems's task scheduler and have it execute the command line above when the system starts. See Schedule a Batch Job for an example how to add a new task. Then change the user to run the task to SYSTEM - a special user account always running in the background.


FreeFileSync Links

Homepage:
 http://freefilesync.sourceforge.net

Project on SourceForge: feedback, suggestions and bug-reports
 http://sourceforge.net/projects/freefilesync

If you like FreeFileSync: consider supporting the project by a donation
 Donate via PayPal


Batch scripting

FreeFileSync can be called from command line and supports integration into batch scripts. This section gives some general hints and examples for Windows *.cmd and *.bat scripts.

When FreeFileSync is started in batch mode (a *.ffs_batch file is passed as argument) it returns one of the following status codes:

Return Codes
0 - Synchronization completed successfully
1 - Synchronization completed with warnings
2 - Synchronization completed with errors
3 - Synchronization was aborted

Now you can check if synchronization was successful from a script:

"C:\Program Files\FreeFileSync\FreeFileSync.exe" "H:\some folder\SyncJob.ffs_batch"
if errorlevel 1 (
  ::if return code is 1 or greater, something went wrong, add special treatment here
  echo Errors occurred during synchronization...
  pause
)

Instead of displaying "An error occurred!" you can also send an email notification (using a third party tool).

Attention
Make sure your script is not blocked by a popup dialog. Consider the following options when setting up a FreeFileSync batch job:

  • Disable checkbox Show progress dialog or have On completion automatically close the results dialog after synchronization.

  • Set error handling to Exit instantly or Ignore errors.