Setting up Unison for your mom

by Philip Guo (philip@pgbovine.net)

Introduction

One year ago, I extolled the virtues of Unison in my article entitled Unison File Synchronizer: Liberation through Data Replication. This article is sort of a sequel; here I will provide instructions for setting up Unison in a way such that someone who is not a computer expert can easily use it on a daily basis. I've just set up Unison for my mother tonight, and I want to help others who want to provide the same gesture of affection for their own loved ones. Unfortunately, software such as Unison is still not yet at the stage where non-hackers can easily configure it, so your mom will still need you to help her set it up (assuming that she's not a hacker). My hope, though, is that after the initial setup work is done, she can simply invoke Unison from all of her computers by double-clicking on a desktop icon, and it should work like magic.

One more passionate plea for people to use Unison

Who can benefit from using Unison? Anyone who regularly works on more than one computer and needs access to the same set of files. For the past few years, my mother has been working on a desktop computer and a laptop at home, as well as on a desktop computer at her office. She routinely copies her Word documents, Excel spreadsheets, PDFs, and other files over to USB flash drives, carries them between her home and workplace, and manually copies every file over to its appropriate directory within My Documents. Sometimes she gets things wrong and clobbers a newer version of a file with an older one, sometimes she moves a file into the wrong place and ends up with duplicates that she must compare by hand, and sometimes she loses a chunk of her valuable work data when one of her computers' hard drives crashes. She has even told me that she wishes she could have some kind of synchronization software to prevent some of these problems, and her wishes came true in the form of Unison. With Unison, she no longer has to worry about keeping files up-to-date or manually copying versions of files that she edited on different computers into the correct directories, and her chances of data loss due to hardware failures are diminished because she has several versions of her data at different locations.

My mother is not alone. Nobody should have to manually synchronize their data or risk losing it when a machine crashes. Data is far too valuable to be left to the error-prone devices of humans. Ok, I will stop fuming now and get to the instructions.

Setting up Unison for your mom

These instructions are for configuring Unison to synchronize data between several computers (all running Windows XP) and one external hard drive. I chose this configuration because my mom, like most computer users in 2006, runs Windows XP and stores all of her documents in the My Documents directory of her computer's internal hard drive. She has an external USB hard drive with enough space to back up all of her data. The external hard drive acts as the hub, and each computer synchronizes against it. If your mom doesn't have that much data, a USB flash drive might also work instead of a hard drive; it's a cheaper option if you don't need as much storage space.

The way that my mom will use Unison is to connect her hard drive to one computer, synchronize, do some work, and synchronize again when she is done. Then she will carry her hard drive with her, plug it into the next computer she sits down at, synchronize, do some more work, and synchronize again when she is done. This way, all of her computers as well as the USB hard drive have live backups of her data. She does not need to have an active Internet connection for this configuration to work.

Ok, here we go ... setting up Unison for your mom ...

1. First, you need to peek into your mom's My Documents directory and ask her which sub-directories or files she does not care to back up. These might include My Music, My Videos, or other random data directories that applications create for users. Write down those file and directory names because you will need them in later steps. Perhaps you might want to create a sub-directory called Junk to ignore and have her throw all of the undesirable files in there.

2. Ask your mom whether she's happy with her current directory structure and whether she would like to clean things up within My Documents (e.g., moving files around, creating more meaningful sub-directories, renaming sub-directories, etc.) before the initial synchronization. Explain to her that it is cumbersome (but still perfectly possible) to change the directory structure later on after it's been synchronized across several different computers, so she should be satisfied with her directory structure before you begin.

3. Plug in her external hard drive (or flash drive) and note the drive letter name it is mounted as (usually D: if you only have one internal hard drive). Go to D: in My Computer and create a directory named unison-backup. Now jump into unison-backup and create a directory named My Documents (with the space in the middle!).

4. D:\unison-backup\My Documents is going to be the replica of My Documents on the external hard drive. Now you should copy over all the files in My Documents over to D:\unison-backup\My Documents. You can safely ignore the directories and files that you wrote down to ignore from Step 1.

5. At this point, with the exception of the ignored directories and files from Step 1, D:\unison-backup\My Documents should be a perfect replica of My Documents on your computer. This is the starting point for Unison to synchronize --- both sides are identical.

6. Download the Windows installer of the GTK+ graphics library because you will need it to run the graphical version of Unison. I tried gtk+-2.8.18-setup-1.exe and it worked fine. Install it with the default options and restart your computer.

7. Download a Windows binary of Unison with a graphical interface (using GTK). I personally tried unison-2.13.16-win-gtk2.exe and it worked fine.

8. Move the Unison executable to your Desktop or somewhere convenient and double-click it to try to run it. If it complains about not being able to find GTK or something, then read this info file written by the guy who made the Windows binaries for some inspiration. Otherwise, it should pop up a dialog box asking for you to specify a root or something. Just hit cancel and exit the application. The side-effect of running Unison for the first time is that it has created a .unison directory in C:\Documents and Settings\USER\ where USER is the user's Windows login name.

