~ubuntu-branches/ubuntu/natty/syncevolution/natty

« back to all changes in this revision

Viewing changes to README.rst

  • Committer: Bazaar Package Importer
  • Author(s): Laurent Bigonville
  • Date: 2011-01-23 17:45:12 UTC
  • mfrom: (4.1.2 sid)
  • Revision ID: james.westby@ubuntu.com-20110123174512-jgvbvbcberl5m4ql
Tags: 1.1+ds1-5ubuntu1
* Merge from debian unstable. (LP: #697087)
* Drop debian/patches/01_fix_duplicated_symbols.patch: Fixed upstream
* debian/patches/0004-fix-linking-as-needed.patch: Fix linking with
  --as-needed, not sure it was the best way though.

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
===============
 
2
 SyncEvolution
 
3
===============
 
4
 
 
5
------------------------------------------------
 
6
synchronize personal information management data
 
7
------------------------------------------------
 
8
 
 
9
:Manual section: 1
 
10
:Version: 1.0
 
11
:Date: Apr 28, 2010
 
12
 
 
13
SYNOPSIS
 
14
========
 
15
 
 
16
Show available sources:
 
17
  syncevolution
 
18
 
 
19
Show information about configuration(s):
 
20
  syncevolution --print-servers|--print-configs|--print-peers
 
21
 
 
22
Show information about a specific configuration:
 
23
  syncevolution --print-config [--quiet] <config> [main|<source> ...]
 
24
 
 
25
List sessions:
 
26
  syncevolution --print-sessions [--quiet] <config>
 
27
 
 
28
Show information about SyncEvolution:
 
29
  syncevolution --help|-h|--version
 
30
 
 
31
Run a synchronization as configured:
 
32
  syncevolution <config> [<source> ...]
 
33
 
 
34
Run a synchronization with properties changed just for this run:
 
35
  syncevolution --run <options for run> <config> [<source> ...]
 
36
 
 
37
Restore data from the automatic backups:
 
38
  syncevolution --restore <session directory> --before|--after [--dry-run] <config> <source> ...
 
39
 
 
40
Modify a configuration:
 
41
  syncevolution --configure <options> <config> [<source> ...]
 
42
  syncevolution --remove|--migrate <options> <config>
 
43
 
 
44
List items:
 
45
  syncevolution --print-items <config> <source>
 
46
 
 
47
Export item(s):
 
48
  syncevolution [--delimiter <string>] --export <dir>|<file>|- <config> <source> [<luid> ...]
 
49
 
 
50
Add item(s):
 
51
  syncevolution [--delimiter <string>|none] --import <dir>|<file>|- <config> <source>
 
52
 
 
53
Update item(s)
 
54
  syncevolution --update <dir> <config> <source>
 
55
  syncevolution [--delimiter <string>|none] --update <file>|- <config> <source> <luid> ...
 
56
 
 
57
Remove item(s):
 
58
  syncevolution --delete-items <config> <source> (<luid> ... | \*)
 
59
 
 
60
DESCRIPTION
 
61
===========
 
62
 
 
63
This text explains the usage of the SyncEvolution command line.
 
64
 
 
65
SyncEvolution synchronizes personal information management (PIM) data
 
66
such as contacts, appointments, tasks and memos using the Synthesis
 
67
sync engine, which provides support for the SyncML synchronization
 
68
protocol.
 
69
 
 
70
SyncEvolution synchronizes with SyncML servers over HTTP and with
 
71
SyncML capable phones locally over Bluetooth (new in 1.0). Plugins
 
72
provide access to the data which is to be synchronized. Binaries are
 
73
available for Linux desktops (synchronizing data in GNOME Evolution,
 
74
with KDE supported indirectly already and Akonadi support in
 
75
development), for MeeGo (formerly Moblin) and for Maemo 5/Nokia
 
76
N900. The source code can be compiled for Unix-like systems and
 
77
provides a framework to build custom SyncML clients or servers.
 
78
 
 
79
USAGE
 
80
=====
 
81
 
 
82
The <config> and the <source> strings are used to find the
 
83
configuration files which determine how synchronization is going to
 
84
proceed. Each source corresponds to one local address book, calendar,
 
85
task list or set of memos and the corresponding database on the
 
86
peer. Depending on which parameters are given, different operations
 
87
are executed.
 
88
 
 
89
Starting with SyncEvolution 1.0, <config> strings can have different
 
90
meanings. Typically, a simple string like `scheduleworld` refers to
 
91
the configuration for that peer, as it did in previous releases. A
 
92
peer is either a SyncML server (the traditional usage of
 
93
SyncEvolution) or a client (the new feature in 1.0).
 
94
 
 
95
Each peer configuration exists inside a specific context, typically
 
96
the `@default` context. All peers in the same context share some parts
 
97
of their configuration, for example, which local databases are to be
 
98
synchronized.  In that sense, a configuration context can be seen as a
 
99
set of local databases plus the peer configurations that are
 
100
synchronized against those databases.
 
101
 
 
102
The peer-independent properties of a source can be configured by
 
103
giving the context name as <config> parameter ("@default
 
104
addressbook"). Operations manipulating the local data also accept
 
105
the context name.
 
106
 
 
107
When different peers are meant to synchronize different local
 
108
databases, then different contexts have to be used when setting up the
 
109
peers by appending a context name after the `at` sign, as in
 
110
`scheduleworld2@other-context`. Later on, if `scheduleworld2` is
 
111
unique, the `@other-context` suffix becomes optional.
 
112
 
 
113
Sometimes it is also useful to change configuration options of a
 
114
context, without modifying a specific peer. This can be done by using
 
115
`@default` (or some other context name) without anything before the
 
116
`at` sign. The empty string "" is the same as `@default`. ::
 
117
 
 
118
   syncevolution
 
119
 
 
120
If no arguments are given, then SyncEvolution will list all available
 
121
data sources regardless whether there is a configuration file for them
 
122
or not. The output includes the identifiers which can then be used to
 
123
select those sources in a configuration file. For each source one can
 
124
set a different synchronization mode in its configuration file. ::
 
125
 
 
126
   syncevolution <config>
 
127
 
 
128
Without the optional list of sources, all sources which are enabled in
 
129
their configuration file are synchronized. ::
 
130
 
 
131
   syncevolution <config> <source> ...
 
132
 
 
133
Otherwise only the ones mentioned on the command line are active. It
 
134
is possible to configure sources without activating their
 
135
synchronization: if the synchronization mode of a source is set to
 
136
`disabled`, the source will be ignored. Explicitly listing such a
 
137
source will synchronize it in `two-way` mode once.
 
138
 
 
139
In SyncEvolution's predefined configuration templates, the following
 
140
names for sources are used. Different names can be chosen for sources
 
141
that are defined manually. ::
 
142
 
 
143
 * addressbook: a list of contacts
 
144
 * calendar: calendar *events*
 
145
 * memo: plain text notes
 
146
 * todo: task list
 
147
 * calendar+todo: a virtual source combining one local "calendar" and
 
148
   one "todo" source (required for synchronizing with some phones)
 
149
 
 
150
Progress and error messages are written into a log file that is
 
151
preserved for each synchronization run. Details about that is found in
 
152
the `Automatic Backups and Logging` section below. All errors and
 
153
warnings are printed directly to the console in addition to writing
 
154
them into the log file. Before quitting SyncEvolution will print a
 
155
summary of how the local data was modified.  This is done with the
 
156
`synccompare` utility script described in the `Exchanging Data`
 
157
section.
 
158
 
 
159
When the `logdir` option is enabled (since v0.9 done by default for
 
160
new configurations), then the same comparison is also done before the
 
161
synchronization starts.
 
162
 
 
163
In case of a severe error the synchronization run is aborted
 
164
prematurely and SyncEvolution will return a non-zero value. Recovery
 
165
from failed synchronization is done by forcing a full synchronization
 
166
during the next run, i.e. by sending all items and letting the SyncML
 
167
server compare against the ones it already knows. This is avoided
 
168
whenever possible because matching items during a slow synchronization
 
169
can lead to duplicate entries.
 
170
 
 
171
After a successful synchronization the server's configuration file is
 
172
updated so that the next run can be done incrementally.  If the
 
173
configuration file has to be recreated e.g. because it was lost, the
 
174
next run recovers from that by doing a full synchronization. The risk
 
175
associated with this is that the server might not recognize items that
 
176
it already has stored previously which then would lead to duplication
 
177
of items. ::
 
178
 
 
179
   syncevolution --configure <options for configuration> <config> [<source> ...]
 
180
 
 
181
Options in the configuration can be modified via the command
 
182
line. Source properties are changed for all sources unless sources are
 
183
listed explicitly.  Some source properties have to be different for
 
184
each source, in which case syncevolution must be called multiple times
 
185
with one source listed in each invocation. ::
 
186
 
 
187
   syncevolution --remove <config>
 
188
 
 
189
Deletes the configuration. If the <config> refers to a specific
 
190
peer, only that peer's configuration is removed. If it refers to
 
191
a context, that context and all peers inside it are removed.
 
192
 
 
193
Note that there is no confirmation question. Neither local data
 
194
referenced by the configuration nor the content of log dirs are
 
195
deleted. ::
 
196
 
 
197
   syncevolution --run <options for run> <config> [<source> ...]
 
198
 
 
199
Options can also be overridden for just the current run, without
 
200
changing the configuration. In order to prevent accidentally running a
 
201
sync session when a configuration change was intended, either
 
202
--configure or --run must be given explicitly if options are specified
 
203
on the command line. ::
 
204
 
 
205
   syncevolution --status <config> [<source> ...]
 
206
 
 
207
Prints what changes were made locally since the last synchronization.
 
208
Depends on access to database dumps from the last run, so using the
 
209
`logdir` option is recommended. ::
 
210
 
 
211
   syncevolution --print-servers|--print-configs|--print-peers
 
212
   syncevolution --print-config [--quiet] <config> [main|<source> ...]
 
213
   syncevolution --print-sessions [--quiet] <config>
 
214
 
 
215
These commands print information about existing configurations. When
 
216
printing a configuration a short version without comments can be
 
217
selected with --quiet. When sources are listed, only their
 
218
configuration is shown. `Main` instead or in combination with sources
 
219
lists only the main peer configuration. ::
 
220
 
 
221
   syncevolution --restore <session directory> --before|--after
 
222
                 [--dry-run] <config> <source> ...
 
223
 
 
224
This restores local data from the backups made before or after a
 
225
synchronization session. The --print-sessions command can be used to
 
226
find these backups. The source(s) have to be listed explicitly. There
 
227
is intentionally no default, because as with --remove there is no
 
228
confirmation question. With --dry-run, the restore is only simulated.
 
229
 
 
230
The session directory has to be specified explicitly with its path
 
231
name (absolute or relative to current directory). It does not have to
 
232
be one of the currently active log directories, as long as it contains
 
233
the right database dumps for the selected sources.
 
234
 
 
235
A restore tries to minimize the number of item changes (see section
 
236
`Item Changes and Data Changes`_). This means that items that are
 
237
identical before and after the change will not be transmitted anew to
 
238
the server during the next synchronization. If the server somehow
 
239
needs to get a clean copy of all items on the client then, use "--sync
 
240
refresh-from-client" in the next run. ::
 
241
 
 
242
  syncevolution --print-items <config> <source>
 
243
  syncevolution [--delimiter <string>] --export <dir>|<file>|- <config> <source> [<luid> ...]
 
244
  syncevolution [--delimiter <string>|none] --import <dir>|<file>|- <config> <source>
 
245
  syncevolution --update <dir> <config> <source>
 
246
  syncevolution [--delimiter <string>|none] --update <file>|- <config> <source> <luid> ...
 
247
  syncevolution --delete-items <config> <source> (<luid> ... | *)
 
248
 
 
249
Restore depends on the specific format of the automatic backups
 
250
created by SyncEvolution. Arbitrary access to item data is provided
 
251
with additional options. <luid> here is the unique local identifier
 
252
assigned to each item in the source, transformed so that it contains
 
253
only alphanumeric characters, dash and underscore. A star * in
 
254
--delete-items selects all items for deletion.
 
255
 
 
256
<config> and <source> must be given, but they do not have to refer to
 
257
existing configurations. In that case, the desired backend and must be
 
258
give via "--source-property type=<backend>", like this::
 
259
 
 
260
  syncevolution --print-items --source-property type=evolution-contacts dummy-config dummy-source
 
261
 
 
262
The desired backend database can be chosen via "--source-property
 
263
evolutionsource".
 
264
 
 
265
OPTIONS
 
266
=======
 
267
 
 
268
Here is a full description of all <options> that can be put in front
 
269
of the server name. Whenever an option accepts multiple values, a
 
270
question mark can be used to get the corresponding help text and/or
 
271
a list of valid values.
 
272
 
 
273
--sync|-s <mode>|?
 
274
  Temporarily synchronize the active sources in that mode. Useful
 
275
  for a `refresh-from-server` or `refresh-from-client` sync which
 
276
  clears all data at one end and copies all items from the other.
 
277
 
 
278
--print-servers|--print-configs|--print-peers
 
279
  Prints the names of all configured peers to stdout. There is no
 
280
  difference between these options, the are just aliases.
 
281
 
 
282
--print-servers|--print-configs|--print-peers|-p
 
283
  Prints the complete configuration for the selected <config>
 
284
  to stdout, including up-to-date comments for all properties. The
 
285
  format is the normal .ini format with source configurations in
 
286
  different sections introduced with [<source>] lines. Can be combined
 
287
  with --sync-property and --source-property to modify the configuration
 
288
  on-the-fly. When one or more sources are listed after the <config>
 
289
  name on the command line, then only the configs of those sources are
 
290
  printed. `main` selects the main configuration instead of source
 
291
  configurations. Using --quiet suppresses the comments for each property.
 
292
  When setting a --template, then the reference configuration for
 
293
  that peer is printed instead of an existing configuration.
 
294
 
 
295
\--print-sessions
 
296
  Prints information about previous synchronization sessions for the
 
297
  selected peer or context are printed. This depends on the `logdir`
 
298
  option.  The information includes the log directory name (useful for
 
299
  --restore) and the synchronization report. In combination with
 
300
  --quiet, only the paths are listed.
 
301
 
 
302
--configure|-c
 
303
  Modify the configuration files for the selected peer and/or sources.
 
304
  If no such configuration exists, then a new one is created using one
 
305
  of the template configurations (see --template option). When
 
306
  creating a new configuration and listing sources explicitly on the
 
307
  command line, only those sources will be set to active in the new
 
308
  configuration, i.e. `syncevolution -c scheduleworld addressbook`
 
309
  followed by `syncevolution scheduleworld` will only synchronize the
 
310
  address book. The other sources are created in a disabled state.
 
311
  When modifying an existing configuration and sources are specified,
 
312
  then the source properties of only those sources are modified.
 
313
 
 
314
--run|-r
 
315
  To prevent accidental sync runs when a configuration change was
 
316
  intended, but the `--configure` option was not used, `--run` must be
 
317
  specified explicitly when sync or source properties are selected
 
318
  on the command line and they are meant to be used during a sync
 
319
  session triggered by the invocation.
 
320
 
 
321
\--migrate
 
322
  In older SyncEvolution releases a different layout of configuration files
 
323
  was used. Using --migrate will automatically migrate to the new
 
324
  layout and rename the <config> into <config>.old to prevent accidental use
 
325
  of the old configuration. WARNING: old SyncEvolution releases cannot
 
326
  use the new configuration!
 
327
 
 
328
  The switch can also be used to migrate a configuration in the current
 
329
  configuration directory: this preserves all property values, discards
 
330
  obsolete properties and sets all comments exactly as if the configuration
 
331
  had been created from scratch. WARNING: custom comments in the
 
332
  configuration are not preserved.
 
333
 
 
334
  --migrate implies --configure and can be combined with modifying
 
335
  properties.
 
336
 
 
337
\--print-items
 
338
  Shows all existing items using one line per item using
 
339
  the format "<luid>[: <short description>]". Whether the description
 
340
  is available depends on the backend and the kind of data that it
 
341
  stores.
 
342
 
 
343
\--export
 
344
  Writes all items in the source or all items whose <luid> is
 
345
  given into a directory if the --export parameter exists and is a
 
346
  directory. The <luid> of each item is used as file name. Otherwise it
 
347
  creates a new file under that name and writes the selected items
 
348
  separated by the chosen delimiter string. stdout can be selected with
 
349
  a dash.
 
350
 
 
351
  The default delimiter (two line breaks) matches a blank line. As a special
 
352
  case, it also matches a blank line with DOS line ending (line break,
 
353
  carriage return, line break). This works for vCard 3.0 and iCalendar 2.0,
 
354
  which never contain blank lines.
 
355
 
 
356
  When exporting, the default delimiter will always insert two line
 
357
  breaks regardless whether the items contain DOS line ends. As a
 
358
  special case, the initial newline of a delimiter is skipped if the
 
359
  item already ends in a newline.
 
360
 
 
361
\--import
 
362
  Adds all items found in the directory or input file to the
 
363
  source.  When reading from a directory, each file is treated as one
 
364
  item. Otherwise the input is split at the chosen delimiter. "none" as
 
365
  delimiter disables splitting of the input.
 
366
 
 
367
\--update
 
368
  Overwrites the content of existing items. When updating from a
 
369
  directory, the name of each file is taken as its luid. When updating
 
370
  from file or stdin, the number of luids given on the command line
 
371
  must match with the number of items in the input.
 
372
 
 
373
\--delete-items
 
374
  Removes the specified items from the source. Most backends print
 
375
  some progress information about this, but besides that, no further
 
376
  output is produced. Trying to remove an item which does not exist
 
377
  typically leads to an ERROR message, but is not reflected in a
 
378
  non-zero result of the command line invocation itself because the
 
379
  situation is not reported as an error by backends (removal of
 
380
  non-existent items is not an error in SyncML). Use a star \* instead
 
381
  or in addition to listing individual luids to delete all items.
 
382
 
 
383
--sync-property|-y <property>=<value>|<property>=?|?
 
384
  Overrides a source-independent configuration property for the
 
385
  current synchronization run or permanently when --configure is used
 
386
  to update the configuration. Can be used multiple times.  Specifying
 
387
  an unused property will trigger an error message.
 
388
 
 
389
  When using the configuration layout introduced with 1.0, some of the
 
390
  sync properties are shared between peers, for example the directory
 
391
  where sessions are logged. Permanently changing such a shared
 
392
  property for one peer will automatically update the property for all
 
393
  other peers in the same context because the property is stored in a
 
394
  shared config file. When printing a config in verbose mode, a summary
 
395
  comment shows which properties are shared in which way.
 
396
 
 
397
--source-property|-z <property>=<value>|<property>=?|?
 
398
  Same as --sync-property, but applies to the configuration of all active
 
399
  sources. `--sync <mode>` is a shortcut for `--source-property sync=<mode>`.
 
400
  
 
401
  When combined with `--configure`, the configuration of all sources
 
402
  is modified. The value is applied to all sources unless sources are
 
403
  listed explicitly on the command line. So if you want to change a
 
404
  source property of just one specific sync source, then use
 
405
  `--configure --source-property ... <server> <source>`.
 
406
  
 
407
  As with sync properties, some properties are shared between peers,
 
408
  in particular the selection of which local data to synchronize.
 
409
 
 
410
--template|-l <peer name>|default|?<device>
 
411
  Can be used to select from one of the built-in default configurations
 
412
  for known SyncML peers. Defaults to the <config> name, so --template
 
413
  only has to be specified when creating multiple different configurations
 
414
  for the same peer, or when using a template that is named differently
 
415
  than the peer. `default` is an alias for `scheduleworld` and can be
 
416
  used as the starting point for servers which do not have a built-in
 
417
  template.
 
418
 
 
419
  A pseudo-random device ID is generated automatically. Therefore setting
 
420
  the `deviceId` sync property is only necessary when manually recreating a
 
421
  configuration or when a more descriptive name is desired.
 
422
 
 
423
  The available templates for different known SyncML servers are listed when
 
424
  using a single question mark instead of template name. When using the
 
425
  `?<device>` format, a fuzzy search for a template that might be
 
426
  suitable for talking to such a device is done. The matching works best
 
427
  when using `<device> = <Manufacturer> <Model>`. If you don't know the
 
428
  manufacturer, you can just keep it as empty. The output in this mode
 
429
  gives the template name followed by a short description and a rating how well
 
430
  the template matches the device (100% is best).
 
431
 
 
432
--status|-t
 
433
  The changes made to local data since the last synchronization are
 
434
  shown without starting a new one. This can be used to see in advance
 
435
  whether the local data needs to be synchronized with the server.
 
436
 
 
437
--quiet|-q
 
438
  Suppresses most of the normal output during a synchronization. The
 
439
  log file still contains all the information.
 
440
 
 
441
--keyring|-k
 
442
  Save or retrieve passwords from the GNOME keyring when modifying the
 
443
  configuration or running a synchronization. Note that using this option
 
444
  applies to *all* passwords in a configuration, so setting a single
 
445
  password as follows moves the other passwords into the keyring, if
 
446
  they were not stored there already::
 
447
 
 
448
     --keyring --configure --sync-property proxyPassword=foo
 
449
 
 
450
  When passwords were stored in the keyring, their value is set to a single
 
451
  hyphen ("-") in the configuration. This means that when running a
 
452
  synchronization without the --keyring argument, the password has to be
 
453
  entered interactively. The --print-config output always shows "-" instead
 
454
  of retrieving the password from the keyring.
 
455
 
 
456
--daemon[=yes/no]
 
457
  By default, the SyncEvolution command line is executed inside the
 
458
  syncevo-dbus-server process. This ensures that synchronization sessions
 
459
  started by the command line do not conflict with sessions started
 
460
  via some other means (GUI, automatically). For debugging purposes
 
461
  or very special use cases (running a local sync against a server which
 
462
  executes inside the daemon) it is possible to execute the operation
 
463
  without the daemon (--daemon=no).
 
464
 
 
465
--help|-h
 
466
  Prints usage information.
 
467
 
 
468
\--version
 
469
  Prints the SyncEvolution version.
 
470
 
 
471
EXAMPLES
 
472
========
 
473
 
 
474
List the known configuration templates::
 
475
 
 
476
   syncevolution --template ?
 
477
 
 
478
Create a new configuration, using the existing ScheduleWorld template::
 
479
 
 
480
  syncevolution --configure \
 
481
                --sync-property "username=123456" \
 
482
                --sync-property "password=!@#ABcd1234" \
 
483
                scheduleworld
 
484
 
 
485
Note that putting passwords into the command line, even for
 
486
short-lived processes as the one above, is a security risk in shared
 
487
environments, because the password is visible to everyone on the
 
488
machine. To avoid this, remove the password from the command above,
 
489
then add the password to the right config.ini file with a text editor.
 
490
This command shows the directory containing the file::
 
491
 
 
492
   syncevolution --print-configs
 
493
 
 
494
Review configuration::
 
495
 
 
496
   syncevolution --print-config scheduleworld
 
497
 
 
498
Synchronize all sources::
 
499
 
 
500
  syncevolution scheduleworld
 
501
 
 
502
Deactivate all sources::
 
503
 
 
504
  syncevolution --configure \
 
505
                --source-property sync=none \
 
506
                scheduleworld
 
507
 
 
508
Activate address book synchronization again, using the --sync shortcut::
 
509
 
 
510
  syncevolution --configure \
 
511
                --sync two-way \
 
512
                scheduleworld addressbook
 
513
 
 
514
Change the password for a configuration::
 
515
 
 
516
  syncevolution --configure \
 
517
                --sync-property password=foo \
 
518
                scheduleworld
 
519
 
 
520
Set up another configuration for under a different account, using
 
521
the same default databases as above::
 
522
 
 
523
  syncevolution --configure \
 
524
                --sync-property username=joe \
 
525
                --sync-property password=foo \
 
526
                --template scheduleworld \
 
527
                scheduleworld_joe
 
528
 
 
529
Set up another configuration using the same account, but different
 
530
local databases (can be used to simulate synchronizing between two
 
531
clients, see `Exchanging Data`_::
 
532
 
 
533
  syncevolution --configure \
 
534
                --sync-property "username=123456" \
 
535
                --sync-property "password=!@#ABcd1234" \
 
536
                --source-property sync=none \
 
537
                 scheduleworld@other
 
538
  
 
539
  syncevolution --configure \
 
540
                --source-property evolutionsource=<name of other address book> \
 
541
                @other addressbook
 
542
 
 
543
  syncevolution --configure \
 
544
                --source-property sync=two-way \
 
545
                scheduleworld@other addressbook
 
546
 
 
547
  syncevolution scheduleworld 
 
548
  syncevolution scheduleworld@other
 
549
 
 
550
Migrate a configuration from the <= 0.7 format to the current one
 
551
and/or updates the configuration so that it looks like configurations
 
552
created anew with the current syncevolution::
 
553
 
 
554
  syncevolution --migrate scheduleworld
 
555
 
 
556
 
 
557
NOTES
 
558
=====
 
559
 
 
560
Exchanging Data
 
561
---------------
 
562
 
 
563
SyncEvolution transmits address book entries as vCard 2.1 or 3.0
 
564
depending on the type chosen in the configuration. Evolution uses
 
565
3.0 internally, so SyncEvolution converts between the two formats as
 
566
needed. Calendar items and tasks can be sent and received in iCalendar
 
567
2.0 as well as vCalendar 1.0, but vCalendar 1.0 should be avoided if
 
568
possible because it cannot represent all data that Evolution stores.
 
569
 
 
570
.. note:: The Evolution backends are mentioned as examples;
 
571
   the same applies to other data sources.
 
572
 
 
573
How the server stores the items depends on its implementation and
 
574
configuration. In the default Funambol server installation, contacts
 
575
and calendar items are converted into an internal format, but at
 
576
least for contacts it preserves most of the properties used by
 
577
Evolution whereas iCalendar 2.0 items are not preserved properly 
 
578
up to and including Funambol 8.0. ScheduleWorld uses the same format
 
579
as Evolution for calendars and tasks and thus requires no conversion.
 
580
 
 
581
To check which data is preserved, one can use this procedure
 
582
(described for contacts, but works the same way for calendars and
 
583
tasks):
 
584
 
 
585
1. synchronize the address book with the server
 
586
2. create a new address book in Evolution and view it in Evolution
 
587
   once (the second step is necessary in at least Evolution 2.0.4
 
588
   to make the new address book usable in SyncEvolution)
 
589
3. add a configuration for that second address book and the
 
590
   same URI on the SyncML server, see EXAMPLES_ above
 
591
4. synchronize again, this time using the other data source
 
592
 
 
593
Now one can either compare the address books in Evolution or do that
 
594
automatically, described here for contacts:
 
595
 
 
596
- save the complete address books: mark all entries, save as vCard
 
597
- invoke `synccompare` with two file names as arguments and it will
 
598
  normalize and compare them automatically
 
599
 
 
600
Normalizing is necessary because the order of cards and their
 
601
properties as well as other minor formatting aspects may be
 
602
different. The output comes from a side-by-side comparison, but
 
603
is augmented by the script so that the context of each change
 
604
is always the complete item that was modified. Lines or items
 
605
following a ">" on the right side were added, those on the
 
606
left side followed by a "<" were removed, and those with
 
607
a "|" between text on the left and right side were modified.
 
608
 
 
609
The automatic unit testing (see HACKING) contains a `testItems`
 
610
test which verifies the copying of special entries using the
 
611
same method.
 
612
 
 
613
Modifying one of the address books or even both at the same time and
 
614
then synchronizing back and forth can be used to verify that
 
615
SyncEvolution works as expected. If you do not trust SyncEvolution or
 
616
the server, then it is prudent to run these checks with a copy of the
 
617
original address book. Make a backup of the .evolution/addressbook
 
618
directory.
 
619
 
 
620
Item Changes and Data Changes
 
621
-----------------------------
 
622
 
 
623
SyncML clients and servers consider each entry in a database as one
 
624
item. Items can be added, removed or updated. This is the item change
 
625
information that client and server exchange during a normal,
 
626
incremental synchronization.
 
627
 
 
628
If an item is saved, removed locally, and reimported, then this is
 
629
usually reported to a peer as "one item removed, one added" because
 
630
the information available to SyncEvolution is not sufficient to
 
631
determine that this is in fact the same item. One exception are
 
632
iCalendar 2.0 items with their globally unique ID: the modification
 
633
above will be reported to the server as "one item updated".
 
634
 
 
635
That is better, but still not quite correct because the content of the
 
636
item has not changed, only the meta information about it which is used
 
637
to detect changes. This cannot be avoided without creating additional
 
638
overhead for normal synchronizations.
 
639
 
 
640
SyncEvolution reports *item changes* (the number of added, removed and
 
641
updated items) as well as *data changes*. These data changes are
 
642
calculated by comparing database dumps using the `synccompare` tool.
 
643
Because this data comparison ignores information about which data
 
644
belongs to which item, it is able to detect that re-adding an item
 
645
that was removed earlier does not change the data, in contrast to the
 
646
item changes. On the other hand, removing one item and adding a
 
647
different one may look like updating just one item.
 
648
 
 
649
Automatic Backups and Logging
 
650
-----------------------------
 
651
 
 
652
To support recovery from a synchronization which damaged the
 
653
local data or modified it in an unexpected way, SyncEvolution
 
654
can create the following files during a synchronization:
 
655
 
 
656
- a dump of the data in a format which can be restored by
 
657
  SyncEvolution, usually a single file per item containing
 
658
  in a standard text format (VCARD/VCALENDAR)
 
659
- a full log file with debug information
 
660
- another dump of the data after the synchronization for
 
661
  automatic comparison of the before/after state with
 
662
  `synccompare`
 
663
 
 
664
If the server configuration option "logdir" is set, then
 
665
a new directory will be created for each synchronization
 
666
in that directory, using the format `<peer>-<yyyy>-<mm>-<dd>-<hh>-<mm>[-<seq>]`
 
667
with the various fields filled in with the time when the
 
668
synchronization started. The sequence suffix will only be
 
669
used when necessary to make the name unique. By default,
 
670
SyncEvolution will never delete any data in that log
 
671
directory unless explicitly asked to keep only a limited
 
672
number of previous log directories.
 
673
 
 
674
This is done by setting the "maxlogdirs" limit to something
 
675
different than the empty string and 0. If a limit is set,
 
676
then SyncEvolution will only keep that many log directories
 
677
and start removing the "less interesting" ones when it reaches
 
678
the limit. Less interesting are those where no data changed
 
679
and no error occurred.
 
680
 
 
681
To avoid writing any additional log file or database dumps during
 
682
a synchronization, the "logdir" can be set to "none". To reduce
 
683
the verbosity of the log, set "loglevel". If not set or 0, then
 
684
the verbosity is set to 3 = DEBUG when writing to a log file and
 
685
2 = INFO when writing to the console directly. To debug issues
 
686
involving data conversion, level 4 also dumps the content of
 
687
items into the log.
 
688
 
 
689
ENVIRONMENT
 
690
===========
 
691
 
 
692
The following environment variables control where SyncEvolution finds
 
693
files and other aspects of its operations.
 
694
 
 
695
http_proxy
 
696
   Overrides the proxy settings temporarily. Setting it to an empty value
 
697
   disables the normal proxy settings.
 
698
 
 
699
HOME/XDG_CACHE_HOME/XDG_CONFIG_HOME
 
700
   SyncEvolution follows the XDG_ desktop standard for its files. By default,
 
701
   `$HOME/.config/syncevolution` is the location for configuration files.
 
702
   `$HOME/.cache/syncevolution` holds session directories with log files and
 
703
   database dumps.
 
704
 
 
705
.. _XDG: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
 
706
 
 
707
SYNCEVOLUTION_DEBUG
 
708
   Setting this to any value disables the filtering of stdout and stderr
 
709
   that SyncEvolution employs to keep noise from system libraries out
 
710
   of the command line output.
 
711
 
 
712
SYNCEVOLUTION_GNUTLS_DEBUG
 
713
   Enables additional debugging output when using the libsoup HTTP transport library.
 
714
 
 
715
SYNCEVOLUTION_BACKEND_DIR
 
716
   Overrides the default path to plugins, normally `/usr/lib/syncevolution/backends`.
 
717
 
 
718
SYNCEVOLUTION_TEMPLATE_DIR
 
719
   Overrides the default path to template files, normally
 
720
   `/usr/share/syncevolution/templates`.
 
721
 
 
722
SYNCEVOLUTION_XML_CONFIG_DIR
 
723
   Overrides the default path to the Synthesis XML configuration files, normally
 
724
   `/usr/share/syncevolution/xml`. These files are merged into one configuration
 
725
   each time the Synthesis SyncML engine is started as part of a sync session.
 
726
 
 
727
   Note that in addition to this directory, SyncEvolution also always
 
728
   searches for configuration files inside `$HOME/.config/syncevolution-xml`.
 
729
   Files with the same relative path and name as in `/usr/share/syncevolution/xml`
 
730
   override those files, others extend the final configuration.
 
731
 
 
732
BUGS
 
733
====
 
734
 
 
735
See `known issues`_ and the `support`_ web page for more information. 
 
736
 
 
737
.. _known issues: http://syncevolution.org/documentation/known-issues
 
738
.. _support: http://syncevolution.org/support
 
739
 
 
740
SEE ALSO
 
741
========
 
742
 
 
743
http://syncevolution.org
 
744
 
 
745
AUTHORS
 
746
=======
 
747
 
 
748
:Main developer:
 
749
     Patrick Ohly <patrick.ohly@intel.com>, http://www.estamos.de
 
750
:Contributors:
 
751
     http://syncevolution.org/about/contributors
 
752
:To contact the project publicly (preferred):
 
753
     syncevolution@syncevolution.org
 
754
:Intel-internal team mailing list (confidential):
 
755
     syncevolution@lists.intel.com