synXer iconsynXer User Manual
for synXer versions: 1.0, 1.1
© 2007 hipercom.pl



Table of contents:
  1. Foreword
  2. Requirements and licensing
  3. Configuration
  4. Synchronization modes
  5. Creating a project
  6. Opening and saving a project
  7. Executing a project
  8. 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:
  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):
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:
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 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).
  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:
  1. For each object O in src, check whether its counterpart in dst exists.
  2. If the answer in 1 is "NO", O is copied to dst.
  3. Otherwise, check if O and its counterpart are of the same type (file, folder, alias).
  4. If the answer in 3 is "NO", no action regarding O is taken.
  5. 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.
  6. 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:

The project window

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 project icon 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 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

Invalid project alert

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

Preparing schedule

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:
If you wish to cancel an operation, double-click it with your mouse. A small Canceled 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

Execution of schedule

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.

Back to the table of contents...



8. Troubleshooting

  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.

Back to the table of contents...



© 2006-2007 hipercom.pl