docs: updates and fixes

docs/development.rst

@@ -15,9 +15,8 @@ Style guide
 We generally follow `pep8
 <https://www.python.org/dev/peps/pep-0008/>`_, with 120 columns
 instead of 79. We do *not* use form-feed (``^L``) characters to
-separate sections either. The `flake8
-<https://flake8.readthedocs.org/>`_ commandline tool should be used to
-check for style errors before sending pull requests.
+separate sections either. Compliance is tested automatically when
+you run the tests.
 
 Output and Logging
 ------------------
@@ -29,7 +28,7 @@ When directly talking to the user (e.g. Y/N questions), do not use logging,
 but directly output to stderr (not: stdout, it could be connected to a pipe).
 
 To control the amount and kinds of messages output to stderr or emitted at
-info level, use flags like --stats.
+info level, use flags like ``--stats`` or ``--list``.
 
 Building a development environment
 ----------------------------------
@@ -70,7 +69,7 @@ Some more advanced examples::
 
 Important notes:
 
-- When using -- to give options to py.test, you MUST also give borg.testsuite[.module].
+- When using ``--`` to give options to py.test, you MUST also give ``borg.testsuite[.module]``.
 
 
 Regenerate usage files
@@ -120,16 +119,16 @@ The plugin `vagrant-scp` is useful to copy stuff from the VMs to the host.
 
 Usage::
 
-   To create and provision the VM:
-     vagrant up OS
-   To create an ssh session to the VM:
-     vagrant ssh OS command
-   To shut down the VM:
-     vagrant halt OS
-   To shut down and destroy the VM:
-     vagrant destroy OS
-   To copy files from the VM (in this case, the generated binary):
-     vagrant scp OS:/vagrant/borg/borg.exe .
+   # To create and provision the VM:
+   vagrant up OS
+   # To create an ssh session to the VM:
+   vagrant ssh OS command
+   # To shut down the VM:
+   vagrant halt OS
+   # To shut down and destroy the VM:
+   vagrant destroy OS
+   # To copy files from the VM (in this case, the generated binary):
+   vagrant scp OS:/vagrant/borg/borg.exe .
 
 
 Creating standalone binaries
@@ -140,7 +139,7 @@ When using the Vagrant VMs, pyinstaller will already be installed.
 
 With virtual env activated::
 
-  pip install pyinstaller>=3.0  # or git checkout master
+  pip install pyinstaller  # or git checkout master
   pyinstaller -F -n borg-PLATFORM borg/__main__.py
   for file in dist/borg-*; do gpg --armor --detach-sign $file; done
 

docs/faq.rst

@@ -26,6 +26,26 @@ repository is only modified from one place. Also keep in mind that
 |project_name| will keep an exclusive lock on the repository while creating
 or deleting archives, which may make *simultaneous* backups fail.
 
+Can I copy or synchronize my repo to another location?
+------------------------------------------------------
+
+Yes, you could just copy all the files. Make sure you do that while no
+backup is running. So what you get here is this:
+
+- client machine ---borg create---> repo1
+- repo1 ---copy---> repo2
+
+There is no special borg command to do the copying, just use cp or rsync if
+you want to do that.
+
+But think about whether that is really what you want. If something goes
+wrong in repo1, you will have the same issue in repo2 after the copy.
+
+If you want to have 2 independent backups, it is better to do it like this:
+
+- client machine ---borg create---> repo1
+- client machine ---borg create---> repo2
+
 Which file types, attributes, etc. are preserved?
 -------------------------------------------------
 
@@ -37,7 +57,7 @@ Which file types, attributes, etc. are preserved?
     * FIFOs ("named pipes")
     * Name
     * Contents
-    * Time of last modification (nanosecond precision)
+    * Timestamps in nanosecond precision: mtime, atime, ctime
     * IDs of owning user and owning group
     * Names of owning user and owning group (if the IDs can be resolved)
     * Unix Mode/Permissions (u/g/o permissions, suid, sgid, sticky)
@@ -57,6 +77,7 @@ Which file types, attributes, etc. are *not* preserved?
       backed up as (deduplicated and compressed) runs of zero bytes.
       Archive extraction has optional support to extract all-zero chunks as
       holes in a sparse file.
+    * filesystem specific attributes, like ext4 immutable bit, see :issue:`618`.
 
 Why is my backup bigger than with attic? Why doesn't |project_name| do compression by default?
 ----------------------------------------------------------------------------------------------
@@ -115,9 +136,12 @@ The borg cache eats way too much disk space, what can I do?
 -----------------------------------------------------------
 
 There is a temporary (but maybe long lived) hack to avoid using lots of disk
