docs/html/sync-configuration.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Style-Type" content="text/css" />
  <meta name="generator" content="pandoc" />
  <title>Configuration</title>
  <style type="text/css">code{white-space: pre;}</style>
  <link rel="stylesheet" href="davdoc.css" type="text/css" />
</head>
<body>
<div class="header">
	<a href="./index.html"><span>DavUtils documentation</span></a>
</div>
<div class="sidebar">
	<div class="nav">
		<h3>dav</h3>
			<ul>
				<li><a href="getting-started.html">Getting started</a></li>
				<li><a href="commands.html">Commands</a></li>
					<ul>
						<li><a href="list.html">list</a></li>
						<li><a href="get.html">get</a></li>
						<li><a href="put.html">put</a></li>
						<li><a href="mkdir.html">mkdir</a></li>
						<li><a href="remove.html">remove</a></li>
						<li><a href="copy.html">copy</a></li>
						<li><a href="move.html">move</a></li>
						<li><a href="export.html">export</a></li>
						<li><a href="import.html">import</a></li>
						<li><a href="get-property.html">get-property</a></li>
						<li><a href="set-property.html">set-property</a></li>
						<li><a href="remove-property.html">remove-property</a></li>
						<li><a href="lock.html">lock</a></li>
						<li><a href="unlock.html">unlock</a></li>
						<li><a href="info.html">info</a></li>
						<li><a href="date.html">date</a></li>
						<li><a href="add-repository.html">add-repository</a></li>
						<li><a href="remove-repository.html">remove-repository</a></li>
						<li><a href="list-repositories.html">list-repositories</a></li>
						<li><a href="check-config.html">check-config</a></li>
					</ul>
				<li><a href="configuration.html">Configuration</a></li>
				<li><a href="encryption.html">Encryption</a></li>
			</ul>
	</div>
	<div class="nav">
		<h3>dav-sync</h3>
			<ul>
				<li><a href="introduction.html">Introduction</a></li>
				<li><a href="sync-commands.html">Commands</a></li>
					<ul>
						<li><a href="pull.html">pull</a></li>
						<li><a href="push.html">push</a></li>
						<li><a href="archive.html">archive</a></li>
						<li><a href="resolve-conflicts.html">resolve-conflicts</a></li>
						<li><a href="delete-conflicts.html">delete-conflicts</a></li>
						<li><a href="trash-info.html">trash-info</a></li>
						<li><a href="empty-trash.html">empty-trash</a></li>
						<li><a href="add-tag.html">add-tag</a></li>
						<li><a href="remove-tag.html">remove-tag</a></li>
						<li><a href="set-tags.html">set-tags</a></li>
						<li><a href="list-tags.html">list-tags</a></li>
						<li><a href="add-directory.html">add-directory</a></li>
						<li><a href="list-directories.html">list-directories</a></li>
						<li><a href="sync-check-config.html">check-config</a></li>
						<li><a href="check-repositories.html">check-repositories</a></li>
					</ul>
				<li><a href="sync-configuration.html">Configuration</a></li>
			</ul>
	</div>
</div>

