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:

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

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.

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.

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

1. For each object O (that is, a file, a folder or an alias) in src, check whether its counterpart exists in dst.
2. 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).
3. 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.
4. 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.
5. 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:

1. If the counterpart of O does not exist in dst, O is copied to dst.
2. 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).
3. 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:

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.

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.

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

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:

1. 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).
2. 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).
3. 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.

Once you have your project set up, you will surely wish to perform the actual synchronization. The synchronization process consists of three phases:

1. Schedule preparation.
2. Schedule execution.
3. 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.

1. 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.
   
2. 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.
   
3. 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.
   
4. 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.
   
5. 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.

© 2006-2007 hipercom.pl