synXer User Manual
for synXer version: 1.0
© 2007 hipercom.pl
Table of contents:
- Foreword
- Requirements and licensing
- Configuration
- Synchronization modes
- Creating a project
- Opening and saving a project
- Executing a project
- Troubleshooting
1. Foreword
synXer is a tool, which will help you keep your projects up-to-date when working
on multiple machines. Its only function is to compare the content of two directory trees
(folders and all their subfolders with content) and decide what must be copied where to
meet your needs. It works with all external USB and FireWire disks, PenDrives, Memory
Sticks and such. It also works with disks mounted remotely via the network. The rule of
thumb is: if you can see something mounted on your desktop, you can use
synXer on
that.
The examples of scenarios, in which
synXer may come in handy are as
follows:
- You work on different Macs (e.g. at home, at work, at school) and have to take your
work with you. You need to be sure you won't waste your time by overwriting your most
recent version of a project by an old one, at a different machine. Copying your whole
project tree every time you switch to a different machine is no solution - it simply
takes too much time. What you need is a reliable, small and fast external storage (e.g.
a Sony 8GB MicroVault Pro external 1-inch HDD may be a good choice) and a piece of
software, which will check for you which files should be copied and where.
synXer is that piece of software.
- You make periodic backups of your work and/or software on a different storage
(possibly mounted remotely via the network). However, the amount of stuff dear to you
grows rapidly and you don't want to copy everyting all the time. It would be best to
add to the backup only the items you have acquired since the last backup. synXer
will handle it for you.
- You are a developer who needs to synchronize a project periodically to get updates
made by other developers. The project sources are located on a FTP server. If you mount
the FTP project repository in Finder (so that it appears as an external disk on
your desktop), you can use synXer to download only files changed by other
developers while you have worked on some other parts of the project. To use
synXer to upload your work, you'd have to mount the FTP repository read-write,
which is currently not possible in Finder, unless you use some third-party
(free) software, like MacFUSE. However, using a specialized version controlling
software might be a better solution in this scenario, but if you have no access to such
services, a simple FTP repository might be helpful for a time.
Judging from the examples above, you may find
synXer useful no matter whether
you're connected to the network or off-line, whether you use just a single Mac or many of
them (or a mix of Macs and PCs), and whether you're a professional or just want to make
sure your music and documents are safely backed up. If you have to copy periodically some
data between different folders (no matter on local, remote, internal or external disks),
synXer may save you some time and effort.
Probably you think now: "there must be plenty of such applications on the Internet".
Surely, you're right. There are quite a few, and some of them available for free. I've
used several of them before and the reasons I wrote
synXer and enjoy using it are
as follows (the features most important in my opinion are written
in red):
- synXer is freeware, you can use it in any environment (home, work, school)
and in any way, without paying any fees, and you don't break any license terms by doing
that.
- synXer is quite fast when comparing with other free
products. Detailed comparisons haven't been made so far, so just take my word it's fast
enough (I synchronize a 1GB+ folder with about 4 thousand files many times a day and
don't complain about the performance).
- synXer is a native Mac OS X application, doesn't depend on any third-party
software (all you need is the synXer.app bundle) and is written using Cocoa,
Objective-C and Apple's development tools. That means there's no need for installation
- you can run synXer from any location (even an external disk), carry it with
you or run it from a CD-ROM or other read-only media (like the installation disk image
or a folder mounted via the network).
- synXer is a universal binary, which means you can use the same executable on
both PowerPC and Intel based Macs.
- synXer prepares a schedule before it touches your
data. You can review the schedule and turn off particular actions if they look
suspicious to you.
- synXer is a document-based and multithreaded
application, which means you can open several synXer projects at once and
perform many synchronizations simultaneously.
- synXer automatically scans the default project folder
and shows you a handy list of your projects, so that the actual synchronization is just
two clicks (or hits of Return) away.
- synXer preserves symbolic links (aliases), even if you synchronize between
Mac HFS+ and FAT32 file systems.
So, try it out. If you decide you don't need it, well... you do have the Trash in your
dock, don't you? And if you have any comments or suggestions, feel free to send an e-mail
to
synxer@hipercom.pl.
Best Regards
Tomasz Tyrakowski, the author.
Back to the table of contents...
2. Requirements and licensing
synXer system requirements:
- Mac OS X version 10.4 (Tiger) or later.
- Apple Macintosh computer with a PowerPC G4 processor or better, or with any Intel
processor.
- 256MB RAM or more.
- About 1MB of free disk space for the application plus some space for saved projects
(a single projects requires about 4kB of disk space).
By downloading and using synXer you agree with the following license terms:
Copyright © 2007, hipercom.pl
All rights reserved.
REDISTRIBUTION
Redistribution an use in binary form, without modification,
are permitted provided that the following conditions
are met:
* Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
NO WARRANTY and NO SUPPORT sections, in the documentation
and/or other materials provided with the distribution.
* Neither the name of hipercom.pl nor the names of its
contributors may be used to endorse or promote products
derived from this software without specific prior written
permission.
NO WARRANTY
Because the program is licensed free of charge,
there is no warranty for the program, to the extent
permitted by applicable law. Except when otherwise
stated in writing the copyright holders and/or other
parties provide the program "as is" without warranty
of any kind, either expressed or implied, including,
but not limited to, the implied warranties of
merchantability and fitness for a particular purpose.
the entire risk as to the quality and performance of
the program is with you. Should the program prove
defective, you assume the cost of all necessary
servicing, repair or correction.
In no event unless required by applicable law or
agreed to in writing will any copyright holder,
or any other party who may modify and/or redistribute
the program as permitted above, be liable to you for
damages, including any general, special, incidental
or consequential damages arising out of the use or
inability to use the program (including but not limited
to loss of data or data being rendered inaccurate or
losses sustained by you or third parties or a failure
of the program to operate with any other programs),
even if such holder or other party has been advised
of the possibility of such damages.
NO SUPPORT
hipercom.pl does not provide any direct support for
its free software. Any issues related to the free
software manufactured by hipercom.pl should be
resolved by consulting the User Manual, included
in the software package, and visiting the product's
web page. |
Please make sure you understand the NO WARRANTY and NO SUPPORT sections.
If you don't agree with them, please remove synXer from your computer.
Back to the table of contents...
3. Configuration
In the current version of
synXer, there are just two settings you may want to
adjust (I wanted to keep
synXer as simple, as possible, and having to set dozens
of options before using an application may be a bit annoying):
- The default location of synXer project files (by default the sub-folder
synXer in your Documents folder). That's the location, which gets
scanned automatically by synXer when it prepares the project list. Of course it
doesn't mean you can't save your project anywhere else. The synXer projects are
just ordinary files and you can save and load a project from any location
(folder). What you need to understand is that if you save your synchronization project
anywhere outside the default projects folder, the project won't show up on the project
list.
REMARK. When you first run synXer, it will create the default projects
folder. You can change the location of this folder in the preferences and, if the new
folder doesn't exist, synXer will try to create this one for you, too. However,
if you have already saved some projects in the old projects folder, you have to copy
them manually to the new location to make them available for opening via the project
list.
- The tolerance in date/time comparison. synXer decides which file is more
recent by comparing the modification dates. Some tests and observations suggest, that
it's better to have a small tolerance when comparing modification dates (small means a
few seconds, usually one second is enough). In particular, when you synchronize a
folder located on a HFS+ (native OS X format) volume and a folder located on a FAT32
(old Windows format) volume, then if you run the synchronization again, there still
will be a list of files to copy, although they are in fact identical. That's due to a
subtle inconsistency in the modification dates. synXer sets the file's
modification date in the destination folder to match the modification date in the
source folder (otherwise after the synchronization the destination folder would seem to
have more recent versions). Somehow those dates differ by a small amount (usually just
one second). It might be a subtle bug in the Cocoa's NSFileManager
class implementation or in the FAT32 support in Mac OS X. Instead of trying to shift
the modification date being set (which would cause problems with HFS-HFS
synchronization, as there is no such effect in that case), I've decided a better
solution is to use a small tolerance when comparing dates. After all, it seems very
unlikely you'll change a file on one machine and a second later you'll change the same
file on a different machine (or even on the same machine, but in a different folder).
However, if you prefer strict comparisons, which may result in redundant copying, set
the tolerance to zero (that's exactly what some of the other synchronization programs
I've tested do, and that's one of the reasons I wrote synXer - by principle,
just after the synchronization there should be nothing to synchronize).
The configuration panel is rather self-explanatory. Use the
Choose button to
select a new location for the
synXer projects and/or type in the new date
comparison tolerance. When done, just close the preferences window. Your settings are
visible immediately after you change them (there's no
Apply or
OK
button).
To get back to the default settings, click the
Factory defaults button.
REMARK. You should change the settings only when you're not satisfied with the
default behavior of
synXer. In most cases you'll never need to open the
preferences panel.
The preferences are stored in the user preference database (usually in the
Library/Preferences folder in your home directory), so each user may set his or
her own preferences. This implies, that if you log in as a different user, or if you run
synXer on a different machine, the preferences will be set back to the factory
defaults.
Back to the table of contents...
4. Synchronization modes
There are three synchronization modes in
synXer. It is important to understand the
similarities and differences between them to choose the one best suited for a particular
purpose. In the description below we assume that
src denotes the source folder and
dst - the destination folder.
Overwrite.
This mode should ensure that after the synchronization
dst is an exact copy of
src. For example, if you work on a project on two different machines (
A and
B), and carry your work on an external disk, you should perform overwrite on
machine
A to the external disk, then go to machine
B and perform the
overwrite
from the external disk to the local folder of
B. After you finish
your work on
B and before you go back to
A, first execute an overwrite from
B's local folder
to the external disk, and then
from the disk to
A's local folder. This way your external disk should always have the most recent
snapshot of your work when you leave either one of your machines. The exact rules in the
overwrite mode are as follows (notice: when we write "an object is removed" or "an object
is copied", we actually mean that a particular operation will be added to the schedule;
before you execute the schedule you have an opportunity to turn some actions off - see
section 7).
- For each object O (that is, a file, a folder or an alias) in src,
check whether its counterpart exists in dst.
- If the answer in 1 is "NO", then copy O to dst (if O is a
folder, it will be copied recursively with all its content).
- If the answer in 1 is "YES", check whether O and its counterpart in
dst are objects of the same type (file, folder, alias). If not, copy O to
dst, overwriting its counterpart.
- If the answer in 3 is "YES", compare the modification dates of O and its
counterpart. If the dates differ (no matter which one is more recent), copy O to
dst, overwriting its counterpart, otherwise take no action. There's an exception
to this rule and it concerns folders. If the modification dates of folders differ,
O won't be copied to dst (that would mean a recursive copy of all the
content, some of which might have not changed at all). Instead, synXer will
compare the content of O file-by-file to determine which part of the folder
content actually differs from its counterpart in dst, and makes sure only the
actual differences will be placed in the schedule.
- As the last step, synXer will check all objects in dst and remove
those, which don't have their counterparts in src.
Please make sure you understand point 4. It says, that in the overwrite mode
synXer will overwrite an object in the destination folder no matter whether it is
older or newer than its counterpart in the source folder. That's the main principle of
the overwrite mode: source folder objects always take precedence. Also, take a look at
point 5 - some objects in the destination folder may be removed. You can be sure that the
source folder will remain intact - there's only one-way copying in this mode.
Complement.
This is the best mode for incremental backups or creating libraries from different
resource folders. It fills up
dst, adding all the objects from
src, which
don't exist in
dst. In this mode synXer will never delete any files and will
overwrite only those, which have more recent counterparts in
src and those
counterparts are of the same type. An example scenario: you download scientific papers
from time to time and put the downloaded papers in your local folder. You also have a
repository of all downloaded papers on an external disk. Every time you download a set of
new papers, you update your repository and after some time eventually remove the papers
from your local disk, making room for more. The best
synXer mode for this scenario
is complement. All the papers you recently downloaded will be copied to your
repository, unless the repository already contains some of them. No papers from the
repository will be removed, and if you download a more recent version, it will replace
the older one in the repository. So the rules for an object
O from
src are
as follows:
- If the counterpart of O does not exist in dst, O is copied to
dst.
- Otherwise, if O and its counterpart have the same type (file, link, folder),
synXer compares the modification dates of O and its counterpart and if
O has a more recent one, it is copied to dst (unless O is a
folder, in which case its content is examined instead of performing a recursive
copy).
- If the modification dates are equal (or the O counterpart's in the
destination folder is more recent), or if the types of O and its counterpart
differ, no action is taken.
Synchronize.
This mode works somewhat like two-way complement. It is best suited for scenarios, in
which you work on two or more machines on different projects and then you want to make
sure all the machines have the most recent version of all projects. In this mode,
synXer will never replace a newer file with an older one and will never delete any
files. If a counterpart of an object doesn't exist, the object is copied to the other
folder instead of being removed from the current one. The exact rules are as follows:
- For each object O in src, check whether its counterpart in
dst exists.
- If the answer in 1 is "NO", O is copied to dst.
- Otherwise, check if O and its counterpart are of the same type (file,
folder, alias).
- If the answer in 3 is "NO", no action regarding O is taken.
- If the answer in 3 is "YES" and O has a more recent modification date,
O is copied to dst (unless O is a folder, in which case its content is
compared entry-by-entry). If the dates are equal or O is older, no action is
taken.
- The steps 1-5 are repeated for the destination folder treated as the source
folder and vice versa.
REMARK. If you had read the description above carefully, you probably discovered
some special cases, in which synXer will take no action when in fact making a copy
might be a better choice. All such scenarios concern the situation, in which an
object in src and its counterpart in dst are of different type (file,
folder, alias). Well, the situations, in which you remove a file, and then create a
folder with exactly the same name in its place (and do that between
synchronizations) are relatively rare, and I have decided it would be best to leave those
unhandled (at least in the current version of synXer), as it is not clear which
action is the most appropriate in such cases.
Back to the table of contents...
5. Creating a project
To create a new synchronization project, either choose New project from the
File menu, or use the New button located at the bottom of the project list
window. A project window will appear, as shown on the picture below:

