docs/src/introduction.md

---
title: 'Introduction to dav-sync'
---

The dav-sync program can synchronize a local directory with a WebDAV collection.

First Steps
-----------

To use dav-sync it is required to configure a repository in [config.xml][1] and the directory in [sync.xml][2].

Create a repository with [dav add-repository][3]. Unlike *dav*, *dav-sync* is not interactive and never shows an authentication prompt. Therefore the user and password **must** be specified if the server requires authentication.

	$ dav add-repository
	Each repository must have an unique name.
	name: myfirstrepo

	Specify the repository base url.
	url: http://example.com/webdav/

	User for HTTP authentication.
	user (optional): myuser
	password (optional): 

After the repository is created, configure a sync-directory with [dav-sync add-directory][4].

	$ dav-sync add-directory
	Each sync directory must have an unique name.
	name: mysyncdir
	Enter local directory path.
	path: $HOME/important_files
	Specify webdav repository.
	0) myfirstrepo
	1) anotherrepo
	repository: 0
	Enter collection relative to the repository base url.
	collection (default: /): /important_files

The specified name is just an identifier and will be used with other dav-sync commands like *pull* and *push*.

After the configuration is created, you can synchronize your files. There are two commands for it: *pull* and *push*.

With *pull* you can apply all changes on the server to your local directory. The command scans the server and detects modified files and which files are deleted. All modified files will be downloadet and all deleted files will be locally removed (or moved to the trash directory). The first time you will run *pull* for a directory this will just download all files from the WebDAV collection.

You can run the *pull* command with:

	dav-sync pull mysyncdir

The *push* command scans your local directory for changes, uploads all modified files and removes all locally deleted files from the server.

	dav-sync push mysyncdir

[1]: ./configuration.html
[2]: ./sync-configuration.html
[3]: ./add-repository.html
[4]: ./add-directory.html


Database
--------

Every sync-directory has a database xml file that contains the etag and last modified date of each file. The etag is used to detect changes on the server and the last modified date is used to detect local changes. The database file is usually located in *$HOME/.dav/* and if you want to reset a sync-directory, you can delete the database. After that, *pull*/*push* (with disabled conflict detection) will download/upload all files.


Conflict detection
------------------

The *pull* and *push* commands detect if a file has changed remotely and locally. This is a conflict that must be resolved manually.

When *pull* detects a conflict it renames the local file to *orig-\$number.\$name* where *\$number* is an integer, usually 0 if no other conflict file with the name exists and *\$name* is the file's name. After the file is renamed the new file from the server is downloadet. The user should merge the files manually then or just delete one or keep both. After that run *resolve-conflicts* to remove all conflict entries from the database otherwise *push* will ignore any file in a conflict state. There is also the *delete-conflicts* command that deletes all conflict files.

When *push* detects that a file is modified locally and on the server, it just skips this file. Run the *pull* command to get the new file from the server and resolve the conflict like described above.


Trash
-----

For high data safety, a trash directory can be configured. If this is done, dav-sync will not delete files, but move them to the trash directory. Also the pull command can move files to the trash directory before overwriting them. 

To enable the trash, add the `<trash>` element to the directory config. The trash path can be absolute or relative to the sync-directory path.

	<directory>
		<name>mydir</name>
		<path>$HOME/myfiles</path>
		<repository>myrepo</repository>
		<database>mydir-db.xml</database>
		
		<!-- enable trash dir -->
		<trash>.trash</trash>
	</directory>

Files inside the trash directory will not be synchronized with the server.

Add the `<backup-on-pull>` element if you want to backup files to the trash directory before they are overwritten.

	<directory>
		...
		
		<backup-on-pull>true</backup-on-pull>
	<directory>
	

Locking
-------

It is highly recommended to lock the repository if it is expected that multiple users want to access and modify the repository simultaneously. Locking can be enabled with the `-l` option when using the *pull* or *push* command, or it can be permanently enabled in *sync.xml* for a directory with the `<lock-pull>` and `<lock-push>` elements.

	<directory>
		...
		<lock-pull>true</lock-pull>
		<lock-push>true</lock-push>
	</directory>

See [Configuration][5] for details.

[5]: ./configuration.html

Encryption
----------

The *dav-sync* program uses the same repository settings as *dav*. If encryption is enabled for a repository, *dav-sync* stores files encrypted on the server. See [Encryption][6] for details.

[6]: ./encryption.html