Mercurial > hg > dav / file diff

--- a/docs/src/sync-configuration.md	Sat Aug 05 13:35:27 2017 +0200
+++ b/docs/src/sync-configuration.md	Sun Aug 06 14:41:20 2017 +0200
@@ -0,0 +1,127 @@
+---
+title: 'Configuration'
+---
+
+The file `$HOME/.dav/sync.xml` is used for configuring sync-directories.
+
+The *sync.xml* file is an XML file with `<configuration>` as root element. This element can only have `<directory>` elements as children.
+
+## directory
+
+This element configures a sync-directory. A sync-directory must have a unique name, a (local) path, repository and a database.
+
+Required elements: `<name>`, `<repository>`, `<path>`, `<database>` \
+Optional elements: `<collection>`, `<trash>`, `<max-retry>`, `<backup-on-pull>`, `<lock-pull>`, `<lock-push>`, `<filter>`
+
+### name
+
+Unique sync-directory identifer. This identifer is used in combination with all *dav-sync* commands.
+
+Type: string \
+Example: `<name>mysyncdir</name>`
+
+### repository
+
+Name of the WebDAV-repository. A repository with the same name must be configured in [config.xml][1].
+
+Type: string \
+Example: `<name>myrepo</name>`
+
+### path
+
+The path of the local directory that should be synchronized. The path must be an absolute path or start with an environment variable. A path with an environment variable must start with an `$` followed by the variable name optionally followed by a path. For example:
+
+	`<path>$HOME/Documents</path>`
+
+The part between `$` and `/` is the environment variable name.
+
+Type: string \
+Example: `<path>/absolute/path</path>`
+
+### database
+
+Path to the database file used for this sync-directory. The path must be relative to the *$HOME/.dav/* directory.
+
+Type: string \
+Example: `<database>myrepo-db.xml</database>`
+
+### collection
+
+Path of the collection relative to the repository root collection. For example if the repository url is *http://example.com/webdav/* and the collection value is */myfiles/*, the directory is synchronized with *http://example.com/webdav/myfiles/*
+
+Type: string \
+Default: / \
+Example: `<collection>/myfiles</collection>`
+
+### trash
+
+Path to the trash directory for this sync-directory. Files that should be deleted will be moved to this directory. The value must be an absolute path or relative to the sync-directory path.
+
+Type: string \
+Example: `<trash>.trash</trash>`
+
+### max-retry
+
+This integer value controls how many attempts of downloading/uploading a file in case of an error are made.
+
+Type: integer \
+Default: 0 \
+Example: `<max-retry>3</max-retry>`
+
+### backup-on-pull
+
+If this element has the value of true, the *pull* command will move old local files to the trash directory before downloading the new version from the server. 
+
+Type: boolean \
+Default: false \
+Example: `<backup-on-pull>true</backup-on-pull>`
+
+### lock-pull
+
+Enables locking for the *pull* command.
+
+Type: boolean \
+Default: false \
+Example: `<lock-pull>true</lock-pull>`
+
+### lock-push
+
+Enables locking for the *push* command.
+
+Type: boolean \
+Default: false \
+Example: `<lock-push>true</lock-push>`
+
+### filter
+
+With the filter element, include and exclude filters can be specified, to control which files are synchronized. The *pull* and *push* command apply these filters to file paths. At first it is checked if a file is matching any include filter. If so only files matching not an exclude filter are further processed.
+
+Note: The file path is relative to the directory path (and WebDAV collection) but always starts with an path separator.
+
+Optional elements: `<include>`, `<exclude>`
+
+### include
+
+Controls which files will be included by *pull* and *push*. If an include filter is specified, only files matching this filter are included.
+
+Type: regex string \
+Default: .* \
+Example: 
+
+	<filter>
+		<include>\.pdf$</include>
+	</filter>
+
+### exclude
+
+Controls which files will be excluded by *pull* and *push*.
+
+Type: regex string \
+Example:
+
+	<filter>
+		<exclude>^/secretdir</exclude>
+		<exclude>\.DS_Store$</exclude>
+	</filter>
+
+