More documentation work

attic/archiver.py

@@ -46,7 +46,7 @@ class Archiver:
         return RepositoryServer().serve()
 
     def do_init(self, args):
-        """Initialize a new repository
+        """Initialize an empty repository
         """
         print('Initializing repository at "%s"' % args.repository.orig)
         repository = self.open_repository(args.repository, create=True)
@@ -59,9 +59,9 @@ class Archiver:
         return self.exit_code
 
     def do_change_passphrase(self, args):
-        """Change passphrase on repository key file
+        """Change repository key file passphrase
         """
-        repository = self.open_repository(Location(args.repository))
+        repository = self.open_repository(args.repository)
         manifest, key = Manifest.load(repository)
         key.change_passphrase()
         return self.exit_code
@@ -350,7 +350,7 @@ class Archiver:
         subparser = subparsers.add_parser('init', parents=[common_parser],
                                           description=self.do_init.__doc__)
         subparser.set_defaults(func=self.do_init)
-        subparser.add_argument('repository',
+        subparser.add_argument('repository', metavar='REPOSITORY',
                                type=location_validator(archive=False),
                                help='repository to create')
         subparser.add_argument('--key-file', dest='keyfile',
@@ -363,7 +363,8 @@ class Archiver:
         subparser = subparsers.add_parser('change-passphrase', parents=[common_parser],
                                           description=self.do_change_passphrase.__doc__)
         subparser.set_defaults(func=self.do_change_passphrase)
-        subparser.add_argument('repository', type=location_validator(archive=False))
+        subparser.add_argument('repository', metavar='REPOSITORY',
+                               type=location_validator(archive=False))
 
         subparser = subparsers.add_parser('create', parents=[common_parser],
                                           description=self.do_create.__doc__)
@@ -376,7 +377,7 @@ class Archiver:
                                metavar="PATTERN", help='exclude paths matching PATTERN')
         subparser.add_argument('-c', '--checkpoint-interval', dest='checkpoint_interval',
                                type=int, default=300, metavar='SECONDS',
-                               help='write checkpointe ever SECONDS seconds (Default: 300)')
+                               help='write checkpoint every SECONDS seconds (Default: 300)')
         subparser.add_argument('--do-not-cross-mountpoints', dest='dontcross',
                                action='store_true', default=False,
                                help='do not cross mount points')
@@ -414,7 +415,7 @@ class Archiver:
         subparser = subparsers.add_parser('list', parents=[common_parser],
                                           description=self.do_list.__doc__)
         subparser.set_defaults(func=self.do_list)