<!-- begin content -->
<div class="content">
<div id="header">
<h1 class="title">Configuration</h1>
</div>
<p>The file <code>$HOME/.dav/sync.xml</code> is used for configuring sync-directories.</p>
<p>The <em>sync.xml</em> file is an XML file with <code>&lt;configuration&gt;</code> as root element. This element can only have <code>&lt;directory&gt;</code> elements as children.</p>
<h2 id="directory">directory</h2>
<p>This element configures a sync-directory. A sync-directory must have a unique name, a (local) path, repository and a database.</p>
<p>Required elements: <code>&lt;name&gt;</code>, <code>&lt;repository&gt;</code>, <code>&lt;path&gt;</code>, <code>&lt;database&gt;</code><br />
Optional elements: <code>&lt;collection&gt;</code>, <code>&lt;trash&gt;</code>, <code>&lt;max-retry&gt;</code>, <code>&lt;backup-on-pull&gt;</code>, <code>&lt;lock-pull&gt;</code>, <code>&lt;lock-push&gt;</code>, <code>&lt;lock-timeout&gt;</code>, <code>&lt;filter&gt;</code></p>
<h3 id="name">name</h3>
<p>Unique sync-directory identifer. This identifer is used in combination with all <em>dav-sync</em> commands.</p>
<p>Type: string<br />
Example: <code>&lt;name&gt;mysyncdir&lt;/name&gt;</code></p>
<h3 id="repository">repository</h3>
<p>Name of the WebDAV-repository. A repository with the same name must be configured in [config.xml][1].</p>
<p>Type: string<br />
Example: <code>&lt;name&gt;myrepo&lt;/name&gt;</code></p>
<h3 id="path">path</h3>
<p>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 <code>$</code> followed by the variable name optionally followed by a path. For example:</p>
<pre><code>`&lt;path&gt;$HOME/Documents&lt;/path&gt;`</code></pre>
<p>The part between <code>$</code> and <code>/</code> is the environment variable name.</p>
<p>Type: string<br />
Example: <code>&lt;path&gt;/absolute/path&lt;/path&gt;</code></p>
<h3 id="database">database</h3>
<p>Path to the database file used for this sync-directory. The path must be relative to the <em>$HOME/.dav/</em> directory.</p>
<p>Type: string<br />
Example: <code>&lt;database&gt;myrepo-db.xml&lt;/database&gt;</code></p>
<h3 id="collection">collection</h3>
<p>Path of the collection relative to the repository root collection. For example if the repository url is <em>http://example.com/webdav/</em> and the collection value is <em>/myfiles/</em>, the directory is synchronized with <em>http://example.com/webdav/myfiles/</em></p>
<p>Type: string<br />
Default: /<br />
Example: <code>&lt;collection&gt;/myfiles&lt;/collection&gt;</code></p>
<h3 id="trash">trash</h3>
<p>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.</p>
<p>Type: string<br />
Example: <code>&lt;trash&gt;.trash&lt;/trash&gt;</code></p>
<h3 id="max-retry">max-retry</h3>
<p>This integer value controls how many attempts of downloading/uploading a file in case of an error are made.</p>
<p>Type: integer<br />
Default: 0<br />
Example: <code>&lt;max-retry&gt;3&lt;/max-retry&gt;</code></p>
<h3 id="backup-on-pull">backup-on-pull</h3>
<p>If this element has the value of true, the <em>pull</em> command will move old local files to the trash directory before downloading the new version from the server.</p>
<p>Type: boolean<br />
Default: false<br />
Example: <code>&lt;backup-on-pull&gt;true&lt;/backup-on-pull&gt;</code></p>
<h3 id="lock-pull">lock-pull</h3>
<p>Enables locking for the <em>pull</em> command.</p>
<p>Type: boolean<br />
Default: false<br />
Example: <code>&lt;lock-pull&gt;true&lt;/lock-pull&gt;</code></p>
<h3 id="lock-push">lock-push</h3>
<p>Enables locking for the <em>push</em> command.</p>
<p>Type: boolean<br />
Default: false<br />
Example: <code>&lt;lock-push&gt;true&lt;/lock-push&gt;</code></p>
<h3 id="lock-timeout">lock-timeout</h3>
<p>Specifies the lock timeout in seconds. If the lock-timeout is 0, the client doesn't request a specific timeout and the server's default value is used. If the lock-timeout is -1, a infinite timeout is requested.</p>
<p>Type: integer<br />
Default: 0<br />
Example: <code>&lt;lock-timeout&gt;50&lt;/lock-timeout&gt;</code></p>
<h3 id="tagconfig">tagconfig</h3>
<p>Configures the local store for resource tags. If this element is specified, resource tags are stored locally.</p>
<p>Optional elements: local-store, detect-changes, xattr-name, on-conflict</p>
<h3 id="local-store">local-store</h3>
<p>Specifies the tag-store type. Currently the only available type is <code>xattr</code>.</p>
<p>The element can contain the attribute <code>format</code> with one of the following values: <code>text</code>, <code>csv</code>, <code>xml</code>, <code>macos</code>. The default value is <code>text</code>.</p>
<p>Type: tagstore type enum<br />
Default: xattr<br />
Example: <code>&lt;local-store format=&quot;csv&quot;&gt;xattr&lt;/local-store&gt;</code></p>
<h3 id="xattr-name">xattr-name</h3>
<p>Specifies the name of the extended attribute for storing tags. The default value is <code>tags</code>, unless you are using the <code>macos</code> format, where the default value is <code>com.apple.metadata:_kMDItemUserTags</code>.</p>
<p>Type: string<br />
Default: tags<br />
Example: `<xattr-name>file_tags</xattr-name></p>
<h3 id="detect-changes">detect-changes</h3>
<p>Controls, if tag changes should be detected.</p>
<p>Type: boolean<br />
Default: false<br />
Example: <code>&lt;detect-changes&gt;true&lt;/detect-changes&gt;</code></p>
<h3 id="on-conflict">on-conflict</h3>
<p>Specifies the behavior, when tag conflicts occur. Possible values are: <code>no_conflict</code>, <code>keep_local</code>, <code>keep_remote</code>, <code>merge</code></p>
<p>Type: onconflict enum<br />
Default: no_conflict<br />
Example: <code>&lt;on-conflict&gt;merge&lt;/on-conflict&gt;</code></p>
<h3 id="filter">filter</h3>
<p>With the filter element, include and exclude filters can be specified, to control which files are synchronized. The <em>pull</em>, <em>push</em> and <em>archive</em> 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.</p>
<p>It is also possible to filter resources by tags. Tags can dynamically be applied to individual files. The tag filter elements contains a tag filter expression. Only files that match the filter expression are synchronized.</p>
<p>Note: The file path is relative to the directory path (and WebDAV collection) but always starts with an path separator.</p>
<p>Optional elements: <code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code>, <code>&lt;tags&gt;</code></p>
<h3 id="include">include</h3>
<p>Controls which files will be included by <em>pull</em> and <em>push</em>. If an include filter is specified, only files matching this filter are included.</p>
<p>Type: regex string<br />
Default: .*<br />
Example:</p>
<pre><code>&lt;filter&gt;
    &lt;include&gt;\.pdf$&lt;/include&gt;
&lt;/filter&gt;</code></pre>
<h3 id="exclude">exclude</h3>
<p>Controls which files will be excluded by <em>pull</em> and <em>push</em>.</p>
<p>Type: regex string<br />
Example:</p>
<pre><code>&lt;filter&gt;
    &lt;exclude&gt;^/secretdir&lt;/exclude&gt;
    &lt;exclude&gt;\.DS_Store$&lt;/exclude&gt;
&lt;/filter&gt;</code></pre>
<h3 id="tags">tags</h3>
<p>Filters resources by tags. Only resources, that are not a collection, are effected. If tags are not stored locally, the pull command still uses the filter.</p>
<p>Filter Syntax:</p>
<pre><code>filter ::= operator? , (tag_list | (&quot;(&quot; , filter , &quot;)&quot;)+)
tag_list ::= tag , (&quot;,&quot; tag)*
operator ::= &quot;&amp;&quot; | &quot;|&quot; | &quot;1&quot; | &quot;0&quot;</code></pre>
<p>Type: tag filter expression<br />
Example:</p>
<pre><code>&lt;filter&gt;
    &lt;!-- sync only resources that have one of this tags --&gt;
    &lt;tags&gt;| (tag1, tag2, tag3)&lt;/tags&gt;
&lt;/filter&gt;</code></pre>
</div>
<!-- end content -->
</body>
</html>