Home | Eclipse plugins -> FileSync | About

FileSync manual

Installation / activation

Make sure that "Project->Build Automatically" is enabled. If not, then FileSync will NOT work automatically as expected.

First one must enable "File synchronization" builder once for each project which need to be synchronized. Then one must create file synchronization mapping (through UI or via any text editor). As long as no project mapping exists, FileSync builder will do nothing, even if it is enabled. If FileSync builder was disabled for project, then it will do nothing even if mapping exists.

One can change FileSync mapping on "Project->Properties->File synchronization" properties page or via text editor (the mapping is located at: "%Project%/.settings/de.loskutov.FileSync.prefs"). One can include/exclude any files/folders/patterns to/from synchronization.

Normally if FileSync builder is activated for the project and FileSync mapping exists, then it would automatically add/copy/delete any project file or folder to the mapped external file/folder on any and every resource change in Eclipse project, if auto-build is enabled for project ("Project->Build Automatically"). Please note, that synchronization works is only in one direction - from Eclipse to the rest of the world. This means, changes on "external" files (files, not being a part of any Eclipse project) would *not* be reflected in Eclipse workspace.

If one need to perform manual file synchronization or add FileSync builder to the current project, then right click on any opened project in the Eclipse Navigator view and select "Force File Synchronization". If FileSync builder is not yet enabled for the project, user will be asked to enable FileSync builder, otherwise the mapped files would be synchronized once.

Note: all warnings/errors would be reported to the Eclipse log only. For successful operations no log entries would be generated. You can see Eclipse log with "Window->Show View->Other...->PDE Runtime->Error Log".


Mapping format

FileSync stores/reads project file mapping to/from: "%Project%/.settings/de.loskutov.FileSync.prefs". The changes of this file will be monitored by FileSync, if FileSync is enabled for the curent project. One mapping property should looks like:

%source folder%|%destination folder%|inclPatternList|exclPatternList|%variables file%

and inclPatternList or exclPatternList should be like:


where %path% could be either relative path or a path pattern in the Ant path notation. If either %destination folder%, inclPatternList or exclPatternList or both are not specified, then each missing entry should be replaced with "," character.

%source folder% and %variables file% are always project relative, %destination folder% is absolute (with some exceptions). If the %destination folder% is absolute, it should start with the device name on Windows (like "C:"), or with the slash ("/") for Linux.

If %destination folder% is in workspace, then it could be specified as workspace relative, replacing workspace location path with ':' char.

One could also use path variables for %destination folder% or first part of it. This path variables are listed under "Window ->Preferences ->General ->Workspace->Linked resources-> Defined path variables". Usage is restricted to the first path segment only, see Javadoc for IPathVariableManager.resolvePath() on Eclipse site.

At the end of mapping one could specify project relative path to variables file (this is optional). This variables file meaning is completely different to path variables usage described before - it could be used to substitute variables in the files during the synchronization. These variables could be specified only through Java .properties file format, %KEY%=%VALUE%, and used only in Ant property format - "Hallo ${KEY}" would be replaced to "Hallo VALUE". The variables files are monitored by plugin, so that changes in this files would lead to start of full synchronisation of the project. One could *enable* variables substitution by specifying a concrete file for particular mapping. Until nothing is specified, *no* variables substitution will be performed.


Mapping examples

Here is an example of two FileSync mappings:


One %source folder% could be mapped to different (*must* be distinct!) destination folders:


Here is another example for two destination folders, one is inside the workspace:


The "serverProject" in example above is the folder (project) inside the current user workspace.

Here is another example for two destination folders, one is defined with path variable "SERVER_PATH":


The "SERVER_PATH" in example above is the folder "E\:/deploy".


Misc. settings

Here are settings with possible values:

useCurrentDateForDestinationFiles=true|false (default is false)
cleanOnCleanBuild=true|false (default is false)
defaultDestination=%full absolute folder path% (default is not specified)
defaultVariables=%project relative file path% (default is not specified)

useCurrentDateForDestinationFiles - if true, then current date for destination files will be used instead of the source file date (default is false).

cleanOnCleanBuild - if true, then destination folders which contains more then only source files would be deleted on clean build (default is false).

defaultDestination - if non - empty, then it could be used as a default destination folder for mappings without to specify it in each mapping. The file path for this property should be always absolute (with one exception). If %defaultDestination% is in workspace, then it could be also specified as workspace relative, replacing workspace location path with ':' char. If the %defaultDestination% is absolute, it should start with the device name on Windows (like "C:"), or with the slash ("/") for Linux.

defaultVariables - if non empty, then it could be used as a "first" default variables substitution file for all mappings which have enabled variables substitution. Then the variables substitution files from such mappings will be used "on top" of this defaults file (if the specified file is not the default one, then the variables from *both* files would be used, and the variables from last file will override default one). The file path for this property should be always relative to the project. This setting allows to share some default variables across multiple mappings but use some different variables values in each mapping.


Risks & restrictions

The file synchronization could work only in one direction - from Eclipse project to the external location. Of course you can do the "dirty trick" and create a project with linked folders, which could be mapped to files of another one (or the same) project. But I cannot guarantee that such configuration will work and do not lead to the data loss.

(e.g. Project -> external folder -> linked folder -> Project)

Synchronization between files on different file systems (like FAT/NTFS) and with cyclical mappings may lead to unexpected results and to endless loops, because file size/timestamp format on different file systems could vary even for "identical" files. If you have cyclical mappings, be sure that the source and destination folders are on the same partition type and with the same allocation unit (block/cluster) size!

For example, the cyclical mapping between FAT and NTFS partition could lead to endless loop (even if block size is the same), because of different timestamp format.


Please send comments or suggestions to loskutov

Last changed at: 24.05.09 18:33