-space for chunks.archive.d (see issue #235 for details):
+space for chunks.archive.d (see :issue:`235` for details):
 
-    # this assumes you are working with the same user as the backup
+::
+
+    # this assumes you are working with the same user as the backup.
+    # you can get the REPOID from the "config" file inside the repository.
     cd ~/.cache/borg/<REPOID>
     rm -rf chunks.archive.d ; touch chunks.archive.d
 
@@ -136,7 +160,7 @@ This has some pros and cons, though:
   machine (if you share same backup repo between multiple machines) or if
   your local chunks cache was lost somehow.
 
-The long term plan to improve this is called "borgception", see ticket #474.
+The long term plan to improve this is called "borgception", see :issue:`474`.
 
 If a backup stops mid-way, does the already-backed-up data stay there?
 ----------------------------------------------------------------------

docs/installation.rst

@@ -77,7 +77,9 @@ make borg readable and executable for its users and then you can run ``borg``::
     sudo chown root:root /usr/local/bin/borg
     sudo chmod 755 /usr/local/bin/borg
 
-Note that the binary uses /tmp to unpack |project_name| with all dependencies. It will fail if /tmp has not enough free space or is mounted with the ``noexec`` option. You can change the temporary directory by setting the ``TEMP`` environment variable before running |project_name|.
+Note that the binary uses /tmp to unpack |project_name| with all dependencies.
+It will fail if /tmp has not enough free space or is mounted with the ``noexec`` option.
+You can change the temporary directory by setting the ``TEMP`` environment variable before running |project_name|.
 
 If a new version is released, you will have to manually download it and replace
 the old version using the same steps as shown above.

docs/internals.rst

@@ -60,8 +60,8 @@ created by some other process), lock acquisition fails.
 The cache lock is usually in `~/.cache/borg/REPOID/lock.*`.
 The repository lock is in `repository/lock.*`.
 
-In case you run into troubles with the locks, you can just delete the `lock.*`
-directory and file IF you first make sure that no |project_name| process is
+In case you run into troubles with the locks, you can use the ``borg break-lock``
+command after you first have made sure that no |project_name| process is
 running on any machine that accesses this resource. Be very careful, the cache
 or repository might get damaged if multiple processes use it at the same time.
 
@@ -181,14 +181,11 @@ Each item represents a file, directory or other fs item and is stored as an
 * mode (item type + permissions)
 * source (for links)
 * rdev (for devices)
-* mtime
+* mtime, atime, ctime in nanoseconds
 * xattrs
 * acl
 * bsdfiles
 
-``ctime`` (change time) is not stored because there is no API to set
-it and it is reset every time an inode's metadata is changed.
-
 All items are serialized using msgpack and the resulting byte stream
 is fed into the same chunker algorithm as used for regular file data
 and turned into deduplicated chunks. The reference to these chunks is then added
@@ -278,8 +275,8 @@ buckets. As a consequence the hash is just a start position for a linear
 search, and if the element is not in the table the index is linearly crossed
 until an empty bucket is found.
 
-When the hash table is filled to 75%, its size is doubled. When it's
-emptied to 25%, its size is halved. So operations on it have a variable
+When the hash table is filled to 75%, its size is grown. When it's
+emptied to 25%, its size is shrinked. So operations on it have a variable
 complexity between constant and linear with low factor, and memory overhead
 varies between 33% and 300%.
 

docs/quickstart.rst

@@ -180,7 +180,7 @@ For automated backups the passphrase can be specified using the
           :ref:`this note about password environments <password_env>`
           for more information.
 
-.. important:: The repository data is totally inaccessible without the key:**
+.. warning:: The repository data is totally inaccessible without the key:
     Make a backup copy of the key file (``keyfile`` mode) or repo config
     file (``repokey`` mode) and keep it at a safe place, so you still have
     the key in case it gets corrupted or lost.
@@ -204,9 +204,8 @@ or::
 
 Remote operations over SSH can be automated with SSH keys. You can restrict the
 use of the SSH keypair by prepending a forced command to the SSH public key in
-the remote server's authorized_keys file. Only the forced command will be run
-when the key authenticates a connection. This example will start |project_name| in server
-mode, and limit the |project_name| server to a specific filesystem path::
+the remote server's `authorized_keys` file. This example will start |project_name|
+in server mode and limit it to a specific filesystem path::
 
   command="borg serve --restrict-to-path /mnt/backup",no-pty,no-agent-forwarding,no-port-forwarding,no-X11-forwarding,no-user-rc ssh-rsa AAAAB3[...]
 

docs/support.rst

@@ -4,8 +4,8 @@
 Support
 =======
 
-Please first read the docs and existing issue tracker issues and mailing
-list posts, a lot of stuff is already documented / explained / discussed /
+Please first read the docs, the existing issue tracker issues and mailing
+list posts -- a lot of stuff is already documented / explained / discussed /
 filed there.
 
 Issue Tracker