9. Navigate into C:\Documents and Settings\USER\.unison\ and you should see a file named default.prf. This is the Unison profile file that you will need to customize in order to get Unison to work for your mom. Open this file in Notepad or another text editor (no, Microsoft Word is NOT a text editor!) and override it with the following text, remembering to add in some blank lines at the end of the file:

   # Unison preferences file - for yo mama
   
   root = C:\Documents and Settings\USER\My Documents
   root = D:\unison-backup\My Documents
   
   # Ignore certain directories and files
   ignore = Path My Music
   ignore = Path Junk to ignore
   ignore = Name Thumbs.db
   ignore = Name Desktop.ini
   
   # Helps out a lot on Windows
   fastcheck = true
   
   # Don't synchronize permission bits
   perms = 0
   
   # Place new files at the top of the list
   sortnewfirst = true
   
   backup = Name *.doc *.pdf *.xls *.txt
   
   # It's a good idea to insert a few blank lines at the end of
   # this file, or else when Unison appends to it, it might
   # accidentally clobber some of your own lines.
   
   

10. This is the starting point for your Unison profile. Let me explain certain parts in more detail.

    The two root lines are the most important. They tell Unison the two endpoints for the synchronization. In this case, the left-hand root is C:\Documents and Settings\USER\My Documents on the computer (of course, replace USER with the real Windows login name), and the right-hand root is D:\unison-backup\My Documents, which is on the external hard drive. Recall that in Step 4, we made sure that the two roots had the same data by copying all the relevant data from the computer to the external drive. Note that if your hard drive mounts as a letter other than D:, you will need to change this line. Also, this will only work if your drive always gets the same drive letter. For example, if you plug in more than one device, the drive may sometimes become E:, which will confuse Unison. Finally, notice that you must use absolute paths, which is why the cumbersome C:\Documents and Settings\USER\My Documents path is necessary.

    The ignore lines specify directories (using the Path keyword) and files (using the Name keyword) to ignore when performing synchronization. In this example, the My Music and Junk to ignore sub-directories within My Documents are to be ignored, as are the pesky Desktop.ini and Thumbs.db files generated by Windows Explorer (in all sub-directories).

    The subsequent lines do other useful things; you can look up their meanings in the Unison User Manual. In particular, fastcheck = true is key to speeding up synchronization for Windows.

11. Now comes the moment of truth ... running Unison successfully for the first time. Double-click on the Unison executable icon again, and choose 'default' as the profile to use (it should be the only one). A big dialog box will pop up to tell you that you have never synchronized these roots before (which is true), so hit OK. Now Unison will scan through both your C: and D: drives in the respective roots to perform the initial synchronization. This might take anywhere from a few minutes to an hour depending on how much data there is, but the good news is that subsequent runs will be much, much faster :)

12. In a perfect world, Unison will finish running and detect no differences because, after all, the two roots should be identical at this point. But alas, the real world is not perfect, and there are probably some files (most notably ones with weird names) that Unison cannot do a good job of synchronizing for some mysterious reason. Those will show up as conflicts in the file list. Select the Ignore menubar entry, then click Permanently ignore the path for these troublesome files. This will add ignore lines to your default.prf profile so that the next time you run Unison, those files will be, well, ignored. Press the "Go!" button and wait for things to finish, then exit.

13. Close Unison and then run it again. Hopefully this time it should say that the synchronization has completed without any conflicts or other necessary actions. Do it again one more time, just to make sure. Now you are all set up!

14. Now ask your mother to use her computer in a normal way for a few hours (preferably having her create, modify, delete, and move files), and then sit down with her to practice the synchronization process. When she plugs in her external hard drive again, double-clicks and runs Unison, it should take several seconds to a minute to scan her computer and external drive and come up with a list of files that have changed since the last synchronization. All of those files should have a green arrow pointing from left to right, which indicates that the default behavior is to propagate the changes from the computer (left root) to the external hard drive (right root). This makes sense because the most updated versions of her files are now on her computer and need to be copied to the external hard drive. Hit "Go!" to perform the synchronization, wait for it to complete, and exit. Now look at the contents of the external hard drive to verify that it has indeed been updated.

    When she creates a new file or modifies an existing file, it is intuitive that the change is propagated to the external hard drive, but be warned that if she deletes a file, the deletion will also propagate to the external hard drive (which, if you think about it, is the correct behavior).

15. Repeat this same process to set up Unison on the other computers that your mom will use on a daily basis :)

16. Here is the daily drill that your mom should abide by in order to use Unison productively:
    1. As soon as she gets on a computer to start working, plug in the external hard drive, run Unison, and propagate all changes from the drive to the computer. All of the green arrows should be from right to left to signify that the newest versions of files are on the external drive (probably due to edits she made on other computers) and need to be propagated to this current computer before she starts working.
    2. She should work to her heart's content, making sure to only create new files within My Documents, which should be the default mode of operation on Windows XP anyways. Also, she should be aware of directories and files that you have set for Unison to ignore.
    3. After she is done working, run Unison again to synchronize. This time, all of the green arrows should be from left to right to signify that the newest versions of files are on the computer (because those are the files that she has edited in this session).
    4. If she ever forgets to synchronize at the beginning and end of every work session, she might get conflicts when Unison detects that a file has been modified on both roots. She will need to make a decision as to which version is the one she wants to keep. However, if she diligently abides by the simple rules of synchronizing right before she starts to work and right before she logs out, she will never encounter a conflict.

If everything goes well, the only thing your mom (or other loved one) needs to do to operate Unison is to double-click its icon, select the default profile, check over the list of updated files, and click "Go!" to synchronize.

Feel free to send comments, suggestions, questions, or rants to me via email: philip@pgbovine.net

Here are some email responses to this article.