dss: Make argument of parse_config_file() a boolean.

[dss.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index bebfe05f5e50cad84c138a38a26ba85697a2c126..db3d1c56386bb4c117c333adbe84c4694664c9e9 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,61 +1,91 @@
 Type
 
-       make
+               make
 
-in the dss source directory to build the dss executable. You
-likely need a recent version of gnu gengetopt,
-ftp://ftp.gnu.org/pub/gnu/gengetopt/, to compile dss.
+in the dss source directory to build the dss executable and copy it
+to some directory that is included in your PATH, e.g. to `$HOME/bin`
+or to `/usr/local/bin`.
+
+Note that [gnu
+gengetopt](https://www.gnu.org/software/gengetopt/gengetopt.html)
+is required to compile dss.
+
+Optionally, type
+
+                make man
+
+to create the man page of dss. This invokes help2man so make sure
+that help2man is installed on your system. Note that the man page is
+just the nroff variant of the output of `dss --detailed-help`.
 
 dss is known to compile on Linux, MacOS, Solaris, FreeBSD and
-NetBSD. However, it is run-tested on Linux only.
+NetBSD. However, it is run-tested only on Linux.
 
-Also make sure that rsync, http://rsync.samba.org/, is installed on
+Also make sure that [rsync](http://rsync.samba.org/) is installed on
 your system. Version 2.6.1 or newer is required.
 
-In order to create snapshots of the existing directory
+Examples:
+---------
+
+Suppose you'd like to create snapshots of the existing directory
 
-       /tmp/foo
+               /foo/bar
 
 in the directory
 
-       /tmp/bar,
+               /baz/qux.
+
+Create the config file
 
-execute the commands
+               ~/.dssrc
 
-       mkdir /tmp/bar
-       ./dss --run --source-dir /tmp/foo --dest-dir /tmp/bar
+that contains the values for the source and the destination directories
+as follows:
 
-To print a list of all snapshots created so far, use
+               echo 'source-dir "/foo/bar"' > ~/.dssrc
+               echo 'dest-dir "/baz/qux"' >> ~/.dssrc
 
-       ./dss --list --source-dir /tmp/foo --dest-dir /tmp/bar
+Then execute the commands
 
-You might want to create the config file
+               mkdir /baz/qux
+               dss --run
 
-       ~/.dssrc
+In order to print the list of all snapshots created so far, use
 
-that contains the values for the source and the destination
-directories. In the above example, this file would contain the
-following lines:
+               dss --ls
 
-       source-dir "/tmp/foo"
-       dest-dir "/tmp/bar"
+Yes, it's really that easy.
 
-Using a configuration file allows you to simply type
+The second example involves a slightly more sophisticated config file.
+It instructs dss to exclude everything which matches at least one
+pattern of the given exclude file, prevents rsync from crossing file
+system boundaries and increases the number of snapshots.
 
-       ./dss --run
+               source-dir "/foo/bar"
+               dest-dir "/baz/qux"
+               # exclude files matching patterns in /etc/dss.exclude
+               rsync-option "--exclude-from=/etc/dss.exclude"
+               # don't cross filesystem boundaries
+               rsync-option "--one-file-system"
+               # maintain 2^6 - 1 = 63 snaphots
+               num-intervals "6"
 
-to start snapshot creation and
+The /etc/dss.exclude file could look like this (see rsync(1) for
+more examples)
 
-       ./dss --list
 
-to list all avalable snapshots.
+                - /proc
+                - /**/tmp/
 
-Try
+Note that dss supports many more features and config options such
+as taking snapshots from remote hosts and several hooks that are
+executed on certain events, for example whenever a snapshot was
+created successfully. Try
 
-       ./dss -h
+               dss -h
 
 for an overview of all supported command line options or
 
-       ./dss --detailed-help
+               dss --detailed-help
 
 for the full help text.