# HG changeset patch # User Olaf Wintermann # Date 1499624114 -7200 # Node ID ee9e63c437c49d850fa61b2ab172a80f96583d7c # Parent 94c0a938b66c954e5dbb23f29fee55736fc6de66 adds documentation for most dav commands copy, move and configuration commands still missing diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/Makefile --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/Makefile Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,66 @@ +# +# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. +# +# Copyright 2017 Olaf Wintermann. All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +# POSSIBILITY OF SUCH DAMAGE. +# + +PANDOC=pandoc +PFLAGS = -c davdoc.css -B header.html -A footer.html + +SRC = getting-started.md +SRC += commands.md +SRC += list.md +SRC += get.md +SRC += put.md +SRC += mkdir.md +SRC += remove.md +SRC += copy.md +SRC += move.md +SRC += get-property.md +SRC += set-property.md +SRC += lock.md +SRC += unlock.md +SRC += info.md +SRC += date.md +SRC += configuration.md +SRC += encryption.md + +HTML = $(SRC:%.md=build/%.html) + +FILES = build/davdoc.css + +all: build $(HTML) $(FILES) + +build: + mkdir -p build + +build/%.html: %.md + $(PANDOC) $(PFLAGS) $< -o $@ + +build/davdoc.css: + cp davdoc.css build + +clean: + rm -Rf build diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/commands.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/commands.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,44 @@ +Commands +======== + +Overview +-------- + +List resources: + + dav list + +Download resource: + + dav get + +Download all resources from a collection: + + dav get -R + +Upload a file: + + dav put + +Upload all files from a directory: + + dav put -R + +Duplicate a resource or a collection on a server: + + dav copy + +There is also a move operation similar to copy: + + dav move + +These are the most common commands. There are also more commands for webdav locking and manipulating webdav properties. + +Common options +-------------- + +**`-N`** disable any authentication prompt. If authentication is required, dav will abort. + +**`-i`** disable TLS certificate verification + +**`-v`** enable verbose output. Internally `CURLOPT_VERBOSE` is set to 1 and verbose output is printed on stderr. diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/configuration.md diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/copy.md diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/date.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/date.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,23 @@ +dav date +======== + +**`date [url]`** + +The purpose of this command is to get the current date from a server and print it on stdout (http date format). This in useful in combination with the `-U` option for the `list` and `get` command. + +The *url* can be any http url. If no *url* is specified, the local time is used. + +### Example: incremental dav get + +It is possible to download only resources, which are modified since a specified date. The *date* command allows you to easily store the date of the last *get*. + + $ dav get -R myserv/col/ + ... + $ dav date myserv > last_get + +After some resources are changed on the server, you can download only the modified files. + + $ dav get -R -U `cat last_get` myserv/col/ + + + diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/davdoc.css --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/davdoc.css Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,79 @@ +.header, h1, h2, h3, .sidebar { + font-family: sans-serif; +} + +div.header { + padding-top: 0.3em; + padding-bottom: 0.5em; + margin-bottom: 2em; + border: none; + border-bottom: 1px solid; + border-bottom-color: #2E2E2E; +} + +div.header span { + font-size: 2em; + font-weight: bold; + margin-left: 1em; +} + +div.header img { + float: right; +} + +div.sidebar { + float: left; + width: 15em; +} + +div.nav { + color: black; + background-color: #E9EBEC; + margin-bottom: 1em; + padding-bottom: 0.1em; +} + +div.nav h3 { + color: white; + background-color: #5B6F7A; + font-size: 1.2em; + padding-top: 0.2em; + padding-bottom: 0.2em; + padding-left: 0.5em; + margin-top: 0; +} + +div.nav ul { + margin-top: 0; + padding-top: 0; + font-size: 0.95em; +} + +div.content { + margin-left: 16em; + padding: 0; + font-family: serif; + font-size: 1em; + min-width: 16em; +} + +div.content h1 { + color: white; + background-color: #5B6F7A; + font-size: 1.2em; + padding-top: 0.2em; + padding-bottom: 0.2em; + padding-left: 0.5em; + padding-right: 0; + margin-top: 0; +} + +div.content h2 { + font-size: 1.2em; +} + +div.content h3 { + font-size: 1.05em; +} + + diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/encryption.md diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/footer.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/footer.html Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,3 @@ + + + diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/get-property.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/get-property.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,27 @@ +dav get-property +================ + +**`get-property [-pc] [-n ] `** + +Gets a specified resource property. Every WebDAV property has a name and an XMl namespace. A namespace can be specified with the `-n` option or with a prefixed name. A prefix and property name are separated by an **:** + +Example: `D:creationdate` + +`D` is the prefix, `creationdate` is the name. + +There are only two available prefixes: + +1. `D` for the `DAV:` namespace +2. `idav` for `http://davutils.org/` + +To use an other namespace, use the `-n` option. + +If the property name has no prefix, and no namespace is specified, the default namespace `DAV:` is used. + +**`-p`** disable file name and path decryption if enabled + +**`-c`** enable file name and path decryption + +**`-n `** specify property namespace + +**Note:** Properties are never encrypted. diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/get.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/get.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,23 @@ +dav get +======= + +**`get [-pcR] [-o ] [-u ] `** + +Downloads a resource. It can also download collections and its child resources. +When downloading a single resource, the default local file name is the resource +name. When downloading collections, it does NOT create a local directory with +the collection's name and places it children in there, but it downloads the +children directly to the current working directory. + +**`-p`** disable file name and content decryption. You get exactly what is stored + on the server. + +**`-c`** enable file name and content decryption + +**`-R`** download a collection + +**`-o `** specify the local output file. A **-** indicates stdout + +**`-u `** downloads only files which are modified since the specified date. Uses the http date format + + diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/getting-started.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/getting-started.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,44 @@ +Getting started +=============== + +### Test + +After successful installation you can test dav with your WebDAV server. + + dav list http://example.com/webdav/ + +This lists all child resources of the specified collection. If you are unfamiliar to WebDAV terminology this means basically listing all files in a directory, similar to the ls unix tool. Infact you can also write dav ls instead of dav list and there is also a -l option like ls has one. + +### Create a repository + +All dav commands are expecting a url argument, but it may be a bit cumbersome to type a full url every time. But you can configure a repository in the dav configuration file ($HOME/.dav/config.xml) with the servers url, optional authentication information and other options. After that you can access a webdav server just with the repository name and an optional path. + +So when you have created a repository with the name myserv and the url http://example.com/webdav/, you can just type + + dav list myserv + +You can add a path to the repository name to access an other url + + dav list myserv/mycollection/ + +This lists the content of http://example.com/webdav/mycollection/ + +The easiest way to create a repository is with the add-repository command. This is a simple configuration assistant. + + $ dav add-repository + Each repository must have an unique name. + name: myserv + + Specify the repository base url. + url: http://example.com/webdav/ + + User for HTTP authentication. + user (optional): myuser + password (optional): + + + Added repository: myserv (http://example.com/webdav/) + +You can also configure the config.xml yourself, check out this example page and the config.xml spec. + +More informations about urls and path in dav here. diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/header.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/header.html Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,38 @@ +
+ davutils documentation +
+
+
+

