Merge pull request #1388 from enkore/f/document-platforms2

Platform feature matrix

docs/development.rst

@@ -19,6 +19,16 @@ instead of 79. We do *not* use form-feed (``^L``) characters to
 separate sections either. Compliance is tested automatically when
 you run the tests.
 
+Continuous Integration
+----------------------
+
+All pull requests go through Travis-CI_, which runs the tests on Linux
+and Mac OS X as well as the flake8 style checker. Additional Unix-like platforms
+are tested on Golem_.
+
+.. _Golem: https://golem.enkore.de/view/Borg/
+.. _Travis-CI: https://travis-ci.org/borgbackup/borg
+
 Output and Logging
 ------------------
 When writing logger calls, always use correct log level (debug only for

docs/faq.rst

@@ -47,25 +47,6 @@ 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?
--------------------------------------------------
-
-    * Directories
-    * Regular files
-    * Hardlinks (considering all files in the same archive)
-    * Symlinks (stored as symlink, the symlink is not followed)
-    * Character and block device files
-    * FIFOs ("named pipes")
-    * Name
-    * Contents
-    * 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)
-    * Extended Attributes (xattrs) on Linux, OS X and FreeBSD
-    * Access Control Lists (ACL_) on Linux, OS X and FreeBSD
-    * BSD flags on OS X and FreeBSD
-
 Which file types, attributes, etc. are *not* preserved?
 -------------------------------------------------------
 

docs/installation.rst

@@ -89,6 +89,76 @@ the old version using the same steps as shown above.
 .. _pyinstaller: http://www.pyinstaller.org
 .. _releases: https://github.com/borgbackup/borg/releases
 
+.. _platforms:
+
+Features & platforms
+--------------------
+
+Besides regular file and directory structures, |project_name| can preserve
+
+    * Hardlinks (considering all files in the same archive)
+    * Symlinks (stored as symlink, the symlink is not followed)
+    * Special files:
+
+        * Character and block device files (restored via mknod)
+        * FIFOs ("named pipes")
+        * Special file *contents* can be backed up in ``--read-special`` mode.
+          By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored.
+    * Timestamps in nanosecond precision: mtime, atime, ctime
+    * Permissions:
+
+        * 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)
+
+On some platforms additional features are supported:
+
+.. Yes/No's are grouped by reason/mechanism/reference.
+
++------------------+----------+-----------+------------+
+| Platform         | ACLs     | xattr     | Flags      |
+|                  | [#acls]_ | [#xattr]_ | [#flags]_  |
++==================+==========+===========+============+
+| Linux x86        | Yes      | Yes       | No         |
++------------------+          |           |            |
+| Linux PowerPC    |          |           |            |
++------------------+          |           |            |
+| Linux ARM        |          |           |            |
++------------------+----------+-----------+------------+
+| Mac OS X         | Yes      | Yes       | Yes (all)  |
++------------------+----------+-----------+            |
+| FreeBSD          | Yes      | Yes       |            |
++------------------+----------+-----------+            |
+| OpenBSD          | n/a      | n/a       |            |
++------------------+----------+-----------+            |
+| NetBSD           | n/a      | No [2]_   |            |
++------------------+----------+-----------+------------+
+| Solaris 11       | No [3]_              | n/a        |
++------------------+                      |            |
+| OpenIndiana      |                      |            |
++------------------+----------+-----------+------------+
+| Windows (cygwin) | No [4]_  | No        | No         |
++------------------+----------+-----------+------------+
+
+Some Distributions (e.g. Debian) run additional tests after each release, these
+are not reflected here.
+
+Other Unix-like operating systems may work as well, but have not been tested at all.
+
+Note that most of the platform-dependent features also depend on the file system.
+For example, ntfs-3g on Linux isn't able to convey NTFS ACLs.
+
+
+.. [2] Feature request :issue:`1332`
+.. [3] Feature request :issue:`1337`
+.. [4] Cygwin tries to map NTFS ACLs to permissions with varying degress of success.
+
+.. [#acls] The native access control list mechanism of the OS. This normally limits access to
+    non-native ACLs. For example, NTFS ACLs aren't completely accessible on Linux with ntfs-3g.
+.. [#xattr] extended attributes; key-value pairs attached to a file, mainly used by the OS.
+    This includes resource forks on Mac OS X.
+.. [#flags] aka *BSD flags*.
+
 .. _source-install:
 
 From Source