Before you run your project, you need to tell
synXer what you intend to do. First,
enter the name of your project (unless you don't plan to save it, in which case the name
is irrelevant). Then choose the source and destination folder by pressing the appropriate
Choose button. As the last step, choose the synchronization mode (for a detailed
description of synchronization mode, please refer to
section 4).
If you decide to save your project for later use, please refer to
section
6 for a detailed description of saving and loading of projects.
If you wish to execute your project right away, just click the
Prepare schedule
button and refer to
section 7 for a detailed description of the
synchronization process.
Back to the table of contents...
6. Opening and saving a project
When you create a new project (see
section 5), usually you will want to
save it for a later use (you are not required to save your project in order to run it; if
you wish to perform a one-time synchronization, which will not be repeated periodically,
there's no need to save the project - just run it and close when done).
synXer projects are just ordinary files with the
.synxer extension. It
is recommended to leave the default extension, because there's an association between
synXer and
.synxer files in the
Finder (double-clicking a
.synxer file will open the project in
synXer).
synXer projects have their own icon to be easily distinguished.
If you want to save your project, choose the
Save (or
Save As...) item from
the
File menu. You will be presented a standard OS X save file panel, which will
start initially in the folder chosen as your default projects folder (see
section 3 for details). Of course, you can save your project in a folder of your
choice. However, only the projects stored in the default location and with the default
.synxerextension will be automatically recognized and presented in the project
list window (the project list window is described later in this section), so the most
convenient solution is to store your project in the default location and keep the default
extension. This way you will be able to access the project quickly next time you run
synXer.
There are two ways of opening a project: through the project list and through a standard
open file panel. We will start with a description of the project list window:

The
Available projects list contains all projects from the default projects folder
(see
section 3). The list shows the descriptive
names of the
projects, not their
file names (the names are entered by the User as one of the
project parameters, see
section 5).
Under the project list there is a detailed description of the selected project (i.e. the
source and destination folder and the synchronization mode).
At the bottom of the project list window there are three buttons for the most frequently
used operations.
If you wish to open a project through the project list window, you have three possible
solutions:
- Select the project you wish to open either with cursor keys, or with a mouse, and
then press Return (the default button in the project list window is Open,
so hitting Return is equivalent to clicking at the Open button).
- Select the project you wish to open with cursor keys or mouse and choose Open
selected from the File menu (or press the Command-O keyboard
shortcut).
- Double-click the project you wish to open with the mouse.
Find yourself the way which is the most convenient for you.
If you wish to open a project, which is not located in the default projects folder,
select
Open project file (
Shift-Command-O keyboard shortcut) from the
File menu. You will be presented a standard open file panel, in which you can
select the project file you wish to open.
If the file you wish to open is not a valid
synXer project, you will get an error
message saying

where "1.synxer" will be replaced with the file you chose. That means the file you
selected is not in fact a synXer project, but by a conincidence was assigned the
.synxer extension.
REMARK. The Delete button in the project list window removes the selected
project from the project list and deletes the file it resides in from the projects
folder. Please be careful - if you confirm the removal of the project, it will be deleted
permanently.
You can show and hide the project list window by pressing Command-L or choosing
Show / hide project list from the Window menu. If you close the project
list window by accident, don't worry - you can bring it back by Show / hide project
list.
Back to the table of contents...
7. Executing a project
Once you have your project set up, you will surely wish to perform the actual
synchronization. The synchronization process consists of three phases:
- Schedule preparation.
- Schedule execution.
- Error reporting.
To begin phase 1, click the
Prepare schedule button in your project window (or hit
Return - the
Prepare schedule button is the default button in the project
window, so hitting
Return activates it). When the preparation of the schedule is
in progress, you are presented a small sheet (sliding from the top of your document
window), which informs you how many actions have been already added to the schedule and
which animates a progress indicator to show you that the work is still in progress:

Please note the
Stop button at the bottom of the sheet. If you decide you want to
break the preparation of the schedule, click the
Stop button and the process will
stop immediately (however, no schedule will be presented in that case -
synXer
assumes, that it is better to have no schedule, than to have an incomplete one, which may
lead to data inconsistency).
After the schedule is prepared, the document window will automatically switch to the
Schedule tab, where you can review the action list before you decide (or not) to
execute it. The action list consists of four columns, which we describe from left to
right:
- The status of the current operation.
This column shows the status of a particular operation. There are four possible values
(symbols) appearing in this column:
-
- no symbol means the operation is scheduled for execution, but has not been
executed yet,
means this
action has been successfully executed,
means there
was an error while synXer was trying to perform this action,
means this
action is currently being executed,
means this action
has been canceled by the User.
- The type of the action.
There are three types of actions, which can be performed by synXer:
-
means the object from
the 4th column will be copied to the other folder,
means the object
from the 4th column will be deleted,
means the
attributes of the counterpart of the object from the 4th column will be set.
- The type of the object.
synXer will show you whether a particular operation affects a file (or alias),
or a whole folder together with its content:
-
means the object from
the 4th column is a file,
means the object
from the 4th column is a folder.
- The last, fourth column, shows the exact location (a full path) of an object, which
a particular action is dealing with:
-
- objects from the source folder are displayed in
green,
- objects from the destination folder are displayed in
red.
If you wish to cancel an operation, double-click it with your mouse. A small

mark will appear in the first
column and the operation will not be executed in the current schedule. Why should you
want to cancel an action? Well, you may decide for example, that copying a 600MB+ disk
image is not convenient at the moment.
After you review your schedule, execute it by clicking the
Execute schedule
button (or just press
Return - the
Execute schedule button is the default
button now, so pressing
Return will activate it). When the action list is being
executed, you are presented with another progress sheet, as shown below

The progress bar indicates the percentage of executed actions (not the percentage of
bytes transferred), so its progress may accelerate or slow down, depending on the sizes
of objects being copied. You can again break the execution of the schedule by clicking
the
Stop
After the schedule is completed,
synXer will switch automatically to the
Errors tab, in which all actions, which have not been completed successfully, will
be shown. The table of errors has just three columns (the status column is useless, as
only errors are presented here anyway): operation symbol, object type, and error message
(containing the full path of the object).
If the schedule is completed without errors, the error list should be empty.
The default button in the
Errors tab will close the project (thus hitting
Return while in the
Errors tab closes the document - see remarks
below).
REMARKS.
- You can break the execution of the schedule by clicking the
Stop button, but the reaction might not be immediate. The execution of the
schedule stops after the current action is finished (you wouldn't like to have a file
half-copied, would you?). While the schedule is being executed, the action list is
being updated in real time to show you which actions have been completed (and whether
any of them caused errors), and which action is currently being performed.
- When there are no differences between the source and the destination (or the
schedule has not been prepared), the Execute schedule button is inactive.
- The quickest way to synchronize folders after mounting an external storage is:
choose your project with cursors, press Return (opens the project), press
Return again (prepares the schedule), when the schedule is ready press
Return again (executes the schedule), when the schedule is executed press
Return for the last time to close the document. That's it.
Back to the table of contents...
8. Troubleshooting
- synXer doesn't start. It shows an icon in the dock and terminates
immediately.
Probably you use Mac OS X version older than 1.4. synXer works only on version
1.4 or later. See section 2 for synXer requirements.
- synXer doesn't synchronize with a folder mounted via FTP in Finder.
Unfortunately, it is impossible to mount an FTP folder in Finder in read-write
mode (see this Apple
Technical Note). Therefore, you are able to synchronize from a FTP location,
but not to one.
- After selecting a folder in the project window via the Choose button, the
folder field shows a totally different location.
That means the folder you selected is not really a folder, but an aliast pointing to a
folder. synXer traverses the alias and shows you the folder the alias is
pointing to, not the aliast itself.
- The Delete / Copy operation fails on a file or folder.
There may be many different reasons for that. First, you have to make sure you have
sufficient priviledges in the destination (and source, too) folder. If you are the
owner, probably you have. If not, try Get Info from the context menu in
Finder and check the permissions (at the bottom of the info window). If you are
to delete a file in a folder, you should have a write priviledge to that folder.
If you get a Delete before copying failed error, the reason may be the same as
above. Another situation, in which you can't remove a file is when a working
application opened that file for writing. If you get detete errors check your running
programs and make sure no program is using a file from the target folder.
- It is not possible to cancel a group of actions at once.
That's by purpose. Normally, you should never need to cancel an action. This feature
is included in synXer to handle some special cases. If you feel you know better
what to copy, do it yourself instead of using an automated synchronizer.
Back to the table of contents...
© 2006-2007 hipercom.pl