improve docs, usage help, changelog

CHANGES

@@ -4,53 +4,65 @@ Borg Changelog
 Version <TBD>
 -------------
 
+Incompatible changes (compared to attic, fork related):
+
 - changed sw name and cli command to "borg", updated docs
-- package name and name in urls uses "borgbackup" to have less collisions
+- package name (and name in urls) uses "borgbackup" to have less collisions
 - changed repo / cache internal magic strings from ATTIC* to BORG*,
-  changed cache location to .cache/borg/
-- give specific path to xattr.is_enabled(), disable symlink setattr call that
-  always fails
-- fix misleading hint the fuse ImportError handler gave, fixes attic #237
-- source: misc. cleanups, pep8, style
-- implement check --last N
-- check: sort archives in reverse time order
+  changed cache location to .cache/borg/ - this means that it currently won't
+  accept attic repos (see issue #21 about improving that)
+
+Bug fixes:
+
 - avoid defect python-msgpack releases, fixes attic #171, fixes attic #185
-- check unpacked data from RPC for tuple type and correct length, fixes attic #127
-- less memory usage: add global option --no-cache-files
 - fix traceback when trying to do unsupported passphrase change, fixes attic #189
 - datetime does not like the year 10.000, fixes attic #139
-- docs and faq improvements, fixes, updates
-- cleanup crypto.pyx, make it easier to adapt to other modes
-- extract: if --stdout is given, write all extracted binary data to stdout
+- fix "info" all archives stats, fixes attic #183
+- fix parsing with missing microseconds, fixes attic #282
+- fix misleading hint the fuse ImportError handler gave, fixes attic #237
+- check unpacked data from RPC for tuple type and correct length, fixes attic #127
+- fix Repository._active_txn state when lock upgrade fails
+- give specific path to xattr.is_enabled(), disable symlink setattr call that
+  always fails
+- fix test setup for 32bit platforms, partial fix for attic #196
+- upgraded versioneer, PEP440 compliance, fixes attic #257
+
+New features:
+
+- less memory usage: add global option --no-cache-files
+- check --last N (only check the last N archives)
+- check: sort archives in reverse time order
+- rename repo::oldname newname (rename repository)
+- create -v output more informative
+- create --progress (backup progress indicator)
+- create --timestamp (utc string or reference file/dir)
 - create: if "-" is given as path, read binary from stdin
-- do os.fsync like recommended in the python docs
+- extract: if --stdout is given, write all extracted binary data to stdout
+- extract --sparse (simple sparse file support)
 - extra debug information for 'fread failed'
+- delete <repo> (deletes whole repo + local cache)
 - FUSE: reflect deduplication in allocated blocks
 - only allow whitelisted RPC calls in server mode
 - normalize source/exclude paths before matching
-- fix "info" all archives stats, fixes attic #183
-- implement create --timestamp, utc string or reference file/dir
-- simple sparse file support (extract --sparse)
-- fix parsing with missing microseconds, fixes attic #282
 - use posix_fadvise to not spoil the OS cache, fixes attic #252
-- source: Let chunker optionally work with os-level file descriptor.
-- source: Linux: remove duplicate os.fsencode calls
-- fix test setup for 32bit platforms, partial fix for attic #196
-- source: refactor _open_rb code a bit, so it is more consistent / regular
-- implement rename repo::oldname newname
-- implement create --progress
-- source: refactor indicator (status) and item processing
-- implement delete repo (also deletes local cache)
-- better create -v output
-- upgraded versioneer, PEP440 compliance, fixes attic #257
-- source: use py.test for better testing, flake8 for code style checks
-- source: fix tox >=2.0 compatibility
 - toplevel error handler: show tracebacks for better error analysis
 - sigusr1 / sigint handler to print current file infos - attic PR #286
-- pypi package: add python version classifiers, add FreeBSD to platforms
-- fix Repository._active_txn state when lock upgrade fails
 - RPCError: include the exception args we get from remote
 
+Other changes:
+
+- source: misc. cleanups, pep8, style
+- docs and faq improvements, fixes, updates
+- cleanup crypto.pyx, make it easier to adapt to other AES modes
+- do os.fsync like recommended in the python docs
+- source: Let chunker optionally work with os-level file descriptor.
+- source: Linux: remove duplicate os.fsencode calls
+- source: refactor _open_rb code a bit, so it is more consistent / regular
+- source: refactor indicator (status) and item processing
+- source: use py.test for better testing, flake8 for code style checks
+- source: fix tox >=2.0 compatibility (test runner)
+- pypi package: add python version classifiers, add FreeBSD to platforms
+
 
 Attic Changelog
 ===============

borg/archiver.py

@@ -515,8 +515,12 @@ Type "Yes I am sure" if you understand this and want to continue.\n""")
         parser = argparse.ArgumentParser(description='Borg %s - Deduplicated Backups' % __version__)
         subparsers = parser.add_subparsers(title='Available commands')
 
+        serve_epilog = textwrap.dedent("""
+        This command starts a repository server process. This command is usually not used manually.
+        """)
         subparser = subparsers.add_parser('serve', parents=[common_parser],
-                                          description=self.do_serve.__doc__)
+                                          description=self.do_serve.__doc__, epilog=serve_epilog,
+                                          formatter_class=argparse.RawDescriptionHelpFormatter)
         subparser.set_defaults(func=self.do_serve)
         subparser.add_argument('--restrict-to-path', dest='restrict_to_paths', action='append',
                                metavar='PATH', help='restrict repository access to PATH')

docs/faq.rst

@@ -51,7 +51,7 @@ Which file types, attributes, etc. are *not* preserved?
       recreate them in any case). So, don't panic if your backup misses a UDS!
     * The precise on-disk representation of the holes in a sparse file.
       Archive creation has no special support for sparse files, holes are
-      backed up up as (deduplicated and compressed) runs of zero bytes.
+      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.
 

docs/installation.rst

@@ -62,21 +62,19 @@ Some of the steps detailled below might be useful also for non-git installs.
     # optional: for unit testing
     apt-get install fakeroot
 
-    # install virtualenv tool, create and activate a virtual env
-    apt-get install python-virtualenv
-    virtualenv --python=python3 borg-env
-    source borg-env/bin/activate   # always do this before using!
-
-    # install some dependencies into virtual env
-    pip install cython  # to compile .pyx -> .c
-    pip install tox pytest  # optional, for running unit tests
-    pip install sphinx  # optional, to build the docs
-
     # get |project_name| from github, install it
     git clone |git_url|
+
+    apt-get install python-virtualenv
+    virtualenv --python=python3 borg-env
+    source borg-env/bin/activate   # always before using!
+
+    # install borg + dependencies into virtualenv
+    pip install cython  # compile .pyx -> .c
+    pip install tox pytest  # optional, for running unit tests
+    pip install sphinx  # optional, to build the docs
     cd borg
     pip install -e .  # in-place editable mode
 
     # optional: run all the tests, on all supported Python versions
     fakeroot -u tox
-