Skip to content

The Power of the SyncEvolution Command Line

With the Funambol iPhone plugin providing a nice GUI for SyncEvolution on the iPhone one might wonder what the advantages are of using the command line version on the iPhone. None of the other platforms have a GUI – why hasn’t anyone added one yet? This post will explore some of the things that can be done on the command line that would be hard to replicate in a GUI.

Traditionally SyncEvolution did not have many command line options: you could select the server to synchronize against in case you have configured more than one (which is entirely possible). Then you could select a subset of data sources to synchronize. Both is not such a big difference compared to a GUI. The advantages are in the output that you get. The iPhone plugin keeps things simple and just presents success or failure. But SyncEvolution offers much more than that.

Comparison of Database Changes

For me Evolution is the main storage location for my precious contact data. Whenever I sync, I absolutely want to be sure that no unintentional changes are applied to that data. Therefore starting with the very first release SyncEvolution would do a before and after dump of the data and print a comparison of those two dumps. Whenever some unwanted change is made, falling back to the previous state is as easy as reimporting the “before” data dump.

Several people have pointed out that changes applied to the server are equally important and that the output of SyncEvolution about “changes during synchronization” was confusing because it didn’t include the changes on the server. I’m a reasonable person (okay, usually), so I listened to those remarks and added a new feature to SyncEvolution 0.7 pre2: it also does another comparison between the data dumps after the previous sync and before the current one, i.e. this comparison lists the changes applied locally. They will be sent to the server in the next sync. This feature depends on having the previous data dump still around, either in /tmp or (and that is the recommended solution because /tmp is likely to be wiped out during a reboot) in the logdir configured in the syncml/config.txt.

Note that logdir must be set manually, it is not set in the example configs


Here is an example:

syncevolution scheduleworld
Local changes to be applied to server during synchronization:
*** vcard30 ***
no changes
*** ical20 ***
no changes
*** itodo20 ***
no changes
*** text ***
                     after last sync | current data
             removed since last sync <
                                     > added since last sync
BEGIN:VCALENDAR                          BEGIN:VCALENDAR
VERSION:2.0                              VERSION:2.0
BEGIN:VJOURNAL                           BEGIN:VJOURNAL
                                     >   SUMMARY:New memo.
                                     >   CATEGORIES:TEST
                                     >   CLASS:PRIVATE
                                     >   DESCRIPTION:New memo.\nThis needs t
                                     >    o be sent to the server.\n
                                     >   END:VJOURNAL
                                     > END:VCALENDAR
                                     > BEGIN:VCALENDAR
                                     > VERSION:2.0
                                     >   BEGIN:VJOURNAL
SUMMARY:Summary Modified                 SUMMARY:Summary Modified
DESCRIPTION:Summary Modified\nBody       DESCRIPTION:Summary Modified\nBody
text                                     text
END:VJOURNAL                             END:VJOURNAL
END:VCALENDAR                            END:VCALENDAR

A completely new memo is listed here as part of the local changes.

15:05:49 GMT +0100 [INFO] - Synchronization URL:
15:05:49 GMT +0100 [INFO] - Preparing synchronization of vcard30...
15:05:49 GMT +0100 [INFO] - Preparing synchronization of ical20...
15:05:49 GMT +0100 [INFO] - Preparing synchronization of itodo20...
15:05:49 GMT +0100 [INFO] - Preparing synchronization of text...
15:05:50 GMT +0100 [INFO] - vcard30: sync mode is 'two-way'
15:05:51 GMT +0100 [INFO] - ical20: sync mode is 'two-way'
15:05:52 GMT +0100 [INFO] - itodo20: sync mode is 'two-way'
15:05:52 GMT +0100 [INFO] - text: sync mode is 'two-way'
15:05:52 GMT +0100 [INFO] - text: 20071110T140450Z-5351-727-1-65@gollum: extracting from EV
15:05:54 GMT +0100 [INFO] - vcard30: John Doe, pas-id-4733548A0000000C, EV Doe, John: update
Synchronization successful.

The following table summarizes all changes transmitted during a synchronization. Sometimes changes might
be transmitted which did not modify data (e.g. when making a change and later reverting it, an update would
still be sent).

Changes applied during synchronization:
+-------------------|-------ON CLIENT-------|-------ON SERVER-------|
|                   |   successful / total  |   successful / total  |
|            Source |  NEW  |  MOD  |  DEL  |  NEW  |  MOD  |  DEL  |
|           vcard30 |  0/0  |  1/1  |  0/0  |  0/0  |  0/0  |  0/0  |
|            ical20 |  0/0  |  0/0  |  0/0  |  0/0  |  0/0  |  0/0  |
|           itodo20 |  0/0  |  0/0  |  0/0  |  0/0  |  0/0  |  0/0  |
|              text |  0/0  |  0/0  |  0/0  |  1/1  |  0/0  |  0/0  |

The following changes are again based on a comparison of the actual local data:

Changes applied to client during synchronization:
*** vcard30 ***
                           before sync | after sync
                   removed during sync <
                                       > added during sync
