Synchronizer Help

Name:	Synchronizer
Version:	3.0
Last update:	2019-02-18 17:51:20

This package allows to keep two local hierarchies of files and folders in sync.
It inserts a new submenu named Synchronizer in the Tools menu. The commands are explained below.

Synchronization

The Synchronize command displays a dialog where one can specify the source and the target directories, along with various options. The target tree is the hierarchy you want to update and the source tree is the hierarchy which has possibly more recent versions of some files or folders (wrt a specified criterion).
These trees are selected using the Set buttons, or specified by entering their full pathname in the appropriate fields, or by choosing an existing named configuration (see below) from the popup menu. The paths are remembered between editing sessions.
The keyboard shortcut to display the dialog is ⌃⌥⌘S (Ctrl-Opt-Cmd-S).
With the Comparison criterion popup menu, you can specify the criterion used to compare items between the two hierarchies. Currently one can compare by:

Modification date
Creation date
File name
Subversion revision number

Comparison by name is just a handy way to adjust the contents of the hierarchies: if a file is present in both hierarchies, it won't be affected. When comparing based on a revision number, both hierarchies must be under version control: if a file does not have a revision number in one of the hierarchies, it will compare as equal.
With the Remove items which are only in target checkbox, one can ask that the items which are in the target (i-e older) directory but are no longer in the source (i-e newer) directory be removed from the target (i-e the old) hierarchy. Be careful with this checkbox since this is not undoable: an alert dialog will ask for confirmation when this box is checked. Note that the files are not really deleted, they are just sent to the Trash, so that, in case of accident, you can rescue them therefrom.
With the Skip items which are only in source checkbox, one can ask that the items which are in the source (i-e newer) directory but are not yet in the target (i-e older) directory be ignored during the synchronization. They are still listed in the reports though.
Three radio-buttons, called in all subfolders, in top folder and down to sublevel respectively, let you specify if you want the synchronization to be performed in all the subdirectories of the target and source directories recursively, or in the top level directory only, or in the subdirectories down to a specified sublevel.
The Report button performs a dry-run: it generates a report about the differences found between the trees, but no synchronization is made. The Synchronize button does execute the synchronization according to the settings made in the dialog. A log of the copies and updates executed is displayed when the synchronization completes.
The Swap button lets you swap the source and target paths: if there exists a configuration corresponding to the swapped settings, its name will automatically be displayed in the Configurations popup menu, otherwise this will be assigned to the Temporary configuration.

Configurations

A particular setting of the target and the source directories is called a configuration. The Synchronizer package can record named configurations. In order to create a new named configuration, use one of the following methods:

use the New Configuration… command in the Synchronizer menu;
alternatively, while the main dialog is running, set the target and source directories with the Set buttons, then click on the Save Config button.

To make a configuration active, use the Configurations submenu in the Synchronizer menu, or the top popup menu inside the main dialog. There are also menu items which let you edit, rename or delete a configuration.
There is a special configuration called 'Temporary': any changes made, in the main dialog, to the target or source directory and not saved as a new configuration are recorded in the 'Temporary' configuration. Note that one cannot delete or rename the 'Temporary' configuration.
The Dump Configurations… command lets you create a file on disk to keep the currently defined configurations. This is a way of editing configurations or storing them for later reuse. A dump file of this type can be loaded using the Load Configurations… command. The format of the dump files is straightforward: empty lines and lines starting with a "#" symbol are ignored. The others contain three values separated by a tabulation: the configuration's name, the path of the target (=older) directory and the path of the source (=newer) directory.

Copy methods

There are currently two different implementations of the synchronizing algorithm: using Alpha or using the rsync command line tool. By default, Alpha's implementation is activated. Technically, these methods are defined as xserv services.
If you want to change the implementation, select the menu item Alpha ↣ Global Setup ↣ Helper Applications and go to the Files category: in the dialog window, find the Synchronizer service and use the Set button (rightwards arrow) to select an implementation for this service.
If you are using Alpha's implementation, there are also different methods to perform the copy of files or folders from source to target. There are designated as the FileCopy service. Currently three methods are available to execute this service:

using the Tcl command [file copy].
using the Unix tool ditto.
using AppleEvents to have the Finder execute the copy.

By default, the ditto implementation is activated. You can also change this in the Files category of the menu item Alpha ↣ Global Setup ↣ Helper Applications.
If you are using rsync's implementation, the FileCopy service is irrelevant because rsync has its own famous delta-transfer algorithm sending only the differences between the source files and the existing files in the destination.

Preferences

Using the menu item Tools ↣ Synchronizer ↣ Synchronizer Preferences (or alternatively Alpha ↣ Preferences ↣ Package Preferences ↣ Synchronizer), one can set some default values for the different parameters, like for instance the comparison criterion. Click here to display the Synchronizer Preferences panel.
With the Ignore VCS files flag, one can ask that the administrative files and folders of some version control systems (CVS, Subversion, Git, Mercurial) be skipped during synchronization: if the trees are under version control, you wouldn't want, generally, this kind of data to be affected. The default value is 1.
With the Include invisible files preference, one can ask that the invisible files (whose name starts with a dot) be also taken into account by the synchronization. The default value is 0.
The options and configurations can also be set via the Options and Configurations submenus respectively.

Synchronizing from a script

This section is intended for developers or users who want to use the Synchronizing facility from a script.
The Synchronizer package provides a Tcl proc called sync::synchronize which by-passes the dialog and lets you specify directly the relevant options to perform a synchronization.
The syntax is:

    sync::synchronize targetDir sourceDir ?args?

The required arguments are the target (=older) tree and the source (=newer) tree, in this order: older first, newer second.
The args argument can be used to pass additional settings. It should be a list suitable for the [array set] Tcl command, that is to say containing successively the name of a key and the corresponding value. For instance:

    skipIfOnlyInSource 1 removeIfOnlyInTarget 0 includeInvisibleFiles 1

The available keys are:

Flags	Default
removeIfOnlyInTarget	0
skipIfOnlyInSource	0
includeInvisibleFiles	0
ignoreVcsFiles	1
Strings	Default
criterion	"Modification date"

The value of the criterion key can be: "Modification date", "Creation date", "Name", or "Subversion revision".

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2004-2019, Bernard Desgraupes.
All rights reserved.
The Synchronizer package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Bernard Desgraupes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BERNARD DESGRAUPES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.