Imported Upstream version 1.1
[platform/upstream/syncevolution.git] / README
1 ===============
2  SyncEvolution
3 ===============
4
5 ------------------------------------------------
6 synchronize personal information management data
7 ------------------------------------------------
8
9 :Manual section: 1
10 :Version: 1.1
11 :Date: 2010-10-26
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