dav

+ +
+
+

dav-sync

+
    +
  • .
    • +
+
+
+ + +
diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/info.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/info.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,49 @@ +dav info +======== + +**`info [-pc] `** + +Prints some information and lists all properties for the resource specified by url. + +### Example 1: info of a collection + +In this example *myserv* is a configured repository with the base url *https://example.com/webdav/*. Because *col* is not encrypted, the *url* is just the *path* appended to base url. + + $ dav info myserv/col/ + name: col + path: /col + url: https://example.com/webdav/col + type: collection + size: 28 + + namespace: DAV: + creationdate: 2017-06-14T09:32:43Z + getetag: "1000-551e83bebc19c" + getlastmodified: Wed, 14 Jun 2017 09:32:43 GMT + supportedlock: + +### Example 2: encrypted resource + +With encrypted resources, the *path* and *url* are different. The real resource name is random, but the name used by *dav* is stored in the *crypto-name* property. + + $ dav info -c myserv/crres + name: crres + path: /crres + url: https://example.com/webdav/wsIwbLxuJQTGtgiMAD1KGeaY + type: resource + size: 48 bytes + + namespace: DAV: + creationdate: 2017-07-09T16:18:09Z + getcontentlength: 48 + getetag: "30-553e4cfecd170" + getlastmodified: Sun, 09 Jul 2017 16:18:09 GMT + supportedlock: + + namespace: http://apache.org/dav/props/ + executable: F + + namespace: http://davutils.org/ + crypto-hash: fm4zstp/FevTs1aoUXc3+mqTmAf2Go+zQ34rSp8/ixDlGLQJXR74Je+WMl1zxZKbS/+5VwDhyZ9pT3gInsq2SA== + crypto-key: mykey + crypto-name: ZU+lZtFi3dprBz44714plYwfRnhyI/apYq46Sk/B6QU= diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/list.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/list.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,49 @@ +dav list +======== + +**`dav list [-altepcR] [-u ] `** + +Lists child resources of the specified collection. Without any options it +shows only the direct children and hides files beginning with a dot. + +Options +------- + +**`-a`** don't hide files whose names begins with a dot `.` + +**`-l`** shows additional information for resources + +Example: + + -- 4.2 KiB Oct 11 2015 somefile + +The first column contains to fields for flags. + +1. Field: `d-` indicates a collection +2. Field: `-c` indicates an encrypted resource + +Also encrypted collections are possible, but only the collection name is encrypted, the content may be unencrypted. + +The second column in the `list -l` output is the resource size. The number has always a suffix (bytes, KiB, MiB, GiB, TiB). To get the exact content-length in bytes you can use the [dav info][1] command. + +[1]: ./info.html + +The third column is the date of the last modification. The `strftime` format is `%b %d %H:%M` if the year is the same. Otherwise the format is `%b %d %Y`. + +The last column is the resource name. If the `-R` option is specified, the resource path is shown. + +**`-t`** this options only work in combination with `-l` and it adds the resource content type to the output (after the flags) + +**`-e`** similar to `-l`, but with 6 flag fields. Currently only the first 4 fields are used. The last two are reserved for future use. + +3. Field: **l** indicates a locked resource +4. Field: **x** indicates a executable resource (executable property with http://apache.org/dav/props/ namespace) + +**`-p`** disables file name and path decryption if enabled + +**`-c`** enables file name and path decryption + +**`-R`** recursively shows all resources in the collection and all child collections + +**`-u `** shows only resources with a lastmodified date after the specified + date. Uses the http date format diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/lock.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/lock.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,21 @@ +dav lock +======== + +**`lock [-pc] `** + +Creates a lock on the resource specified by the url. The lock is an exclusive write lock with infinity depth. + +If the resource is successfully locked, a lock token for this resource is printed on stdout. This lock token should be saved somewhere to unlock the resource eventually. + +**`-p`** disable file name and path decryption if enabled + +**`-c`** enable file name and path decryption + +### Example 1: lock resource and use the lock token + + $ dav lock myserv/resource + opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37 + $ dav put -L opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37 myserv/resource newfile + $ dav unlock -L opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37 myserv/resource + + diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/mkdir.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/mkdir.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,15 @@ +dav mkdir +========= + +**`mkdir [-pc] [-k ] [-L ] `** + +Creates a collection. All intermediate collections are created. + +**`-p`** disable file name encryption and decryption + +**`-c`** enables file file name and content encryption + +**`-k `** use the specified key for encryption. The key must be configured in + the config.xml file + +**`-L `** use a lock token diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/move.md diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/put.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/put.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,27 @@ +dav put +======= + +**`put [-pcR] [-k ] [-L ] `** + +Uploads a file or a directory. When uploading a file and the url points to +an existing collection, a resource inside this collection with the file's name is created. When the url points to a non-existing resource, the resource is +created. + +When uploading a directory, you need to specify the -R option. It uploads +all files in the directory to the specified url, but it does not create a +collection for the directory itself. + +**`-p`** disable file name encryption and decryption + +**`-c`** enable file name and content encryption + +**`-R`** upload directory + +**`-k `** use the specified key for encryption. The key must be configured in + the config.xml file + +**`-L `** use a lock token. See [dav lock][1] + +[1]: ./lock.html + + diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/remove.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/remove.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,13 @@ +dav remove +========== + +**`remove [-pc] [-L ] `** + +Removes a resource. When removing a collection, all unterneath resources are +removed. + +**`-p`** disable file name and path decryption if enabled + +**`-c`** enable file name and path decryption + +**`-L`** use a lock token diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/set-property.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/set-property.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,24 @@ +dav set-property +================ + +**`set-property [-pc] [-L ] [-n ] [value]`** + +Sets a resource property to a specified value. + +property is a property name with or without prefix (see [get-property][1] for details). + +[1]: ./get-property.html + +If no value is specified, the content for the property is read from stdin. + +**`-p`** disable file name and path decryption if enabled + +**`-c`** enable file name and path decryption + +**`-L `** use a lock token. See [dav lock][1] + +**`-n `** specify property namespace + +**Note:** Properties are never encrypted. + + diff -r 94c0a938b66c -r ee9e63c437c4 docs/src/unlock.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/unlock.md Sun Jul 09 20:15:14 2017 +0200 @@ -0,0 +1,25 @@ +dav unlock +========== + +**`unlock [-pc] [-L ] `** + +Unlocks the specified url with a lock token. If no lock token is specified with the `-L` option, it read from stdin. + +**`-p`** disable file name and path decryption if enabled + +**`-c`** enable file name and path decryption + +**`-L `** use a lock token + +### Example 1: unlock with lock token from stdin + + $ dav lock myserv/resource > locktoken + $ dav unlock myserv/resource < locktoken + +### Example 2: unlock with lock token from command line argument + + $ dav lock myserv/resource + opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37 + $ dav unlock -L opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37 myserv/resource + +