BEGIN:VCARD                              BEGIN:VCARD
N:Doe;John                               N:Doe;John
ADR;TYPE=HOME:Test Box #1;;Test Drive    ADR;TYPE=HOME:Test Box #1;;Test Drive
1;Test Village;Lower Test County;123     1;Test Village;Lower Test County;123
45;Testovia                              45;Testovia
ADR;TYPE=HOME:Test Box #3;;Test Drive    ADR;TYPE=HOME:Test Box #3;;Test Drive
3;Test Megacity;Test County;12347;Ne     3;Test Megacity;Test County;12347;Ne
w Testonia                               w Testonia
ADR;TYPE=WORK:Test Box #2;;Test Drive    ADR;TYPE=WORK:Test Box #2;;Test Drive
2;Test Town;Upper Test County;12346;     2;Test Town;Upper Test County;12346;
Old Testovia                             Old Testovia
BDAY:2006-01-08                          BDAY:2006-01-08
CATEGORIES:TEST                          CATEGORIES:TEST
EMAIL:john.doe@home.priv                 EMAIL:john.doe@home.priv             
NICKNAME:user1                           NICKNAME:user1
NOTE:This is a test case which uses a    NOTE:This is a test case which uses a
lmost all Evolution fields.              lmost all Evolution fields.
ORG:Test Inc.;Testing                    ORG:Test Inc.;Testing
ROLE:professional test case              ROLE:professional test case
TEL;TYPE=CAR:car 7                       TEL;TYPE=CAR:car 7
TEL;TYPE=CELL:mobile 3                   TEL;TYPE=CELL:mobile 3
TEL;TYPE=FAX;TYPE=HOME:homefax 5         TEL;TYPE=FAX;TYPE=HOME:homefax 5
TEL;TYPE=FAX;TYPE=WORK:businessfax 4     TEL;TYPE=FAX;TYPE=WORK:businessfax 4
TEL;TYPE=HOME:home 2                     TEL;TYPE=HOME:home 2
TEL;TYPE=PAGER:pager 6                   TEL;TYPE=PAGER:pager 6
TEL;TYPE=PREF:primary 8                  TEL;TYPE=PREF:primary 8
TEL;TYPE=WORK:business 1                 TEL;TYPE=WORK:business 1
TITLE:Manager                          | TITLE:Senior Manager

Only one line was changed: John Doe has been promoted…

URL:                 URL:
VERSION:3.0                              VERSION:3.0
END:VCARD                                END:VCARD
*** ical20 ***
no changes
*** itodo20 ***
no changes
*** text ***
no changes

New Command Line Options in 0.7 pre2

The check for local changes makes sense even without a sync, for example to figure out whether there are any local changes which would get lost during a “refresh-from-server” sync. Doing such a “refresh-from-server” once before continuing with normal “two-way” synchronization is another example for something which is now possible with new the command line options:

syncevolution [<options>] <server> [<source> ...]
syncevolution --help|-h
syncevolution --version

  --sync|-s <mode>
    Temporarily synchronize the active sources in that mode. Useful
    for a 'refresh-from-server' or 'refresh-from-client' sync which
    clears all data at one end and copies all items from the other.

    The changes made to local data since the last synchronization are
    shown without starting a new one. This can be used to see in advance
    whether the local data needs to be synchronized with the server.

    Suppresses most of the normal output during a synchronization. The
    log file still contains all the information.

    Prints usage information.

    Prints the SyncEvolution version.

Running Regularly

Like any other command line application, SyncEvolution can be run regularly for example by making it part of a cron job.

When you do that, please choose a long delay between each sync!

It is easy to generate a high load on a SyncML server even without actually exchanging data.

Not available (yet)

Due to limitations in the logging of the SyncML library, the INFO messages which are printed at the end of a sync cannot be printed to the screen at the same time as they are written into the log file. That would be more natural as it provides some feedback while the sync is still running. Even more important would be an estimate how much of the sync is already completed. The SyncML library provides some support for that, it just isn’t used in SyncEvolution yet.

{ 4 } Comments

  1. Bob | April 27, 2008 at 9:31 pm | Permalink

    Sounds great but the what is needed is a simple example of:

    a) setup evolution server with *THIS*
    b) setup iphone or sync device with *THIS*

    It seems fractured and impossible to follow the install of syncing evolution to Iphone from the info provided.

  2. Patrick Ohly | April 28, 2008 at 5:34 am | Permalink

    Bob, are you refering to 0.7 or the 0.8 alpha 1? If it is 0.7, did you see the instructions given here:

    If you find them insufficient, then please tell me why and I’ll improve the docs accordingly.

    For 0.8 there is no corresponding step-by-step list yet. Just use –configure combined with multiple –sync-property args to set the necessary values.

    Regarding the iPhone, please follow the instructions that Funambol has on their web site if you use the GUI.

  3. jacob | April 2, 2009 at 5:50 pm | Permalink

    I have two adressbooks in Evolution and Syncevolution takes the wrong one. How can I guide the program to take the good one?

  4. Patrick Ohly | April 2, 2009 at 8:52 pm | Permalink

    Jacob, set the “evolutionsource” property for the address book sync source.

    When you invoke “syncevolution” without parameters, then you’ll get a list of known address books. You can use either the name of the desired address book as value for “evolutionsource” or the URI; usually using the name is easier.

{ 1 } Trackback

  1. [...] provides the missing link between Mac OSX and SyncML. The application is  *nix style, command line based, originally for GNOME Evolution GNU/Linux and later ported to iPhone, OS X, Maemo.  Old school [...]

Post a Comment

Your email is never published nor shared. Required fields are marked *