-        subparser.add_argument('src', metavar='SRC', type=location_validator(),
+        subparser.add_argument('src', metavar='REPOSITORY_OR_ARCHIVE', type=location_validator(),
                                help='repository/archive to list contents of')
 
         subparser = subparsers.add_parser('mount', parents=[common_parser],

docs/Makefile

@@ -138,5 +138,5 @@ gh-pages: html
 	(cd $$GH_PAGES_CLONE && git add -A && git commit -m 'Updated gh-pages' && git push) && \
 	rm -rf $$GH_PAGES_CLONE
 
-inotify:
+inotify: html
 	while inotifywait -r . --exclude usage.rst --exclude '_build/*' ; do make html ; done

docs/_static/nature.css

@@ -0,0 +1,283 @@
+/*
+ * nature.css_t
+ * ~~~~~~~~~~~~
+ *
+ * Sphinx stylesheet -- nature theme.
+ *
+ * :copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+ 
+@import url("basic.css");
+ 
+/* -- page layout ----------------------------------------------------------- */
+ 
+body {
+    font-family: Arial, sans-serif;
+    font-size: 100%;
+    background-color: #111;
+    color: #555;
+    margin: 0;
+    padding: 0;
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 230px;
+}
+
+hr {
+    border: 1px solid #B1B4B6;
+}
+ 
+div.document {
+    background-color: #eee;
+}
+ 
+div.body {
+    background-color: #ffffff;
+    color: #3E4349;
+    padding: 0 30px 30px 30px;
+    font-size: 0.9em;
+}
+ 
+div.footer {
+    color: #555;
+    width: 100%;
+    padding: 13px 0;
+    text-align: center;
+    font-size: 75%;
+}
+ 
+div.footer a {
+    color: #444;
+    text-decoration: underline;
+}
+ 
+div.related {
+    background-color: #6BA81E;
+    line-height: 32px;
+    color: #fff;
+    text-shadow: 0px 1px 0 #444;
+    font-size: 0.9em;
+}
+ 
+div.related a {
+    color: #E2F3CC;
+}
+ 
+div.sphinxsidebar {
+    font-size: 0.75em;
+    line-height: 1.5em;
+}
+
+div.sphinxsidebarwrapper{
+    padding: 20px 0;
+}
+ 
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+    font-family: Arial, sans-serif;
+    color: #222;
+    font-size: 1.2em;
+    font-weight: normal;
+    margin: 0;
+    padding: 5px 10px;
+    background-color: #ddd;
+    text-shadow: 1px 1px 0 white
+}
+
+div.sphinxsidebar h4{
+    font-size: 1.1em;
+}
+ 
+div.sphinxsidebar h3 a {
+    color: #444;
+}
+ 
+ 
+div.sphinxsidebar p {
+    color: #888;
+    padding: 5px 20px;
+}
+ 
+div.sphinxsidebar p.topless {
+}
+ 
+div.sphinxsidebar ul {
+    margin: 10px 20px;
+    padding: 0;
+    color: #000;
+}
+ 
+div.sphinxsidebar a {
+    color: #444;
+}
+ 
+div.sphinxsidebar input {
+    border: 1px solid #ccc;
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+div.sphinxsidebar input[type=text]{
+    margin-left: 20px;
+}
+ 
+/* -- body styles ----------------------------------------------------------- */
+ 
+a {
+    color: #005B81;
+    text-decoration: none;
+}
+ 
+a:hover {
+    color: #E32E00;
+    text-decoration: underline;
+}
+ 
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: Arial, sans-serif;
+    background-color: #BED4EB;
+    font-weight: normal;
+    color: #212224;
+    margin: 30px 0px 10px 0px;
+    padding: 5px 0 5px 10px;
+    text-shadow: 0px 1px 0 white
+}
+ 
+div.body h1 { border-top: 20px solid white; margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 150%; background-color: #C8D5E3; }
+div.body h3 { font-size: 120%; background-color: #D8DEE3; }
+div.body h4 { font-size: 110%; background-color: #D8DEE3; }
+div.body h5 { font-size: 100%; background-color: #D8DEE3; }
+div.body h6 { font-size: 100%; background-color: #D8DEE3; }
+ 
+a.headerlink {
+    color: #c60f0f;
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+ 
+a.headerlink:hover {
+    background-color: #c60f0f;
+    color: white;
+}
+ 
+div.body p, div.body dd, div.body li {
+    line-height: 1.5em;
+}
+ 
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.highlight{
+    background-color: white;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+ 
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+ 
+div.topic {
+    background-color: #eee;
+}
+ 
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+ 
+p.admonition-title {
+    display: inline;
+}
+ 
+p.admonition-title:after {
+    content: ":";
+}
+ 
+pre {
+    padding: 10px;
+    background-color: White;
+    color: #222;
+    line-height: 1.2em;
+    border: 1px solid #C6C9CB;
+    font-size: 1.1em;
+    margin: 1.5em 0 1.5em 0;
+    -webkit-box-shadow: 1px 1px 1px #d8d8d8;
+    -moz-box-shadow: 1px 1px 1px #d8d8d8;
+}
+ 
+tt {
+    background-color: #ecf0f3;
+    color: #222;
+    /* padding: 1px 2px; */
+    font-size: 1.1em;
+    font-family: monospace;
+}
+
+.viewcode-back {
+    font-family: Arial, sans-serif;
+}
+
+div.viewcode-block:target {
+    background-color: #f4debf;
+    border-top: 1px solid #ac9;
+    border-bottom: 1px solid #ac9;
+}
+
+/* Customizations */
+body {
+    background-color: rgb(242, 242, 242);
+}
+div.related {
+    background-color: #0a0a0a;
+    text-shadow: none;
+}
+div.related a {
+    color: #ddd;
+}
+div.body h1,
+div.body h2,
+div.body h3 {
+    padding-left: 0;
+    background-color: inherit;
+}
+
+div.document,
+div.related {
+    width: 800px;
+    margin: 0px auto;
+}
+div.body {
+    background-color: inherit;
+    border-left: 1px solid #eee;
+}
+div.document {
+    background-color: #ffffff;
+}
+div.sphinxsidebar {
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+    background-color: inherit;
+}

docs/_themes/attic/sidebarlogo.html

@@ -1,6 +1,5 @@
 <div class="sidebarlogo">
   <a href="{{ pathto('index') }}">
   <div class="title">Attic</div>
-  <div class="subtitle">Documentation</div>
 </a>
 </div>

docs/_themes/attic/static/attic.css_t

@@ -35,10 +35,14 @@ div.sphinxsidebar {
 }
 
 h1, h2, h3 {
+  font-family: "DejaVu Serif";
   font-weight: normal;
-  color: #444;
+  font-style: italic;
+  color: #333;
 }
-
+h1 { font-size: 200%;}
+h2 { font-size: 140%;}
+h3 { font-size: 100%;}
 ul {
   padding-left: 1.2em;
   margin-bottom: .3em;
@@ -49,7 +53,6 @@ ul ul {
 li {
   margin: .1em 0;
 }
-
 a:link, a:visited {
   color: #00608f;
   text-decoration: none;
@@ -64,6 +67,9 @@ div.sphinxsidebar a:link, div.sphinxsidebar a:visited {
   border-bottom: 1px dotted #555;
 }
 
+div.sphinxsidebar input {
+  border: 1px solid #ccc;
+}
 
 pre {
   border: 1px solid #ccc;
@@ -72,17 +78,32 @@ pre {
   color: #ddd;
   border-radius: .4em;
   box-shadow: 2px 2px #ddd;
-
+  line-height: 1.2em;
+}
+pre a:link,
+pre a:visited {
+  color: #00B0E4;
 }
 
 div.note {
   background-color: #eee;
   border: 1px solid #ccc;
+  border-radius: .4em;
+  box-shadow: 2px 2px #ddd;
 }
 div.sidebarlogo .title {
-  font-size: 250%;
+  font-family: "DejaVu Serif";
+  font-style: italic;
+  font-size: 500%;
 }
 div.sidebarlogo .subtitle {
   font-style: italic;
   color: #777;
-}
+}
+tt span.pre {
+  font-size: 110%;
+}
+dt {
+  font-style: italic;
+  font-size: 95%;
+}

docs/commands.rst

@@ -0,0 +1,239 @@
+.. include:: global.rst.inc
+.. _detailed_usage:
+
+Commands
+========
+
+|project_name| consists of a number of commands. Each command accepts
+a number of arguments and options. The following sections will describe each
+command in detail.
+
+Quiet by default
+----------------
+
+Like most UNIX commands |project_name| is quiet by default but the ``-v`` or
+``--verbose`` option can be used to get the program to output more status
+messages as it is processing.
+
+.. _attic_init:
+
+attic init
+----------
+
+.. include:: usage/init.rst.inc
+
+This command initializes an empty :ref:`repository <repository_def>`.
+A repository is a filesystem directory
+containing the deduplicated data from zero or more archives.
+Encryption is enabled at repository initialization time.
+
+Examples
+~~~~~~~~
+::
+
+    # Local backup repository
+    $ attic init /data/mybackuprepo.attic
+
+    # Remote backup repository
+    $ attic init user@hostname:mybackuprepo.attic
+
+    # Encrypted remote backup repository
+    $ attic init --passphrase user@hostname:mybackuprepo.attic
+
+
+attic create
+------------
+
+.. include:: usage/create.rst.inc
+
+This command creates a backup archive containing all files found while
+recursively traversing all paths specified. The archive will consume almost
+no disk space for files or parts of files that has already been archived by
+other archives.
+
+Examples
+~~~~~~~~
+::
+
+    # Backups ~/Documents into an archive named "my-documents"
+    $ attic create /data/myrepo.attic::my-documents ~/Documents
+
+    # Backup ~/Documents and ~/src but exclude pyc files
+    $ attic create /data/myrepo.attic::my-files   \
+        ~/Documents                               \
+        ~/src                                     \
+        --exclude *.pyc
+
+    # Backup the root filesystem into an archive named "root-YYYY-MM-DD"
+    NAME="root-`date +%Y-%m-%d`"
+    $ attic create /data/myrepo.attic::$NAME / --do-not-cross-mountpoints
+
+.. _attic_extract:
+
+attic extract
+-------------
+
+.. include:: usage/extract.rst.inc
+
+This command extracts the contents of an archive. By default the entire
+archive is extracted but a subset of files and directories can be selected
+by passing a list of ``PATHs`` as arguments. The file selection can further
+be restricted by using the ``--exclude`` option.
+
+Examples
+~~~~~~~~
+::
+
+    # Extract entire archive
+    $ attic extract /data/myrepo::my-files
+
+    # Extract entire archive and list files while processing
+    $ attic extract -v /data/myrepo::my-files
+
+    # Extract the "src" directory
+    $ attic extract /data/myrepo::my-files home/USERNAME/src
+
+    # Extract the "src" directory but exclude object files
+    $ attic extract /data/myrepo::my-files home/USERNAME/src --exclude *.o
+
+
+attic verify
+------------
+
+.. include:: usage/verify.rst.inc
+
+This command is similar to :ref:`attic_extract` but instead of writing any
+files to disk the command just verifies that all files are extractable and
+not corrupt. |project_name| will not compare the the archived files with the
+files on disk.
+
+
+attic delete
+------------
+
+.. include:: usage/delete.rst.inc
+
+This command deletes an archive from the repository. Any disk space not
+shared with any other existing archive is also reclaimed.
+
+
+.. _attic_list:
+
+attic list
+----------
+
+.. include:: usage/list.rst.inc
+
+This command lists the contents of a repository or an archive.
+
+Examples
+~~~~~~~~
+::
+
+    $ attic list /data/myrepo
+    my-files            Thu Aug  1 23:33:22 2013
+    my-documents        Thu Aug  1 23:35:43 2013
+    root-2013-08-01     Thu Aug  1 23:43:55 2013
+    root-2013-08-02     Fri Aug  2 15:18:17 2013
+    ...
+
+    $ attic list /data/myrepo::root-2013-08-02
+    drwxr-xr-x root   root          0 Jun 05 12:06 .
+    lrwxrwxrwx root   root          0 May 31 20:40 bin -> usr/bin
+    drwxr-xr-x root   root          0 Aug 01 22:08 etc
+    drwxr-xr-x root   root          0 Jul 15 22:07 etc/ImageMagick-6
+    -rw-r--r-- root   root       1383 May 22 22:25 etc/ImageMagick-6/colors.xml
+    ...
+
+
+attic prune
+-----------
+
+.. include:: usage/prune.rst.inc
+
+The ``prune`` command prunes a repository by deleting archives not matching
+any of the specified retention options specified. This command is normally
+used by automated backup scripts wanting to keep a certain number of historic
+backups. 
+
+Examples
+~~~~~~~~
+::
+
+    # Keep 7 end of day and 4 end of week archives
+    $ attic prune /data/myrepo --daily=7 --weekly=4
+
+    # Same as above but only apply to archive names starting with "foo"
+    $ attic prune /data/myrepo --daily=7 --weekly=4 --prefix=foo
+
+
+attic info
+----------
+
+.. include:: usage/info.rst.inc
+
+This command displays some detailed information about the specified archive.
+
+Examples
+~~~~~~~~
+::
+
+    $ attic info /data/myrepo::root-2013-08-02
+    Name: root-2013-08-02
+    Fingerprint: bc3902e2c79b6d25f5d769b335c5c49331e6537f324d8d3badcb9a0917536dbb
+    Hostname: myhostname
+    Username: root
+    Time: Fri Aug  2 15:18:17 2013
+    Command line: /usr/bin/attic create --stats /data/myrepo::root-2013-08-02 / --do-not-cross-mountpoints
+    Number of files: 147429
+    Original size: 5344169493 (4.98 GB)
+    Compressed size: 1748189642 (1.63 GB)
+    Unique data: 64805454 (61.80 MB)
+
+
+attic mount
+-----------
+
+.. include:: usage/mount.rst.inc
+
+This command mounts an archive as a FUSE filesystem. This can be useful for
+browsing an archive or restoring individual files. Unless the ``--foreground``
+option is given the command will run in the background until the filesystem
+is ``umounted``.
+
+Examples
+~~~~~~~~
+::
+
+    $ attic mount /data/myrepo::root-2013-08-02 /tmp/mymountpoint
+    $ ls /tmp/mymountpoint
+    bin  boot  etc  lib  lib64  mnt  opt  root  sbin  srv  usr  var
+    $ fusermount -u /tmp/mymountpoint
+
+
+attic change-passphrase
+-----------------------
+
+.. include:: usage/change-passphrase.rst.inc
+
+The key files used for repository encryption are optionally passphrase
+protected. This command can be used to change this passphrase.
+
+Examples
+~~~~~~~~
+::
+
+    # Create a key file protected repository
+    $ attic init --key-file /tmp/encrypted-repo
+    Initializing repository at "/tmp/encrypted-repo"
+    Enter passphrase (empty for no passphrase):
+    Enter same passphrase again: 
+    Key file "/home/USER/.attic/keys/tmp_encrypted_repo" created.
+    Keep this file safe. Your data will be inaccessible without it.
+
+    # Change key file passphrase
+    $ attic change-passphrase /tmp/encrypted-repo
+    Enter passphrase for key file /home/USER/.attic/keys/tmp_encrypted_repo: 
+    New passphrase: 
+    Enter same passphrase again: 
+    Key file "/home/USER/.attic/keys/tmp_encrypted_repo" updated

docs/conf.py

@@ -133,7 +133,7 @@ html_static_path = ['_static']
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {
     'index': ['sidebarlogo.html', 'sidebarusefullinks.html', 'searchbox.html'],
-    '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', 'searchbox.html']
+    '**': ['sidebarlogo.html', 'localtoc.html', 'relations.html', 'sidebarusefullinks.html', 'searchbox.html']
 }
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/detailedusage.rst

@@ -1,11 +0,0 @@
-.. include:: global.rst.inc
-.. _detailed_usage:
-
-Detailed Usage
---------------
-
-|project_name| consists of a number of subcommands. Each subcommand accepts
-a number of arguments and options. The following sections will describe each
-subcommand in detail.
-
-.. include:: usage.rst

docs/faq.rst

@@ -5,40 +5,30 @@ Frequently asked questions
 ==========================
 
 Which platforms are supported?
-------------------------------
-
-Currently Linux, FreeBSD and MacOS X are supported.
+    Currently Linux, FreeBSD and MacOS X are supported.
 
 
 Can I backup VM disk images?
-----------------------------
-
-Yes, the :ref:`deduplication <deduplication_def>` technique used by |project_name|
-makes sure only the modified parts of the file are stored.
-
+    Yes, the :ref:`deduplication <deduplication_def>` technique used by |project_name|
+    makes sure only the modified parts of the file are stored.
 
 Which file attributes are preserved?
-------------------------------------
+    The following attributes are preserved:
 
-The following attributes are preserved:
-
-* Name
-* Contents
-* Time of last modification (nanosecond precision with Python >= 3.3)
-* User ID of owner
-* Group ID of owner
-* Unix Permission
-* Extended attributes (xattrs)
-
-.. Note::
-    POSIX Access Control Lists (ACL_) are not yet preserved.
+    * Name
+    * Contents
+    * Time of last modification (nanosecond precision with Python >= 3.3)
+    * User ID of owner
+    * Group ID of owner
+    * Unix Permission
+    * Extended attributes (xattrs)
 
+    .. Note::
+        POSIX Access Control Lists (ACL_) are not yet preserved.
 
 How can I specify the encryption passphrase programmatically?
--------------------------------------------------------------
-
-The encryption passphrase can be specified programmatically using the
-`ATTIC_PASSPHRASE` environment variable. This is convenient when setting up
-automated encrypted backups. Another option is to use
-key file based encryption with a blank passphrase. For more details see
-:ref:encrypted_repos
+    The encryption passphrase can be specified programmatically using the
+    `ATTIC_PASSPHRASE` environment variable. This is convenient when setting up
+    automated encrypted backups. Another option is to use
+    key file based encryption with a blank passphrase. See
+    :ref:`encrypted_repos` for more details.

docs/foreword.rst

@@ -0,0 +1,58 @@
+.. include:: global.rst.inc
+.. _foreward:
+
+Foreword
+========
+
+Features
+--------
+
+Space efficient storage
+    Variable block size `deduplication`_ is used to reduce the number of bytes 
+    stored by detecting redundant data. Each file is split into a number of
+    variable length chunks and only chunks that have never been seen before
+    are compressed and added to the repository.
+
+Optional data encryption
+    All data can be protected using 256-bit AES_ encryption and data integrity
+    and authenticity is verified using `HMAC-SHA256`_.
+
+Off-site backups
+    |project_name| can store data on any remote host accessible over SSH as
+    long as |project_name| is installed.
+
+Backups mountable as filesystems
+    Backup archives are :ref:`mountable <usage_attic_mount>` as
+    `userspace filesystems`_ for easy backup verification and restores.
+
+
+Terminology
+-----------
+
+.. _deduplication_def:
+
+Deduplication
+    Deduplication is a technique for improving storage utilization by
+    eliminating redundant data. 
+
+.. _archive_def:
+
+Archive
+    An archive is a collection of files along with metadata that include file
+    permissions, directory structure and various file attributes.
+    Since each archive in a repository must have a unique name a good naming
+    convention is ``hostname-YYYY-MM-DD``.
+
+.. _repository_def:
+
+Repository
+    A repository is a filesystem directory storing data from zero or more
+    archives. The data in a repository is both deduplicated and 
+    optionally encrypted making it both efficient and safe. Repositories are
+    created using :ref:`attic_init` and the contents can be listed using
+    :ref:`attic_list`.
+
+Key file
+    When a repository is initialized a key file containing a password
+    protected encryption key is created. It is vital to keep this file safe
+    since the repository data is totally inaccessible without it.

docs/global.rst.inc

@@ -1,3 +1,4 @@
+.. highlight:: bash
 .. |project_name| replace:: ``Attic``
 .. |project_version| replace:: 0.7
 .. |package_dirname| replace:: Attic-|project_version|
@@ -15,3 +16,4 @@
 .. _`msgpack-python`: https://pypi.python.org/pypi/msgpack-python/
 .. _homebrew: http://mxcl.github.io/homebrew/
 .. _issue tracker: https://github.com/jborg/attic/issues
+.. _userspace filesystems: https://en.wikipedia.org/wiki/Filesystem_in_Userspace

docs/index.rst

@@ -7,21 +7,6 @@ The main goal of |project_name| is to provide an efficient and secure way
 to backup data. The data deduplication technique used makes |project_name|
 suitable for daily backups since only actual changes are stored.
 
-Main Features
--------------
-Space efficient storage
-    Variable block size `deduplication`_ is used to reduce the number of bytes 
-    stored by detecting redundant data. Each file is split into a number of
-    variable length chunks and only chunks that have never been seen before
-    are compressed and added to the repository.
-
-Optional data encryption
-    All data can be protected using 256-bit AES_ encryption and data integrity
-    and authenticity is verified using `HMAC-SHA256`_.
-
-Off-site backups
-    |project_name| can store data on any remote host accessible over SSH as
-    long as |project_name| is installed.
 
 Easy to use
 -----------
@@ -31,7 +16,7 @@ first backup :ref:`archive <archive_def>` in two lines::
     $ attic init /usbdrive/my-backup.attic
     $ attic create -v /usbdrive/my-backup.attic::documents ~/Documents
 
-See the :ref:`generalusage` section for more detailed examples.
+See the :ref:`generalusage` section for a more detailed example.
 
 Easy installation
 -----------------
@@ -39,7 +24,7 @@ You can use pip to install |project_name| quickly and easily::
 
     $ pip install attic
 
-Need more help with installing? See :ref:`installation`
+Need more help with installing? See :ref:`installation`.
 
 User's Guide
 ============
@@ -47,11 +32,11 @@ User's Guide
 .. toctree::
    :maxdepth: 2
 
+   foreword
    installation
-   generalusage
-   detailedusage
+   quickstart
+   commands
    faq
-   terminology
 
 Contribute
 ==========

docs/installation.rst

@@ -2,7 +2,7 @@
 .. _installation:
 
 Installation
-=============
+============
 
 |project_name| requires Python_ 3.2 or above to work. Even though Python 3 is
 not the default Python version on most Linux distributions it is usually

docs/generalusage.rst → docs/quickstart.rst

@@ -1,51 +1,79 @@
 .. include:: global.rst.inc
-.. _generalusage:
+.. _quickstart:
 
-General Usage
-=============
+Quick Start
+===========
 
-The following examples showcases how to use |project_name| to backup some
-important files from a users home directory (for more detailed information
-about each subcommand see the :ref:`detailed_usage` section).
+This chapter will get you started with |project_name|. The first section
+presents a simple example that uses |project_name| to backup data.
+The next section continues by showing how backups can be automated.
 
-Initialize a local :ref:`repository <repository_def>` to store backup
-:ref:`archives <archive_def>` in (See :ref:`encrypted_repos` and
-:ref:`remote_repos` for more details)::
+A step by step example
+----------------------
+
+1. Before any backup can be made a repository has to be initialized::
 
     $ attic init /somewhere/my-backup.attic
 
-Create an archive containing the ``~/src`` and ``~/Documents`` directories::
+2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called
+   *first-backup*::
 
     $ attic create -v /somwhere/my-backup.attic::first-backup ~/src ~/Documents
 
-Create another archive the next day. This backup will be a lot quicker since
-only new data is stored. The ``--stats`` option tells |project_name| to print
-statistics about the newly created archive such as the amount of unique data
-(not shared with other archives)::
+3. The next day create a new archive called *second-backup*::
 
     $ attic create -v --stats /somwhere/my-backup.attic::second-backup ~/src ~/Documents
 
-List all archives in the repository::
+   This backup will be a lot quicker and a lot smaller since only new never
+   before seen data is stored. The ``--stats`` causes |project_name| to output
+   statistics about the newly created archive such as the amount of unique
+   data (not shared with other archives).
+
+4. List all archives in the repository::
 
     $ attic list /somewhere/my-backup.attic
 
-List the files in the *first-backup* archive::
+5. List the contents of the *first-backup* archive::
 
     $ attic list /somewhere/my-backup.attic::first-backup
 
-Restore the *first-backup* archive::
+6. Restore the *first-backup* archive::
 
     $ attic extract -v /somwhere/my-backup.attic::first-backup
 
-Recover disk space by manually deleting the *first-backup* archive::
+7. Recover disk space by manually deleting the *first-backup* archive::
 
     $ attic delete /somwhere/my-backup.attic::first-backup
 
-Use the ``prune`` subcommand to delete all archives except a given number of
-*daily*, *weekly*, *monthly* and *yearly* archives::
 
-    $ attic prune /somwhere/my-backup.attic --daily=7 --weekly=2 --monthly=6
+Automating backups
+------------------
+
+The following example script backups up ``/home`` and
+``/var/www`` to a remote server. The script also uses the
+:ref:`usage_attic_prune` subcommand to maintain a certain number
+of old archives::
+
+    #!/bin/sh
+    REPOSITORY=username@remoteserver.com:backup.attic
+
+    # Backup all of /home and /var/www except a few
+    # excluded directories
+    attic create --stats                            \
+        $REPOSITORY::hostname-`date +%Y-%m-%d`      \
+        /home                                       \
+        /var/www                                    \
+        --exclude /home/*/.cache                    \
+        --exclude /home/Ben/Music/Justin\ Bieber    \
+        --exclude *.pyc
+
+    # Use the `prune` subcommand to maintain 7 daily, 4 weekly
+    # and 6 monthly archives.
+    attic prune -v $REPOSITORY --daily=7 --weekly=4 --monthly=6
 
+.. Note::
+    This script assumes the repository has already been initalized with
+    :ref:`attic_init`.
 
 .. _encrypted_repos:
 

docs/update_usage.sh

@@ -1,7 +1,9 @@
 #!/usr/bin/bash
-echo -n > usage.rst 
-for cmd in change-passphrase create delete extract init mount prune verify; do
-  LINE=`echo -n attic $cmd | tr 'a-z- ' '~'`
-  echo -e ".. _usage_attic_$cmd:\n\nattic $cmd\n$LINE\n::\n" >> usage.rst
-  attic $cmd -h >> usage.rst
+if [ ! -d usage ]; then
+  mkdir usage
+fi
+for cmd in change-passphrase create delete extract info init list mount prune verify; do
+  FILENAME="usage/$cmd.rst.inc"
+  echo -e "Synopsis\n~~~~~~~~\n::\n" > $FILENAME
+  attic $cmd -h | sed -e 's/^/    /' >> $FILENAME
 done

docs/usage.rst

@@ -1,166 +0,0 @@
-.. _usage_attic_change-passphrase:
-
-attic change-passphrase
-~~~~~~~~~~~~~~~~~~~~~~~
-::
-
-usage: attic change-passphrase [-h] [-v] repository
-
-Change passphrase on repository key file
-
-positional arguments:
-  repository
-
-optional arguments:
-  -h, --help     show this help message and exit
-  -v, --verbose  verbose output
-.. _usage_attic_create:
-
-attic create
-~~~~~~~~~~~~
-::
-
-usage: attic create [-h] [-v] [-s] [-e PATTERN] [-c SECONDS]
-                    [--do-not-cross-mountpoints] [--numeric-owner]
-                    ARCHIVE PATH [PATH ...]
-
-Create new archive
-
-positional arguments:
-  ARCHIVE               archive to create
-  PATH                  paths to archive
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --verbose         verbose output
-  -s, --stats           print statistics for the created archive
-  -e PATTERN, --exclude PATTERN
-                        exclude paths matching PATTERN
-  -c SECONDS, --checkpoint-interval SECONDS
-                        write checkpointe ever SECONDS seconds (Default: 300)
-  --do-not-cross-mountpoints
-                        do not cross mount points
-  --numeric-owner       only store numeric user and group identifiers
-.. _usage_attic_delete:
-
-attic delete
-~~~~~~~~~~~~
-::
-
-usage: attic delete [-h] [-v] ARCHIVE
-
-Delete archive
-
-positional arguments:
-  ARCHIVE        archive to delete
-
-optional arguments:
-  -h, --help     show this help message and exit
-  -v, --verbose  verbose output
-.. _usage_attic_extract:
-
-attic extract
-~~~~~~~~~~~~~
-::
-
-usage: attic extract [-h] [-v] [-e PATTERN] [--numeric-owner]
-                     ARCHIVE [PATH [PATH ...]]
-
-Extract archive contents
-
-positional arguments:
-  ARCHIVE               archive to extract
-  PATH                  paths to extract
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --verbose         verbose output
-  -e PATTERN, --exclude PATTERN
-                        exclude paths matching PATTERN
-  --numeric-owner       only obey numeric user and group identifiers
-.. _usage_attic_init:
-
-attic init
-~~~~~~~~~~
-::
-
-usage: attic init [-h] [-v] [--key-file] [--passphrase] repository
-
-Initialize a new repository
-
-positional arguments:
-  repository     repository to create
-
-optional arguments:
-  -h, --help     show this help message and exit
-  -v, --verbose  verbose output
-  --key-file     enable key file based encryption
-  --passphrase   enable passphrase based encryption
-.. _usage_attic_mount:
-
-attic mount
-~~~~~~~~~~~
-::
-
-usage: attic mount [-h] [-v] [-f] [-o OPTIONS] ARCHIVE MOUNTPOINT
-
-Mount archive as a FUSE fileystem
-
-positional arguments:
-  ARCHIVE           archive to mount
-  MOUNTPOINT        where to mount filesystem
-
-optional arguments:
-  -h, --help        show this help message and exit
-  -v, --verbose     verbose output
-  -f, --foreground  stay in foreground, do not daemonize
-  -o OPTIONS        Extra mount options
-.. _usage_attic_prune:
-
-attic prune
-~~~~~~~~~~~
-::
-
-usage: attic prune [-h] [-v] [-H HOURLY] [-d DAILY] [-w WEEKLY] [-m MONTHLY]
-                   [-y YEARLY] [-p PREFIX]
-                   REPOSITORY
-
-Prune repository archives according to specified rules
-
-positional arguments:
-  REPOSITORY            repository to prune
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --verbose         verbose output
-  -H HOURLY, --hourly HOURLY
-                        number of hourly archives to keep
-  -d DAILY, --daily DAILY
-                        number of daily archives to keep
-  -w WEEKLY, --weekly WEEKLY
-                        number of daily archives to keep
-  -m MONTHLY, --monthly MONTHLY
-                        number of monthly archives to keep
-  -y YEARLY, --yearly YEARLY
-                        number of yearly archives to keep
-  -p PREFIX, --prefix PREFIX
-                        only consider archive names starting with this prefix
-.. _usage_attic_verify:
-
-attic verify
-~~~~~~~~~~~~
-::
-
-usage: attic verify [-h] [-v] [-e PATTERN] ARCHIVE [PATH [PATH ...]]
-
-Verify archive consistency
-
-positional arguments:
-  ARCHIVE               archive to verity integrity of
-  PATH                  paths to verify
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --verbose         verbose output
-  -e PATTERN, --exclude PATTERN
-                        exclude paths matching PATTERN

docs/usage/change-passphrase.rst.inc

@@ -0,0 +1,14 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic change-passphrase [-h] [-v] REPOSITORY
+    
+    Change repository key file passphrase
+    
+    positional arguments:
+      REPOSITORY
+    
+    optional arguments:
+      -h, --help     show this help message and exit
+      -v, --verbose  verbose output

docs/usage/create.rst.inc

@@ -0,0 +1,25 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic create [-h] [-v] [-s] [-e PATTERN] [-c SECONDS]
+                        [--do-not-cross-mountpoints] [--numeric-owner]
+                        ARCHIVE PATH [PATH ...]
+    
+    Create new archive
+    
+    positional arguments:
+      ARCHIVE               archive to create
+      PATH                  paths to archive
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      -v, --verbose         verbose output
+      -s, --stats           print statistics for the created archive
+      -e PATTERN, --exclude PATTERN
+                            exclude paths matching PATTERN
+      -c SECONDS, --checkpoint-interval SECONDS
+                            write checkpoint every SECONDS seconds (Default: 300)
+      --do-not-cross-mountpoints
+                            do not cross mount points
+      --numeric-owner       only store numeric user and group identifiers

docs/usage/delete.rst.inc

@@ -0,0 +1,14 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic delete [-h] [-v] ARCHIVE
+    
+    Delete archive
+    
+    positional arguments:
+      ARCHIVE        archive to delete
+    
+    optional arguments:
+      -h, --help     show this help message and exit
+      -v, --verbose  verbose output

docs/usage/extract.rst.inc

@@ -0,0 +1,19 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic extract [-h] [-v] [-e PATTERN] [--numeric-owner]
+                         ARCHIVE [PATH [PATH ...]]
+    
+    Extract archive contents
+    
+    positional arguments:
+      ARCHIVE               archive to extract
+      PATH                  paths to extract
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      -v, --verbose         verbose output
+      -e PATTERN, --exclude PATTERN
+                            exclude paths matching PATTERN
+      --numeric-owner       only obey numeric user and group identifiers

docs/usage/info.rst.inc

@@ -0,0 +1,14 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic info [-h] [-v] ARCHIVE
+    
+    Show archive details such as disk space used
+    
+    positional arguments:
+      ARCHIVE        archive to display information about
+    
+    optional arguments:
+      -h, --help     show this help message and exit
+      -v, --verbose  verbose output

docs/usage/init.rst.inc

@@ -0,0 +1,16 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic init [-h] [-v] [--key-file] [--passphrase] REPOSITORY
+    
+    Initialize an empty repository
+    
+    positional arguments:
+      REPOSITORY     repository to create
+    
+    optional arguments:
+      -h, --help     show this help message and exit
+      -v, --verbose  verbose output
+      --key-file     enable key file based encryption
+      --passphrase   enable passphrase based encryption

docs/usage/list.rst.inc

@@ -0,0 +1,15 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic list [-h] [-v] REPOSITORY_OR_ARCHIVE
+    
+    List archive or repository contents
+    
+    positional arguments:
+      REPOSITORY_OR_ARCHIVE
+                            repository/archive to list contents of
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      -v, --verbose         verbose output

docs/usage/mount.rst.inc

@@ -0,0 +1,17 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic mount [-h] [-v] [-f] [-o OPTIONS] ARCHIVE MOUNTPOINT
+    
+    Mount archive as a FUSE fileystem
+    
+    positional arguments:
+      ARCHIVE           archive to mount
+      MOUNTPOINT        where to mount filesystem
+    
+    optional arguments:
+      -h, --help        show this help message and exit
+      -v, --verbose     verbose output
+      -f, --foreground  stay in foreground, do not daemonize
+      -o OPTIONS        Extra mount options

docs/usage/prune.rst.inc

@@ -0,0 +1,28 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic prune [-h] [-v] [-H HOURLY] [-d DAILY] [-w WEEKLY] [-m MONTHLY]
+                       [-y YEARLY] [-p PREFIX]
+                       REPOSITORY
+    
+    Prune repository archives according to specified rules
+    
+    positional arguments:
+      REPOSITORY            repository to prune
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      -v, --verbose         verbose output
+      -H HOURLY, --hourly HOURLY
+                            number of hourly archives to keep
+      -d DAILY, --daily DAILY
+                            number of daily archives to keep
+      -w WEEKLY, --weekly WEEKLY
+                            number of daily archives to keep
+      -m MONTHLY, --monthly MONTHLY
+                            number of monthly archives to keep
+      -y YEARLY, --yearly YEARLY
+                            number of yearly archives to keep
+      -p PREFIX, --prefix PREFIX
+                            only consider archive names starting with this prefix

docs/usage/verify.rst.inc

@@ -0,0 +1,17 @@
+Synopsis
+~~~~~~~~
+::
+
+    usage: attic verify [-h] [-v] [-e PATTERN] ARCHIVE [PATH [PATH ...]]
+    
+    Verify archive consistency
+    
+    positional arguments:
+      ARCHIVE               archive to verity integrity of
+      PATH                  paths to verify
+    
+    optional arguments:
+      -h, --help            show this help message and exit
+      -v, --verbose         verbose output
+      -e PATTERN, --exclude PATTERN
+                            exclude paths matching PATTERN