build_usage / build_man / doc updates

docs/faq.rst

@@ -27,13 +27,7 @@ which is slower.
 Can I backup from multiple servers into a single repository?
 ------------------------------------------------------------
 
-Yes, this is *possible* from the technical standpoint, but it is
-*not recommended* from the security perspective. BorgBackup is
-built upon a defined :ref:`attack_model` that cannot provide its
-guarantees for multiple clients using the same repository. See
-:ref:`borg_security_critique` for a detailed explanation.
-
-Also, in order for the deduplication used by Borg to work, it
+In order for the deduplication used by Borg to work, it
 needs to keep a local cache containing checksums of all file
 chunks already stored in the repository. This cache is stored in
 ``~/.cache/borg/``.  If Borg detects that a repository has been
@@ -49,7 +43,7 @@ Can I back up to multiple, swapped backup targets?
 --------------------------------------------------
 
 It is possible to swap your backup disks if each backup medium is assigned its
-own repository by creating a new one with :ref:`borg_init`.
+own repository by creating a new one with :ref:`borg_rcreate`.
 
 Can I copy or synchronize my repo to another location?
 ------------------------------------------------------
@@ -57,8 +51,8 @@ Can I copy or synchronize my repo to another location?
 If you want to have redundant backup repositories (preferably at separate
 locations), the recommended way to do that is like this:
 
-- ``borg init repo1``
-- ``borg init repo2``
+- ``borg rcreate repo1``
+- ``borg rcreate repo2``
 - client machine ---borg create---> repo1
 - client machine ---borg create---> repo2
 
@@ -94,10 +88,6 @@ Also, you must not run borg against multiple instances of the same repo
   think they are identical and e.g. use the same local cache for them
   (which is an issue if they happen to be not the same).
   See :issue:`4272` for an example.
-- Encryption security issues if you would update repo and copy-of-repo
-  independently, due to AES counter reuse (when using legacy encryption modes).
-
-See also: :ref:`faq_corrupt_repo`
 
 "this is either an attack or unsafe" warning
 --------------------------------------------
@@ -118,9 +108,9 @@ you could delete the manifest-timestamp and the local cache:
 
 ::
 
-  borg config repo id   # shows the REPO_ID
+  borg config id   # shows the REPO_ID
   rm ~/.config/borg/security/REPO_ID/manifest-timestamp
-  borg delete --cache-only REPO
+  borg rdelete --cache-only
 
 This is an unsafe and unsupported way to use borg, you have been warned.
 
@@ -199,11 +189,6 @@ really desperate (e.g. if you have no completed backup of that file and you'ld
 rather get a partial file extracted than nothing). You do **not** want to give
 that option under any normal circumstances.
 
-Note that checkpoints inside files are created only since version 1.1, make
-sure you have an up-to-date version of borgbackup if you want to continue
-instead of retransferring a huge file. In some cases, there is only an outdated
-version shipped with your distribution (e.g. Debian). See :ref:`installation`.
-
 How can I backup huge file(s) over a unstable connection?
 ---------------------------------------------------------
 
@@ -241,32 +226,8 @@ then use ``tar`` to perform the comparison:
 
 ::
 
-    borg export-tar /path/to/repo::archive-name - | tar --compare -f - -C /path/to/compare/to
-
-
-.. _faq_corrupt_repo:
-
-My repository is corrupt, how can I restore from an older copy of it?
----------------------------------------------------------------------
-
-Note: this is only required for repos using legacy encryption modes.
-
-If your repositories are encrypted and have the same ID, the recommended method
-is to delete the corrupted repository, but keep its security info, and then copy
-the working repository to the same location:
-
-::
-
-    borg delete --keep-security-info /path/to/repo
-    rsync -aH /path/to/repo-working/ /path/to/repo  # Note the trailing slash.
+    borg export-tar archive-name - | tar --compare -f - -C /path/to/compare/to
 
-A plain delete command would remove the security info in
-``~/.config/borg/security``, including the nonce value. In BorgBackup
-:ref:`security_encryption` is AES-CTR, where the nonce is a counter. When the
-working repo was used later for creating new archives, Borg would re-use nonce
-values due to starting from a lower counter value given by the older copy of the
-repository. To prevent this, the ``keep-security-info`` option is applied so
-that the client-side nonce counter is kept.
 
 Can Borg add redundancy to the backup data to deal with hardware malfunction?
 -----------------------------------------------------------------------------
@@ -296,7 +257,7 @@ SMR (shingled magnetic recording) hard drives are very different from
 regular hard drives. Applications have to behave in certain ways or
 performance will be heavily degraded.
 
-Borg 1.1 ships with default settings suitable for SMR drives,
+Borg ships with default settings suitable for SMR drives,
 and has been successfully tested on *Seagate Archive v2* drives
 using the ext4 file system.
 
@@ -436,16 +397,16 @@ Say you want to prune ``/var/log`` faster than the rest of
 archive *names* and then implement different prune policies for
 different prefixes. For example, you could have a script that does::
 
-    borg create --exclude var/log $REPOSITORY:main-$(date +%Y-%m-%d) /
-    borg create $REPOSITORY:logs-$(date +%Y-%m-%d) /var/log
+    borg create --exclude var/log main-$(date +%Y-%m-%d) /
+    borg create logs-$(date +%Y-%m-%d) /var/log
 
 Then you would have two different prune calls with different policies::
 
-    borg prune --verbose --list -d 30 --prefix main- "$REPOSITORY"
-    borg prune --verbose --list -d 7  --prefix logs- "$REPOSITORY"
+    borg prune --verbose --list -d 30 --prefix main-
+    borg prune --verbose --list -d 7  --prefix logs-
 
-This will keep 7 days of logs and 30 days of everything else. Borg 1.1
-also supports the ``--glob-archives`` parameter.
+This will keep 7 days of logs and 30 days of everything else.
+Borg also supports the ``--glob-archives`` parameter.
 
 How do I remove files from an existing backup?
 ----------------------------------------------
@@ -476,37 +437,6 @@ to change them.
 Security
 ########
 
-.. _borg_security_critique:
-
-Isn't BorgBackup's legacy AES-CTR-based crypto broken?
-------------------------------------------------------
-
-Note: in borg 1.3 new AEAD cipher based modes with session keys were added,
-solving the issues of the legacy modes.
-
-If a nonce (counter) value is reused, AES-CTR mode crypto is broken.
-
-To exploit the AES counter management issue, an attacker would need to have
-access to the borg repository.
-
-By tampering with the repo, the attacker could bring the repo into a state so
-that it reports a lower "highest used counter value" than the one that actually
-was used. The client would usually notice that, because it rather trusts the
-clientside stored "highest used counter value" than trusting the server.
-
-But there are situations, where this is simply not possible:
-
-- If clients A and B used the repo, the client A can only know its own highest
-  CTR value, but not the one produced by B. That is only known to (B and) the
-  server (the repo) and thus the client A needs to trust the server about the
-  value produced by B in that situation. You can't do much about this except
-  not having multiple clients per repo.
-
-- Even if there is only one client, if client-side information is completely
-  lost (e.g. due to disk defect), the client also needs to trust the value from
-  server side. You can avoid this by not continuing to write to the repository
-  after you have lost clientside borg information.
-
 .. _home_config_borg:
 
 How important is the $HOME/.config/borg directory?
@@ -583,7 +513,7 @@ Using ``BORG_PASSCOMMAND`` with a properly permissioned file
 Using keyfile-based encryption with a blank passphrase
   It is possible to encrypt your repository in ``keyfile`` mode instead of the default
   ``repokey`` mode and use a blank passphrase for the key file (simply press Enter twice
-  when ``borg init`` asks for the password). See :ref:`encrypted_repos`
+  when ``borg rcreate`` asks for the password). See :ref:`encrypted_repos`
   for more details.
 
 Using ``BORG_PASSCOMMAND`` with macOS Keychain
@@ -717,34 +647,6 @@ Send a private email to the :ref:`security contact <security-contact>`
 if you think you have discovered a security issue.
 Please disclose security issues responsibly.
 
-How important are the nonce files?
-------------------------------------
-
-This only applies to repositories using legacy encryption modes.
-
-Borg uses :ref:`AES-CTR encryption <borg_security_critique>`. An
-essential part of AES-CTR is a sequential counter that must **never**
-repeat. If the same value of the counter is used twice in the same repository,
-an attacker can decrypt the data. The counter is stored in the home directory
-of each user ($HOME/.config/borg/security/$REPO_ID/nonce) as well as
-in the repository (/path/to/repo/nonce). When creating a new archive borg uses
-the highest of the two values. The value of the counter in the repository may be
-higher than your local value if another user has created an archive more recently
-than you did.
-
-Since the nonce is not necessary to read the data that is already encrypted,
-``borg info``, ``borg list``, ``borg extract`` and ``borg mount`` should work
-just fine without it.
-
-If the nonce file stored in the repo is lost, but you still have your local copy,
-borg will recreate the repository nonce file the next time you run ``borg create``.
-This should be safe for repositories that are only used from one user account
-on one machine.
-
-For repositories that are used by multiple users and/or from multiple machines
-it is safest to avoid running *any* commands that modify the repository after
-the nonce is deleted or if you suspect it may have been tampered with. See :ref:`attack_model`.
-
 Common issues
 #############
 
@@ -789,9 +691,9 @@ How can I deal with my very unstable SSH connection?
 If you have issues with lost connections during long-running borg commands, you
 could try to work around:
 
-- Make partial extracts like ``borg extract REPO PATTERN`` to do multiple
+- Make partial extracts like ``borg extract PATTERN`` to do multiple
   smaller extraction runs that complete before your connection has issues.
-- Try using ``borg mount REPO MOUNTPOINT`` and ``rsync -avH`` from
+- Try using ``borg mount MOUNTPOINT`` and ``rsync -avH`` from
   ``MOUNTPOINT`` to your desired extraction directory. If the connection breaks
   down, just repeat that over and over again until rsync does not find anything
   to do any more. Due to the way borg mount works, this might be less efficient
@@ -846,7 +748,7 @@ space for chunks.archive.d (see :issue:`235` for details):
 ::
 
     # this assumes you are working with the same user as the backup.
-    cd ~/.cache/borg/$(borg config /path/to/repo id)
+    cd ~/.cache/borg/$(borg config id)
     rm -rf chunks.archive.d ; touch chunks.archive.d
 
 This deletes all the cached archive chunk indexes and replaces the directory
@@ -1151,7 +1053,7 @@ To achieve this, run ``borg create`` within the mountpoint/snapshot directory:
 
     # Example: Some file system mounted in /mnt/rootfs.
     cd /mnt/rootfs
-    borg create /path/to/repo::rootfs_backup .
+    borg create rootfs_backup .
 
 
 I am having troubles with some network/FUSE/special filesystem, why?
@@ -1240,7 +1142,7 @@ This can happen for CIFS- or FUSE shares. If you are sure that your target volum
 will always have enough disk space, you can use the following workaround to disable
 checking for free disk space::
 
-    borg config -- $REPO_LOCATION additional_free_space -2T
+    borg config -- additional_free_space -2T
 
 How do I rename a repository?
 -----------------------------
@@ -1279,112 +1181,3 @@ libraries are actually loaded and used.
 In the borg git repository, there is scripts/glibc_check.py that can determine
 (based on the symbols' versions they want to link to) whether a set of given
 (Linux) binaries works with a given glibc version.
-
-
-Why was Borg forked from Attic?
--------------------------------
-
-Borg was created in May 2015 in response to the difficulty of getting new
-code or larger changes incorporated into Attic and establishing a bigger
-developer community / more open development.
-
-More details can be found in `ticket 217
-<https://github.com/jborg/attic/issues/217>`_ that led to the fork.
-
-Borg intends to be:
-
-* simple:
-
-  * as simple as possible, but no simpler
-  * do the right thing by default, but offer options
-* open:
-
-  * welcome feature requests
-  * accept pull requests of good quality and coding style
-  * give feedback on PRs that can't be accepted "as is"
-  * discuss openly, don't work in the dark
-* changing:
-
-  * Borg is not compatible with Attic
-  * do not break compatibility accidentally, without a good reason
-    or without warning. allow compatibility breaking for other cases.
-  * if major version number changes, it may have incompatible changes
-
-Migrating from Attic
-####################
-
-What are the differences between Attic and Borg?
-------------------------------------------------
-
-Borg is a fork of `Attic`_ and maintained by "`The Borg collective`_".
-
-.. _Attic: https://github.com/jborg/attic
-.. _The Borg collective: https://borgbackup.readthedocs.org/en/latest/authors.html
-
-Here's a (incomplete) list of some major changes:
-
-* lots of attic issues fixed
-  (see `issue #5 <https://github.com/borgbackup/borg/issues/5>`_),
-  including critical data corruption bugs and security issues.
-* more open, faster paced development
-  (see `issue #1 <https://github.com/borgbackup/borg/issues/1>`_)
-* less chunk management overhead (less memory and disk usage for chunks index)
-* faster remote cache resync (useful when backing up multiple machines into same repo)
-* compression: no, lz4, zstd, zlib or lzma compression, adjustable compression levels
-* repokey replaces problematic passphrase mode (you can't change the passphrase
-  nor the pbkdf2 iteration count in "passphrase" mode)
-* simple sparse file support, great for virtual machine disk files
-* can read special files (e.g. block devices) or from stdin, write to stdout
-* rename-based locking is more compatible than attic's posix locking
-* uses fadvise to not spoil / blow up the fs cache
-* better error messages / exception handling
-* better logging, screen output, progress indication
-* tested on misc. Linux systems, 32 and 64bit, FreeBSD, OpenBSD, NetBSD, macOS
-
-Please read the :ref:`changelog` (or ``docs/changes.rst`` in the source distribution) for more
-information.
-
-Borg is not compatible with original Attic (but there is a one-way conversion).
-
-How do I migrate from Attic to Borg?
-------------------------------------
-
-Use :ref:`borg_upgrade`. This is a one-way process that cannot be reversed.
-
-There are some caveats:
-
-- The upgrade can only be performed on local repositories.
-  It cannot be performed on remote repositories.
-
-- If the repository is in "keyfile" encryption mode, the keyfile must
-  exist locally or it must be manually moved after performing the upgrade:
-
-  1. Get the repository ID with ``borg config /path/to/repo id``.
-  2. Locate the attic key file at ``~/.attic/keys/``. The correct key for the
-     repository starts with the line ``ATTIC_KEY <repository id>``.
-  3. Copy the attic key file to ``~/.config/borg/keys/``
-  4. Change the first line from ``ATTIC_KEY ...`` to ``BORG_KEY ...``.
-  5. Verify that the repository is now accessible (e.g. ``borg list <repository>``).
-- Attic and Borg use different :ref:`"chunker params" <chunker-params>`.
-  This means that data added by Borg won't deduplicate with the existing data
-  stored by Attic. The effect is lessened if the files cache is used with Borg.
-- Repositories in "passphrase" mode *must* be migrated to "repokey" mode using
-  "borg key migrate-to-repokey" (only available in borg <= 1.2.x). Borg does not
-  support the "passphrase" mode in any other way.
-
-Why is my backup bigger than with attic?
-----------------------------------------
-
-Attic was rather unflexible when it comes to compression, it always
-compressed using zlib level 6 (no way to switch compression off or
-adjust the level or algorithm).
-
-The default in Borg is lz4, which is fast enough to not use significant CPU time
-in most cases, but can only achieve modest compression. It still compresses
-easily compressed data fairly well.
-
-Borg also offers zstd, zlib and lzma compression, choose wisely.
-
-Which choice is the best option depends on a number of factors, like
-bandwidth to the repository, how well the data compresses, available CPU
-power and so on.

docs/installation.rst

@@ -177,8 +177,8 @@ following dependencies first:
 * optionally, if you wish to mount an archive as a FUSE filesystem, you need
   a FUSE implementation for Python:
 
-  - Either pyfuse3_ (preferably, newer and maintained) or llfuse_ (older,
-    unmaintained now). See also the BORG_FUSE_IMPL env variable.
+  - Either pyfuse3_ (preferably, newer) or llfuse_ (older).
+    See also the BORG_FUSE_IMPL env variable.
   - See setup.py about the version requirements.
 
 If you have troubles finding the right package names, have a look at the

docs/internals/data-structures.rst

@@ -79,7 +79,7 @@ Normally the keys are computed like this::
 
   key = id = id_hash(unencrypted_data)
 
-The id_hash function depends on the :ref:`encryption mode <borg_init>`.
+The id_hash function depends on the :ref:`encryption mode <borg_rcreate>`.
 
 As the id / key is used for deduplication, id_hash must be a cryptographically
 strong hash or MAC.
@@ -736,7 +736,6 @@ The chunks cache is a key -> value mapping and contains:
 
   - reference count
   - size
-  - encrypted/compressed size
 
 The chunks cache is a HashIndex_. Due to some restrictions of HashIndex,
 the reference count of each given chunk is limited to a constant, MAX_VALUE
@@ -754,9 +753,9 @@ Here is the estimated memory usage of Borg - it's complicated::
   chunk_size ~= 2 ^ HASH_MASK_BITS  (for buzhash chunker, BLOCK_SIZE for fixed chunker)
   chunk_count ~= total_file_size / chunk_size
 
-  repo_index_usage = chunk_count * 40
+  repo_index_usage = chunk_count * 48
 
-  chunks_cache_usage = chunk_count * 44
+  chunks_cache_usage = chunk_count * 40
 
   files_cache_usage = total_file_count * 240 + chunk_count * 80
 

docs/internals/frontends.rst

@@ -208,7 +208,7 @@ Passphrase prompts should be handled differently. Use the environment variables
 and *BORG_NEW_PASSPHRASE* (see :ref:`env_vars` for reference) to pass passphrases to Borg, don't
 use the interactive passphrase prompts.
 
-When setting a new passphrase (:ref:`borg_init`, :ref:`borg_key_change-passphrase`) normally
+When setting a new passphrase (:ref:`borg_rcreate`, :ref:`borg_key_change-passphrase`) normally
 Borg prompts whether it should display the passphrase. This can be suppressed by setting
 the environment variable *BORG_DISPLAY_PASSPHRASE* to *no*.
 
@@ -252,7 +252,7 @@ last_modified
 The *encryption* key, if present, contains:
 
 mode
-    Textual encryption mode name (same as :ref:`borg_init` ``--encryption`` names)
+    Textual encryption mode name (same as :ref:`borg_rcreate` ``--encryption`` names)
 keyfile
     Path to the local key file used for access. Depending on *mode* this key may be absent.
 

docs/internals/security.rst

@@ -38,9 +38,6 @@ Under these circumstances Borg guarantees that the attacker cannot
 The attacker can always impose a denial of service per definition (he could
 forbid connections to the repository, or delete it entirely).
 
-When the above attack model is extended to include multiple clients
-independently updating the same repository, then Borg fails to provide
-confidentiality (i.e. guarantees 3) and 4) do not apply any more).
 
 .. _security_structural_auth:
 
@@ -78,7 +75,7 @@ the root node of a DAG through its edges, since the root node has no incoming ed
 
 With the scheme as described so far an attacker could easily replace the manifest,
 therefore Borg includes a tertiary authentication mechanism (TAM) that is applied
-to the manifest since version 1.0.9 (see :ref:`tam_vuln`).
+to the manifest (see :ref:`tam_vuln`).
 
 TAM works by deriving a separate key through HKDF_ from the other encryption and
 authentication keys and calculating the HMAC of the metadata to authenticate [#]_::
@@ -129,12 +126,12 @@ AEAD modes
 
 Modes: --encryption (repokey|keyfile)-[blake2-](aes-ocb|chacha20-poly1305)
 
-Supported: borg 1.3+
+Supported: borg 2.0+
 
 Encryption with these modes is based on AEAD ciphers (authenticated encryption
 with associated data) and session keys.
 
-Depending on the chosen mode (see :ref:`borg_init`) different AEAD ciphers are used:
+Depending on the chosen mode (see :ref:`borg_rcreate`) different AEAD ciphers are used:
 
 - AES-256-OCB - super fast, single-pass algorithm IF you have hw accelerated AES.
 - chacha20-poly1305 - very fast, purely software based AEAD cipher.
@@ -201,106 +198,13 @@ Legacy modes
 
 Modes: --encryption (repokey|keyfile)-[blake2]
 
-Supported: all borg versions, blake2 since 1.1
+Supported: borg < 2.0
 
-DEPRECATED. We strongly suggest you use the safer AEAD modes, see above.
+These were the AES-CTR based modes in previous borg versions.
 
-Encryption with these modes is based on the Encrypt-then-MAC construction,
-which is generally seen as the most robust way to create an authenticated
-encryption scheme from encryption and message authentication primitives.
+borg 2.0 does not support creating new repos using these modes,
+but ``borg transfer`` can still read such existing repos.
 
-Every operation (encryption, MAC / authentication, chunk ID derivation)
-uses independent, random keys generated by `os.urandom`_.
-
-Borg does not support unauthenticated encryption -- only authenticated encryption
-schemes are supported. No unauthenticated encryption schemes will be added
-in the future.
-
-Depending on the chosen mode (see :ref:`borg_init`) different primitives are used:
-
-- Legacy encryption modes use AES-256 in CTR mode. The
-  counter is added in plaintext, since it is needed for decryption,
-  and is also tracked locally on the client to avoid counter reuse.
-
-- The authentication primitive is either HMAC-SHA-256 or BLAKE2b-256
-  in a keyed mode. 
-
-  Both HMAC-SHA-256 and BLAKE2b have undergone extensive cryptanalysis  
-  and have proven secure against known attacks. The known vulnerability
-  of SHA-256 against length extension attacks does not apply to HMAC-SHA-256.
-  
-  The authentication primitive should be chosen based upon SHA hardware support.
-  With SHA hardware support, hmac-sha256 is likely to be much faster. 
-  If no hardware support is provided, Blake2b-256 will outperform hmac-sha256.
-  To find out if you have SHA hardware support, use::
-
-  $ borg benchmark cpu
-
-  The output will include an evaluation of cryptographic hashes/MACs like::
-
-  Cryptographic hashes / MACs ====================================
-  hmac-sha256              1GB        0.436s
-  blake2b-256              1GB        1.579s
-
-  Based upon your output, choose the primitive that is faster (in the above
-  example, hmac-sha256 is much faster, which indicates SHA hardware support).
-
-- The primitive used for authentication is always the same primitive
-  that is used for deriving the chunk ID, but they are always
-  used with independent keys.
-
-Encryption::
-
-    id = AUTHENTICATOR(id_key, data)
-    compressed = compress(data)
-
-    iv = reserve_iv()
-    encrypted = AES-256-CTR(enc_key, 8-null-bytes || iv, compressed)
-    authenticated = type-byte || AUTHENTICATOR(enc_hmac_key, encrypted) || iv || encrypted
-
-
-Decryption::
-
-    # Given: input *authenticated* data, possibly a *chunk-id* to assert
-    type-byte, mac, iv, encrypted = SPLIT(authenticated)
-
-    ASSERT(type-byte is correct)
-    ASSERT( CONSTANT-TIME-COMPARISON( mac, AUTHENTICATOR(enc_hmac_key, encrypted) ) )
-
-    decrypted = AES-256-CTR(enc_key, 8-null-bytes || iv, encrypted)
-    decompressed = decompress(decrypted)
-
-    ASSERT( CONSTANT-TIME-COMPARISON( chunk-id, AUTHENTICATOR(id_key, decompressed) ) )
-
-The client needs to track which counter values have been used, since
-encrypting a chunk requires a starting counter value and no two chunks
-may have overlapping counter ranges (otherwise the bitwise XOR of the
-overlapping plaintexts is revealed).
-
-The client does not directly track the counter value, because it
-changes often (with each encrypted chunk), instead it commits a
-"reservation" to the security database and the repository by taking
-the current counter value and adding 4 GiB / 16 bytes (the block size)
-to the counter. Thus the client only needs to commit a new reservation
-every few gigabytes of encrypted data.
-
-This mechanism also avoids reusing counter values in case the client
-crashes or the connection to the repository is severed, since any
-reservation would have been committed to both the security database
-and the repository before any data is encrypted. Borg uses its
-standard mechanism (SaveFile) to ensure that reservations are durable
-(on most hardware / storage systems), therefore a crash of the
-client's host would not impact tracking of reservations.
-
-However, this design is not infallible, and requires synchronization
-between clients, which is handled through the repository. Therefore in
-a multiple-client scenario a repository can trick a client into
-reusing counter values by ignoring counter reservations and replaying
-the manifest (which will fail if the client has seen a more recent
-manifest or has a more recent nonce reservation). If the repository is
-untrusted, but a trusted synchronization channel exists between
-clients, the security database could be synchronized between them over
-said trusted channel. This is not part of Borg's functionality.
 
 .. _key_encryption:
 
@@ -468,13 +372,12 @@ Compression and Encryption
 
 Combining encryption with compression can be insecure in some contexts (e.g. online protocols).
 
-There was some discussion about this in `github issue #1040`_ and for Borg some developers
+There was some discussion about this in :issue:`1040` and for Borg some developers
 concluded this is no problem at all, some concluded this is hard and extremely slow to exploit
 and thus no problem in practice.
 
 No matter what, there is always the option not to use compression if you are worried about this.
 
-.. _github issue #1040: https://github.com/borgbackup/borg/issues/1040
 
 Fingerprinting
 ==============
@@ -490,7 +393,7 @@ output of the chunker. The sizes of these stored chunks are influenced by the
 compression, encryption and authentication.
 
 buzhash chunker
-+++++++++++++++
+~~~~~~~~~~~~~~~
 
 The buzhash chunker chunks according to the input data, the chunker's
 parameters and the secret chunker seed (which all influence the chunk boundary
@@ -501,7 +404,7 @@ chunk (identical content / size as the original file), bigger files result in
 multiple chunks.
 
 fixed chunker
-+++++++++++++
+~~~~~~~~~~~~~
 
 This chunker yields fixed sized chunks, with optional support of a differently
 sized header chunk. The last chunk is not required to have the full block size

docs/man/borg-benchmark-cpu.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CPU 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-benchmark-cpu \- Benchmark CPU bound operations.
 .
 .nr rst2man-indent-level 0
 .
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-BENCHMARK-CPU" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-benchmark-cpu \- Benchmark CPU bound operations.
 .SH SYNOPSIS
 .sp
 borg [common options] benchmark cpu [options]
@@ -39,8 +39,12 @@ This command benchmarks misc. CPU bound borg operations.
 .sp
 It creates input data in memory, runs the operation and then displays throughput.
 To reduce outside influence on the timings, please make sure to run this with:
-\- an otherwise as idle as possible machine
-\- enough free memory so there will be no slow down due to paging activity
+.INDENT 0.0
+.IP \(bu 2
+an otherwise as idle as possible machine
+.IP \(bu 2
+enough free memory so there will be no slow down due to paging activity
+.UNINDENT
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.

docs/man/borg-benchmark-crud.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-BENCHMARK-CRUD" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS
 .sp
-borg [common options] benchmark crud [options] REPOSITORY PATH
+borg [common options] benchmark crud [options] PATH
 .SH DESCRIPTION
 .sp
 This command benchmarks borg CRUD (create, read, update, delete) operations.
@@ -88,9 +88,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPOSITORY
-repository to use for benchmark (must exist)
-.TP
 .B PATH
 path were to create benchmark input data
 .UNINDENT

docs/man/borg-benchmark.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-benchmark \- benchmark command
 .
 .nr rst2man-indent-level 0
 .
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-BENCHMARK" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-benchmark \- benchmark command
 .SH SYNOPSIS
 .nf
 borg [common options] benchmark crud ...

docs/man/borg-break-lock.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BREAK-LOCK 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-BREAK-LOCK" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .SH SYNOPSIS
 .sp
-borg [common options] break\-lock [options] [REPOSITORY]
+borg [common options] break\-lock [options]
 .SH DESCRIPTION
 .sp
 This command breaks the repository and cache locks.
@@ -41,12 +41,6 @@ trying to access the Cache or the Repository.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.INDENT 0.0
-.TP
-.B REPOSITORY
-repository for which to break the locks
-.UNINDENT
 .SH SEE ALSO
 .sp
 \fIborg\-common(1)\fP

docs/man/borg-check.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHECK 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-check \- Check repository consistency
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-CHECK" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-check \- Check repository consistency
 .SH SYNOPSIS
 .sp
-borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
+borg [common options] check [options]
 .SH DESCRIPTION
 .sp
 The check command verifies the consistency of a repository and the corresponding archives.
@@ -126,28 +126,25 @@ slow.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.INDENT 0.0
-.TP
-.B REPOSITORY_OR_ARCHIVE
-repository or archive to check consistency of
-.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-repository\-only
+.BI \-\-name \ NAME
+specify the archive name
+.TP
+.B  \-\-repository\-only
 only perform repository checks
 .TP
-.B \-\-archives\-only
+.B  \-\-archives\-only
 only perform archives checks
 .TP
-.B \-\-verify\-data
+.B  \-\-verify\-data
 perform cryptographic archive data integrity verification (conflicts with \fB\-\-repository\-only\fP)
 .TP
-.B \-\-repair
+.B  \-\-repair
 attempt to repair any inconsistencies found
 .TP
-.B \-\-save\-space
+.B  \-\-save\-space
 work slower, but using less space
 .TP
 .BI \-\-max\-duration \ SECONDS

docs/man/borg-common.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMMON 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-common \- Common options of Borg commands
 .
 .nr rst2man-indent-level 0
 .
@@ -30,49 +27,52 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-COMMON" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-common \- Common options of Borg commands
 .SH SYNOPSIS
 .INDENT 0.0
 .TP
-.B \-h\fP,\fB  \-\-help
+.B  \-h\fP,\fB  \-\-help
 show this help message and exit
 .TP
-.B \-\-critical
+.B  \-\-critical
 work on log level CRITICAL
 .TP
-.B \-\-error
+.B  \-\-error
 work on log level ERROR
 .TP
-.B \-\-warning
+.B  \-\-warning
 work on log level WARNING (default)
 .TP
-.B \-\-info\fP,\fB  \-v\fP,\fB  \-\-verbose
+.B  \-\-info\fP,\fB  \-v\fP,\fB  \-\-verbose
 work on log level INFO
 .TP
-.B \-\-debug
+.B  \-\-debug
 enable debug output, work on log level DEBUG
 .TP
 .BI \-\-debug\-topic \ TOPIC
 enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
 .TP
-.B \-p\fP,\fB  \-\-progress
+.B  \-p\fP,\fB  \-\-progress
 show progress information
 .TP
-.B \-\-iec
+.B  \-\-iec
 format using IEC units (1KiB = 1024B)
 .TP
-.B \-\-log\-json
+.B  \-\-log\-json
 Output one JSON object per log line instead of formatted text.
 .TP
 .BI \-\-lock\-wait \ SECONDS
 wait at most SECONDS for acquiring a repository/cache lock (default: 1).
 .TP
-.B \-\-bypass\-lock
+.B  \-\-bypass\-lock
 Bypass locking mechanism
 .TP
-.B \-\-show\-version
+.B  \-\-show\-version
 show/log the borg version
 .TP
-.B \-\-show\-rc
+.B  \-\-show\-rc
 show/log the return code (rc)
 .TP
 .BI \-\-umask \ M
@@ -93,7 +93,7 @@ deprecated, use \fB\-\-upload\-buffer\fP instead
 .BI \-\-upload\-buffer \ UPLOAD_BUFFER
 set network upload buffer size in MiB. (default: 0=no buffer)
 .TP
-.B \-\-consider\-part\-files
+.B  \-\-consider\-part\-files
 treat part files like normal files (e.g. to list/extract them)
 .TP
 .BI \-\-debug\-profile \ FILE
@@ -101,6 +101,9 @@ Write execution profile in Borg format into FILE. For local use a Python\-compat
 .TP
 .BI \-\-rsh \ RSH
 Use this command to connect to the \(aqborg serve\(aq process (default: \(aqssh\(aq)
+.TP
+.BI \-r \ REPO\fR,\fB \ \-\-repo \ REPO
+repository to use
 .UNINDENT
 .SH SEE ALSO
 .sp

docs/man/borg-compact.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPACT 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-compact \- compact segment files in the repository
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-COMPACT" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-compact \- compact segment files in the repository
 .SH SYNOPSIS
 .sp
-borg [common options] compact [options] [REPOSITORY]
+borg [common options] compact [options]
 .SH DESCRIPTION
 .sp
 This command frees repository space by compacting segments.
@@ -60,16 +60,10 @@ See \fIseparate_compaction\fP in Additional Notes for more details.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.INDENT 0.0
-.TP
-.B REPOSITORY
-repository to compact
-.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-cleanup\-commits
+.B  \-\-cleanup\-commits
 cleanup commit\-only 17\-byte segment files
 .TP
 .BI \-\-threshold \ PERCENT
@@ -82,10 +76,7 @@ set minimum threshold for saved space in PERCENT (Default: 10)
 .nf
 .ft C
 # compact segments and free repo disk space
-$ borg compact /path/to/repo
-
-# same as above plus clean up 17byte commit\-only segments
-$ borg compact \-\-cleanup\-commits /path/to/repo
+$ borg compact
 .ft P
 .fi
 .UNINDENT

docs/man/borg-compression.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPRESSION 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-compression \- Details regarding compression
 .
 .nr rst2man-indent-level 0
 .
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-COMPRESSION" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-compression \- Details regarding compression
 .SH DESCRIPTION
 .sp
 It is no problem to mix different compression methods in one repo,

docs/man/borg-config.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CONFIG 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-config \- get, set, and delete values in a repository or cache config file
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-CONFIG" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-config \- get, set, and delete values in a repository or cache config file
 .SH SYNOPSIS
 .sp
-borg [common options] config [options] [REPOSITORY] [NAME] [VALUE]
+borg [common options] config [options] [NAME] [VALUE]
 .SH DESCRIPTION
 .sp
 This command gets and sets options in a local repository or cache config file.
@@ -53,9 +53,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPOSITORY
-repository to configure
-.TP
 .B NAME
 name of config key
 .TP
@@ -65,13 +62,13 @@ new value for key
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-c\fP,\fB  \-\-cache
+.B  \-c\fP,\fB  \-\-cache
 get and set values from the repo cache
 .TP
-.B \-d\fP,\fB  \-\-delete
+.B  \-d\fP,\fB  \-\-delete
 delete the key from the config file
 .TP
-.B \-l\fP,\fB  \-\-list
+.B  \-l\fP,\fB  \-\-list
 list the configuration of the repo
 .UNINDENT
 .SH EXAMPLES
@@ -90,13 +87,13 @@ making changes!
 .nf
 .ft C
 # find cache directory
-$ cd ~/.cache/borg/$(borg config /path/to/repo id)
+$ cd ~/.cache/borg/$(borg config id)
 
 # reserve some space
-$ borg config /path/to/repo additional_free_space 2G
+$ borg config additional_free_space 2G
 
 # make a repo append\-only
-$ borg config /path/to/repo append_only 1
+$ borg config append_only 1
 .ft P
 .fi
 .UNINDENT

docs/man/borg-create.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-create \- Create new archive
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-CREATE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-create \- Create new archive
 .SH SYNOPSIS
 .sp
-borg [common options] create [options] ARCHIVE [PATH...]
+borg [common options] create [options] NAME [PATH...]
 .SH DESCRIPTION
 .sp
 This command creates a backup archive containing all files found while recursively
@@ -126,8 +126,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B ARCHIVE
-name of archive to create (must be also a valid directory name)
+.B NAME
+specify the archive name
 .TP
 .B PATH
 paths to archive
@@ -135,22 +135,22 @@ paths to archive
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-n\fP,\fB  \-\-dry\-run
+.B  \-n\fP,\fB  \-\-dry\-run
 do not create a backup archive
 .TP
-.B \-s\fP,\fB  \-\-stats
+.B  \-s\fP,\fB  \-\-stats
 print statistics for the created archive
 .TP
-.B \-\-list
+.B  \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
 .BI \-\-filter \ STATUSCHARS
 only display items with the given status characters (see description)
 .TP
-.B \-\-json
+.B  \-\-json
 output stats as JSON. Implies \fB\-\-stats\fP\&.
 .TP
-.B \-\-no\-cache\-sync
+.B  \-\-no\-cache\-sync
 experimental: do not synchronize the cache. Implies not using the files cache.
 .TP
 .BI \-\-stdin\-name \ NAME
@@ -160,18 +160,18 @@ use NAME in archive for stdin data (default: \(aqstdin\(aq)
 set user USER in archive for stdin data (default: \(aqroot\(aq)
 .TP
 .BI \-\-stdin\-group \ GROUP
-set group GROUP in archive for stdin data (default: \(aqroot\(aq)
+set group GROUP in archive for stdin data (default: \(aqwheel\(aq)
 .TP
 .BI \-\-stdin\-mode \ M
 set mode to M in archive for stdin data (default: 0660)
 .TP
-.B \-\-content\-from\-command
+.B  \-\-content\-from\-command
 interpret PATH as command and store its stdout. See also section Reading from stdin below.
 .TP
-.B \-\-paths\-from\-stdin
+.B  \-\-paths\-from\-stdin
 read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories.
 .TP
-.B \-\-paths\-from\-command
+.B  \-\-paths\-from\-command
 interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP
 .TP
 .BI \-\-paths\-delimiter \ DELIM
@@ -192,61 +192,61 @@ include/exclude paths matching PATTERN
 .BI \-\-patterns\-from \ PATTERNFILE
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
-.B \-\-exclude\-caches
+.B  \-\-exclude\-caches
 exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
 .TP
-.B \-\-keep\-exclude\-tags
+.B  \-\-keep\-exclude\-tags
 if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .TP
-.B \-\-exclude\-nodump
+.B  \-\-exclude\-nodump
 exclude files flagged NODUMP
 .UNINDENT
 .SS Filesystem options
 .INDENT 0.0
 .TP
-.B \-x\fP,\fB  \-\-one\-file\-system
+.B  \-x\fP,\fB  \-\-one\-file\-system
 stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
 .TP
-.B \-\-numeric\-owner
+.B  \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B \-\-numeric\-ids
+.B  \-\-numeric\-ids
 only store numeric user and group identifiers
 .TP
-.B \-\-noatime
+.B  \-\-noatime
 do not store atime into archive
 .TP
-.B \-\-atime
+.B  \-\-atime
 do store atime into archive
 .TP
-.B \-\-noctime
+.B  \-\-noctime
 do not store ctime into archive
 .TP
-.B \-\-nobirthtime
+.B  \-\-nobirthtime
 do not store birthtime (creation date) into archive
 .TP
-.B \-\-nobsdflags
+.B  \-\-nobsdflags
 deprecated, use \fB\-\-noflags\fP instead
 .TP
-.B \-\-noflags
+.B  \-\-noflags
 do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive
 .TP
-.B \-\-noacls
+.B  \-\-noacls
 do not read and store ACLs into archive
 .TP
-.B \-\-noxattrs
+.B  \-\-noxattrs
 do not read and store xattrs into archive
 .TP
-.B \-\-sparse
+.B  \-\-sparse
 detect sparse holes in input (supported only by fixed chunker)
 .TP
 .BI \-\-files\-cache \ MODE
 operate files cache in MODE. default: ctime,size,inode
 .TP
-.B \-\-read\-special
+.B  \-\-read\-special
 open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
 .UNINDENT
 .SS Archive options
@@ -274,86 +274,84 @@ select compression algorithm, see the output of the "borg help compression" comm
 .nf
 .ft C
 # Backup ~/Documents into an archive named "my\-documents"
-$ borg create /path/to/repo::my\-documents ~/Documents
+$ borg create my\-documents ~/Documents
 
 # same, but list all files as we process them
-$ borg create \-\-list /path/to/repo::my\-documents ~/Documents
+$ borg create \-\-list my\-documents ~/Documents
 
 # Backup ~/Documents and ~/src but exclude pyc files
-$ borg create /path/to/repo::my\-files \e
+$ borg create my\-files                \e
     ~/Documents                       \e
     ~/src                             \e
     \-\-exclude \(aq*.pyc\(aq
 
 # Backup home directories excluding image thumbnails (i.e. only
 # /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
-$ borg create /path/to/repo::my\-files /home \e
-    \-\-exclude \(aqsh:/home/*/.thumbnails\(aq
+$ borg create my\-files /home \-\-exclude \(aqsh:home/*/.thumbnails\(aq
 
 # Backup the root filesystem into an archive named "root\-YYYY\-MM\-DD"
 # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio)
-$ borg create \-C zlib,6 \-\-one\-file\-system /path/to/repo::root\-{now:%Y\-%m\-%d} /
+$ borg create \-C zlib,6 \-\-one\-file\-system root\-{now:%Y\-%m\-%d} /
 
-# Backup onto a remote host ("push" style) via ssh to port 2222,
-# logging in as user "borg" and storing into /path/to/repo
-$ borg create ssh://borg@backup.example.org:2222/path/to/repo::{fqdn}\-root\-{now} /
+# Backup into an archive name like FQDN\-root\-TIMESTAMP
+$ borg create \(aq{fqdn}\-root\-{now}\(aq /
 
 # Backup a remote host locally ("pull" style) using sshfs
 $ mkdir sshfs\-mount
 $ sshfs root@example.com:/ sshfs\-mount
 $ cd sshfs\-mount
-$ borg create /path/to/repo::example.com\-root\-{now:%Y\-%m\-%d} .
+$ borg create example.com\-root\-{now:%Y\-%m\-%d} .
 $ cd ..
 $ fusermount \-u sshfs\-mount
 
 # Make a big effort in fine granular deduplication (big chunk management
 # overhead, needs a lot of RAM and disk space, see formula in internals
 # docs \- same parameters as borg < 1.0 or attic):
-$ borg create \-\-chunker\-params buzhash,10,23,16,4095 /path/to/repo::small /smallstuff
+$ borg create \-\-chunker\-params buzhash,10,23,16,4095 small /smallstuff
 
 # Backup a raw device (must not be active/in use/mounted at that time)
-$ borg create \-\-read\-special \-\-chunker\-params fixed,4194304 /path/to/repo::my\-sdx /dev/sdX
+$ borg create \-\-read\-special \-\-chunker\-params fixed,4194304 my\-sdx /dev/sdX
 
 # Backup a sparse disk image (must not be active/in use/mounted at that time)
-$ borg create \-\-sparse \-\-chunker\-params fixed,4194304 /path/to/repo::my\-disk my\-disk.raw
+$ borg create \-\-sparse \-\-chunker\-params fixed,4194304 my\-disk my\-disk.raw
 
 # No compression (none)
-$ borg create \-\-compression none /path/to/repo::arch ~
+$ borg create \-\-compression none arch ~
 
 # Super fast, low compression (lz4, default)
-$ borg create /path/to/repo::arch ~
+$ borg create arch ~
 
 # Less fast, higher compression (zlib, N = 0..9)
-$ borg create \-\-compression zlib,N /path/to/repo::arch ~
+$ borg create \-\-compression zlib,N arch ~
 
 # Even slower, even higher compression (lzma, N = 0..9)
-$ borg create \-\-compression lzma,N /path/to/repo::arch ~
+$ borg create \-\-compression lzma,N arch ~
 
 # Only compress compressible data with lzma,N (N = 0..9)
-$ borg create \-\-compression auto,lzma,N /path/to/repo::arch ~
+$ borg create \-\-compression auto,lzma,N arch ~
 
 # Use short hostname, user name and current time in archive name
-$ borg create /path/to/repo::{hostname}\-{user}\-{now} ~
+$ borg create \(aq{hostname}\-{user}\-{now}\(aq ~
 # Similar, use the same datetime format that is default as of borg 1.1
-$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S} ~
+$ borg create \(aq{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S}\(aq ~
 # As above, but add nanoseconds
-$ borg create /path/to/repo::{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f} ~
+$ borg create \(aq{hostname}\-{user}\-{now:%Y\-%m\-%dT%H:%M:%S.%f}\(aq ~
 
 # Backing up relative paths by moving into the correct directory first
 $ cd /home/user/Documents
 # The root directory of the archive will be "projectA"
-$ borg create /path/to/repo::daily\-projectA\-{now:%Y\-%m\-%d} projectA
+$ borg create \(aqdaily\-projectA\-{now:%Y\-%m\-%d}\(aq projectA
 
 # Use external command to determine files to archive
 # Use \-\-paths\-from\-stdin with find to only backup files less than 1MB in size
-$ find ~ \-size \-1000k | borg create \-\-paths\-from\-stdin /path/to/repo::small\-files\-only
+$ find ~ \-size \-1000k | borg create \-\-paths\-from\-stdin small\-files\-only
 # Use \-\-paths\-from\-command with find to only backup files from a given user
-$ borg create \-\-paths\-from\-command /path/to/repo::joes\-files \-\- find /srv/samba/shared \-user joe
+$ borg create \-\-paths\-from\-command joes\-files \-\- find /srv/samba/shared \-user joe
 # Use \-\-paths\-from\-stdin with \-\-paths\-delimiter (for example, for filenames with newlines in them)
 $ find ~ \-size \-1000k \-print0 | borg create \e
     \-\-paths\-from\-stdin \e
     \-\-paths\-delimiter "\e0" \e
-    /path/to/repo::smallfiles\-handle\-newline
+    smallfiles\-handle\-newline
 .ft P
 .fi
 .UNINDENT

docs/man/borg-delete.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-delete \- Delete an existing repository or archives
 .
 .nr rst2man-indent-level 0
 .
@@ -30,21 +27,19 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-DELETE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-delete \- Delete archives
 .SH SYNOPSIS
 .sp
-borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...]
+borg [common options] delete [options]
 .SH DESCRIPTION
 .sp
-This command deletes an archive from the repository or the complete repository.
+This command deletes archives from the repository.
 .sp
 Important: When deleting archives, repository disk space is \fBnot\fP freed until
 you run \fBborg compact\fP\&.
 .sp
-When you delete a complete repository, the security info and local cache for it
-(if any) are also deleted. Alternatively, you can delete just the local cache
-with the \fB\-\-cache\-only\fP option, or keep the security info with the
-\fB\-\-keep\-security\-info\fP option.
-.sp
 When in doubt, use \fB\-\-dry\-run \-\-list\fP to see what would be deleted.
 .sp
 When using \fB\-\-stats\fP, you will get some statistics about how much data was
@@ -58,43 +53,35 @@ pattern to match multiple archives using the \fB\-\-glob\-archives GLOB\fP optio
 (for more info on these patterns, see \fIborg_patterns\fP). Note that these
 two options are mutually exclusive.
 .sp
-To avoid accidentally deleting archives, especially when using glob patterns,
-it might be helpful to use the \fB\-\-dry\-run\fP to test out the command without
-actually making any changes to the repository.
+Always first use \fB\-\-dry\-run \-\-list\fP to see what would be deleted.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.INDENT 0.0
-.TP
-.B REPOSITORY_OR_ARCHIVE
-repository or archive to delete
-.TP
-.B ARCHIVE
-archives to delete
-.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-n\fP,\fB  \-\-dry\-run
+.B  \-n\fP,\fB  \-\-dry\-run
 do not change repository
 .TP
-.B \-\-list
+.B  \-\-list
 output verbose list of archives
 .TP
-.B \-s\fP,\fB  \-\-stats
+.B  \-\-consider\-checkpoints
+consider checkpoint archives for deletion (default: not considered).
+.TP
+.B  \-s\fP,\fB  \-\-stats
 print statistics for the deleted archive
 .TP
-.B \-\-cache\-only
+.B  \-\-cache\-only
 delete only the local cache for the given repository
 .TP
-.B \-\-force
+.B  \-\-force
 force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
 .TP
-.B \-\-keep\-security\-info
+.B  \-\-keep\-security\-info
 keep the local security info when deleting a repository
 .TP
-.B \-\-save\-space
+.B  \-\-save\-space
 work slower, but using less space
 .UNINDENT
 .SS Archive filters
@@ -122,26 +109,18 @@ consider last N archives after other filters were applied
 .nf
 .ft C
 # delete a single backup archive:
-$ borg delete /path/to/repo::Monday
+$ borg delete Monday
 # actually free disk space:
-$ borg compact /path/to/repo
+$ borg compact
 
 # delete all archives whose names begin with the machine\(aqs hostname followed by "\-"
-$ borg delete \-\-prefix \(aq{hostname}\-\(aq /path/to/repo
+$ borg delete \-\-prefix \(aq{hostname}\-\(aq
 
 # delete all archives whose names contain "\-2012\-"
-$ borg delete \-\-glob\-archives \(aq*\-2012\-*\(aq /path/to/repo
+$ borg delete \-a \(aq*\-2012\-*\(aq
 
 # see what would be deleted if delete was run without \-\-dry\-run
-$ borg delete \-\-list \-\-dry\-run \-a \(aq*\-May\-*\(aq /path/to/repo
-
-# delete the whole repository and the related local cache:
-$ borg delete /path/to/repo
-You requested to completely DELETE the repository *including* all archives it contains:
-repo                                 Mon, 2016\-02\-15 19:26:54
-root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
-newname                              Mon, 2016\-02\-15 19:50:19
-Type \(aqYES\(aq if you understand this and want to continue: YES
+$ borg delete \-\-list \-\-dry\-run \-a \(aq*\-May\-*\(aq
 .ft P
 .fi
 .UNINDENT

docs/man/borg-diff.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DIFF 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-diff \- Diff contents of two archives
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-DIFF" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-diff \- Diff contents of two archives
 .SH SYNOPSIS
 .sp
-borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
+borg [common options] diff [options] ARCHIVE1 ARCHIVE2 [PATH...]
 .SH DESCRIPTION
 .sp
 This command finds differences (file contents, user/group/mode) between archives.
@@ -57,11 +57,11 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPO::ARCHIVE1
-repository location and ARCHIVE1 name
+.B ARCHIVE1
+ARCHIVE1 name
 .TP
 .B ARCHIVE2
-ARCHIVE2 name (no repository location allowed)
+ARCHIVE2 name
 .TP
 .B PATH
 paths of items inside the archives to compare; patterns are supported
@@ -69,19 +69,19 @@ paths of items inside the archives to compare; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-numeric\-owner
+.B  \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B \-\-numeric\-ids
+.B  \-\-numeric\-ids
 only consider numeric user and group identifiers
 .TP
-.B \-\-same\-chunker\-params
+.B  \-\-same\-chunker\-params
 Override check of chunker parameters.
 .TP
-.B \-\-sort
+.B  \-\-sort
 Sort the output lines by file path.
 .TP
-.B \-\-json\-lines
+.B  \-\-json\-lines
 Format output as JSON Lines.
 .UNINDENT
 .SS Exclusion options
@@ -105,44 +105,17 @@ read include/exclude patterns from PATTERNFILE, one per line
 .sp
 .nf
 .ft C
-$ borg init \-e=none testrepo
-$ mkdir testdir
-$ cd testdir
-$ echo asdf > file1
-$ dd if=/dev/urandom bs=1M count=4 > file2
-$ touch file3
-$ borg create ../testrepo::archive1 .
-
-$ chmod a+x file1
-$ echo "something" >> file2
-$ borg create ../testrepo::archive2 .
-
-$ echo "testing 123" >> file1
-$ rm file3
-$ touch file4
-$ borg create ../testrepo::archive3 .
-
-$ cd ..
-$ borg diff testrepo::archive1 archive2
-[\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
-   +135 B    \-252 B file2
-
-$ borg diff testrepo::archive2 archive3
-    +17 B      \-5 B file1
-added           0 B file4
-removed         0 B file3
-
-$ borg diff testrepo::archive1 archive3
+$ borg diff archive1 archive2
     +17 B      \-5 B [\-rw\-r\-\-r\-\- \-> \-rwxr\-xr\-x] file1
    +135 B    \-252 B file2
 added           0 B file4
 removed         0 B file3
 
-$ borg diff \-\-json\-lines testrepo::archive1 archive3
+$ borg diff archive1 archive2
 {"path": "file1", "changes": [{"type": "modified", "added": 17, "removed": 5}, {"type": "mode", "old_mode": "\-rw\-r\-\-r\-\-", "new_mode": "\-rwxr\-xr\-x"}]}
 {"path": "file2", "changes": [{"type": "modified", "added": 135, "removed": 252}]}
 {"path": "file4", "changes": [{"type": "added", "size": 0}]}
-{"path": "file3", "changes": [{"type": "removed", "size": 0}]
+{"path": "file3", "changes": [{"type": "removed", "size": 0}]}
 .ft P
 .fi
 .UNINDENT

docs/man/borg-export-tar.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-export-tar \- Export archive contents as a tarball
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-EXPORT-TAR" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-export-tar \- Export archive contents as a tarball
 .SH SYNOPSIS
 .sp
-borg [common options] export\-tar [options] ARCHIVE FILE [PATH...]
+borg [common options] export\-tar [options] NAME FILE [PATH...]
 .SH DESCRIPTION
 .sp
 This command creates a tarball from an archive.
@@ -115,8 +115,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B ARCHIVE
-archive to export
+.B NAME
+specify the archive name
 .TP
 .B FILE
 output tar file. "\-" to write to stdout instead.
@@ -127,10 +127,10 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-tar\-filter
+.B  \-\-tar\-filter
 filter program to pipe data through
 .TP
-.B \-\-list
+.B  \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
 .BI \-\-tar\-format \ FMT

docs/man/borg-extract.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-extract \- Extract archive contents
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-EXTRACT" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-extract \- Extract archive contents
 .SH SYNOPSIS
 .sp
-borg [common options] extract [options] ARCHIVE [PATH...]
+borg [common options] extract [options] NAME [PATH...]
 .SH DESCRIPTION
 .sp
 This command extracts the contents of an archive. By default the entire
@@ -66,8 +66,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B ARCHIVE
-archive to extract
+.B NAME
+specify the archive name
 .TP
 .B PATH
 paths to extract; patterns are supported
@@ -75,34 +75,34 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-list
+.B  \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
-.B \-n\fP,\fB  \-\-dry\-run
+.B  \-n\fP,\fB  \-\-dry\-run
 do not actually change any files
 .TP
-.B \-\-numeric\-owner
+.B  \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B \-\-numeric\-ids
+.B  \-\-numeric\-ids
 only obey numeric user and group identifiers
 .TP
-.B \-\-nobsdflags
+.B  \-\-nobsdflags
 deprecated, use \fB\-\-noflags\fP instead
 .TP
-.B \-\-noflags
+.B  \-\-noflags
 do not extract/set flags (e.g. NODUMP, IMMUTABLE)
 .TP
-.B \-\-noacls
+.B  \-\-noacls
 do not extract/set ACLs
 .TP
-.B \-\-noxattrs
+.B  \-\-noxattrs
 do not extract/set xattrs
 .TP
-.B \-\-stdout
+.B  \-\-stdout
 write all extracted data to stdout
 .TP
-.B \-\-sparse
+.B  \-\-sparse
 create holes in output sparse file from all\-zero chunks
 .UNINDENT
 .SS Exclusion options
@@ -130,22 +130,22 @@ Remove the specified number of leading path elements. Paths with fewer elements
 .nf
 .ft C
 # Extract entire archive
-$ borg extract /path/to/repo::my\-files
+$ borg extract my\-files
 
 # Extract entire archive and list files while processing
-$ borg extract \-\-list /path/to/repo::my\-files
+$ borg extract \-\-list my\-files
 
 # Verify whether an archive could be successfully extracted, but do not write files to disk
-$ borg extract \-\-dry\-run /path/to/repo::my\-files
+$ borg extract \-\-dry\-run my\-files
 
 # Extract the "src" directory
-$ borg extract /path/to/repo::my\-files home/USERNAME/src
+$ borg extract my\-files home/USERNAME/src
 
 # Extract the "src" directory but exclude object files
-$ borg extract /path/to/repo::my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
+$ borg extract my\-files home/USERNAME/src \-\-exclude \(aq*.o\(aq
 
 # Restore a raw device (must not be active/in use/mounted at that time)
-$ borg extract \-\-stdout /path/to/repo::my\-sdx | dd of=/dev/sdx bs=10M
+$ borg extract \-\-stdout my\-sdx | dd of=/dev/sdx bs=10M
 .ft P
 .fi
 .UNINDENT

docs/man/borg-import-tar.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-IMPORT-TAR 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-import-tar \- Create a backup archive from a tarball
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-IMPORT-TAR" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-import-tar \- Create a backup archive from a tarball
 .SH SYNOPSIS
 .sp
-borg [common options] import\-tar [options] ARCHIVE TARFILE
+borg [common options] import\-tar [options] NAME TARFILE
 .SH DESCRIPTION
 .sp
 This command creates a backup archive from a tarball.
@@ -86,8 +86,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B ARCHIVE
-name of archive to create (must be also a valid directory name)
+.B NAME
+specify the archive name
 .TP
 .B TARFILE
 input tar file. "\-" to read from stdin instead.
@@ -95,19 +95,19 @@ input tar file. "\-" to read from stdin instead.
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-tar\-filter
+.B  \-\-tar\-filter
 filter program to pipe data through
 .TP
-.B \-s\fP,\fB  \-\-stats
+.B  \-s\fP,\fB  \-\-stats
 print statistics for the created archive
 .TP
-.B \-\-list
+.B  \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
 .BI \-\-filter \ STATUSCHARS
 only display items with the given status characters
 .TP
-.B \-\-json
+.B  \-\-json
 output stats as JSON (implies \-\-stats)
 .UNINDENT
 .SS Archive options
@@ -135,25 +135,25 @@ select compression algorithm, see the output of the "borg help compression" comm
 .nf
 .ft C
 # export as uncompressed tar
-$ borg export\-tar /path/to/repo::Monday Monday.tar
+$ borg export\-tar Monday Monday.tar
 
 # import an uncompressed tar
-$ borg import\-tar /path/to/repo::Monday Monday.tar
+$ borg import\-tar Monday Monday.tar
 
 # exclude some file types, compress using gzip
-$ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
+$ borg export\-tar Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq
 
 # use higher compression level with gzip
-$ borg export\-tar \-\-tar\-filter="gzip \-9" repo::Monday Monday.tar.gz
+$ borg export\-tar \-\-tar\-filter="gzip \-9" Monday Monday.tar.gz
 
 # copy an archive from repoA to repoB
-$ borg export\-tar \-\-tar\-format=BORG repoA::archive \- | borg import\-tar repoB::archive \-
+$ borg \-r repoA export\-tar \-\-tar\-format=BORG archive \- | borg \-r repoB import\-tar archive \-
 
 # export a tar, but instead of storing it on disk, upload it to remote site using curl
-$ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
+$ borg export\-tar Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST
 
 # remote extraction via "tarpipe"
-$ borg export\-tar /path/to/repo::Monday \- | ssh somewhere "cd extracted; tar x"
+$ borg export\-tar Monday \- | ssh somewhere "cd extracted; tar x"
 .ft P
 .fi
 .UNINDENT
@@ -166,9 +166,9 @@ Outputs a script that copies all archives from repo1 to repo2:
 .sp
 .nf
 .ft C
-for A T in \(gaborg list \-\-format=\(aq{archive} {time:%Y\-%m\-%dT%H:%M:%S}{LF}\(aq repo1\(ga
+for A T in \(gaborg list \-\-format=\(aq{archive} {time:%Y\-%m\-%dT%H:%M:%S}{LF}\(aq\(ga
 do
-  echo "borg export\-tar \-\-tar\-format=BORG repo1::$A \- | borg import\-tar \-\-timestamp=$T repo2::$A \-"
+  echo "borg \-r repo1 export\-tar \-\-tar\-format=BORG $A \- | borg \-r repo2 import\-tar \-\-timestamp=$T $A \-"
 done
 .ft P
 .fi

docs/man/borg-info.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INFO 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-info \- Show archive details such as disk space used
 .
 .nr rst2man-indent-level 0
 .
@@ -30,12 +27,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-INFO" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-info \- Show archive details such as disk space used
 .SH SYNOPSIS
 .sp
-borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
+borg [common options] info [options]
 .SH DESCRIPTION
 .sp
-This command displays detailed information about the specified archive or repository.
+This command displays detailed information about the specified archive.
 .sp
 Please note that the deduplicated sizes of the individual archives do not add
 up to the deduplicated size of the repository ("all archives"), because the two
@@ -53,16 +53,10 @@ This is shown as \fIutilization of maximum supported archive size\fP\&.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.INDENT 0.0
-.TP
-.B REPOSITORY_OR_ARCHIVE
-repository or archive to display information about
-.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-json
+.B  \-\-json
 format output as JSON
 .UNINDENT
 .SS Archive filters
@@ -89,58 +83,20 @@ consider last N archives after other filters were applied
 .sp
 .nf
 .ft C
-$ borg info /path/to/repo::2017\-06\-29T11:00\-srv
-Archive name: 2017\-06\-29T11:00\-srv
-Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
-Comment:
-Hostname: myhostname
-Username: root
-Time (start): Thu, 2017\-06\-29 11:03:07
-Time (end): Thu, 2017\-06\-29 11:03:13
-Duration: 5.66 seconds
-Number of files: 17037
-Command line: /usr/sbin/borg create /path/to/repo::2017\-06\-29T11:00\-srv /srv
-Utilization of max. archive size: 0%
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-                       Original size      Compressed size    Deduplicated size
-This archive:               12.53 GB             12.49 GB              1.62 kB
-All archives:              121.82 TB            112.41 TB            215.42 GB
-
-                       Unique chunks         Total chunks
-Chunk index:                 1015213            626934122
-
-$ borg info /path/to/repo \-\-last 1
-Archive name: 2017\-06\-29T11:00\-srv
-Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
+$ borg info Tuesday2022\-06\-25T20:51:39
+Archive name: Tuesday2022\-06\-25T20:51:39
+Archive fingerprint: f7dea0788dfc026cc2be1c0f5b94beb4e4084eb3402fc40c38d8719b1bf2d943
 Comment:
-Hostname: myhostname
-Username: root
-Time (start): Thu, 2017\-06\-29 11:03:07
-Time (end): Thu, 2017\-06\-29 11:03:13
-Duration: 5.66 seconds
-Number of files: 17037
-Command line: /usr/sbin/borg create /path/to/repo::2017\-06\-29T11:00\-srv /srv
-Utilization of max. archive size: 0%
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-                       Original size      Compressed size    Deduplicated size
-This archive:               12.53 GB             12.49 GB              1.62 kB
-All archives:              121.82 TB            112.41 TB            215.42 GB
-
-                       Unique chunks         Total chunks
-Chunk index:                 1015213            626934122
-
-$ borg info /path/to/repo
-Repository ID: d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
-Location: /path/to/repo
-Encrypted: Yes (repokey)
-Cache: /root/.cache/borg/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
-Security dir: /root/.config/borg/security/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-                       Original size      Compressed size    Deduplicated size
-All archives:              121.82 TB            112.41 TB            215.42 GB
-
-                       Unique chunks         Total chunks
-Chunk index:                 1015213            626934122
+Hostname: mba2020
+Username: tw
+Time (start): Sat, 2022\-06\-25 20:51:40
+Time (end): Sat, 2022\-06\-25 20:51:40
+Duration: 0.03 seconds
+Command line: /Users/tw/w/borg\-env/bin/borg \-r path/to/repo create \-\-stats \(aqTuesday{now}\(aq src \-\-progress
+Utilization of maximum supported archive size: 0%
+Number of files: 244
+Original size: 13.80 MB
+Deduplicated size: 531 B
 .ft P
 .fi
 .UNINDENT

docs/man/borg-key-change-algorithm.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-ALGORITHM 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-key-change-algorithm \- Change repository key algorithm
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-KEY-CHANGE-ALGORITHM" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-key-change-algorithm \- Change repository key algorithm
 .SH SYNOPSIS
 .sp
-borg [common options] key change\-algorithm [options] [REPOSITORY] ALGORITHM
+borg [common options] key change\-algorithm [options] ALGORITHM
 .SH DESCRIPTION
 .sp
 Change the algorithm we use to encrypt and authenticate the borg key.
@@ -77,8 +77,6 @@ borg key change\-algorithm /path/to/repo pbkdf2
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
-.sp
-REPOSITORY
 .INDENT 0.0
 .TP
 .B ALGORITHM

docs/man/borg-key-change-location.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-LOCATION 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-key-change-location \- Change repository key location
 .
 .nr rst2man-indent-level 0
 .
@@ -30,26 +27,30 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-KEY-CHANGE-LOCATION" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-key-change-location \- Change repository key location
 .SH SYNOPSIS
 .sp
-borg [common options] key change\-location [options] [REPOSITORY] KEY_LOCATION
+borg [common options] key change\-location [options] KEY_LOCATION
 .SH DESCRIPTION
 .sp
 Change the location of a borg key. The key can be stored at different locations:
-.sp
+.INDENT 0.0
+.IP \(bu 2
 keyfile: locally, usually in the home directory
+.IP \(bu 2
 repokey: inside the repo (in the repo config)
-.INDENT 0.0
-.TP
-.B Note: this command does NOT change the crypto algorithms, just the key location,
-thus you must ONLY give the key location (keyfile or repokey).
 .UNINDENT
+.sp
+Please note:
+.sp
+This command does NOT change the crypto algorithms, just the key location,
+thus you must ONLY give the key location (keyfile or repokey).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
-.sp
-REPOSITORY
 .INDENT 0.0
 .TP
 .B KEY_LOCATION
@@ -58,7 +59,7 @@ select key location
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-keep
+.B  \-\-keep
 keep the key also at the current location (default: remove it)
 .UNINDENT
 .SH SEE ALSO

docs/man/borg-key-change-passphrase.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-key-change-passphrase \- Change repository key file passphrase
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-key-change-passphrase \- Change repository key file passphrase
 .SH SYNOPSIS
 .sp
-borg [common options] key change\-passphrase [options] [REPOSITORY]
+borg [common options] key change\-passphrase [options]
 .SH DESCRIPTION
 .sp
 The key files used for repository encryption are optionally passphrase
@@ -45,9 +45,6 @@ does not protect future (nor past) backups to the same repository.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.sp
-REPOSITORY
 .SH EXAMPLES
 .INDENT 0.0
 .INDENT 3.5
@@ -55,7 +52,7 @@ REPOSITORY
 .nf
 .ft C
 # Create a key file protected repository
-$ borg init \-\-encryption=keyfile \-v /path/to/repo
+$ borg rcreate \-\-encryption=keyfile \-v
 Initializing repository at "/path/to/repo"
 Enter new passphrase:
 Enter same passphrase again:
@@ -67,7 +64,7 @@ Archives: 0, w/ cached Idx: 0, w/ outdated Idx: 0, w/o cached Idx: 0.
 Done.
 
 # Change key file passphrase
-$ borg key change\-passphrase \-v /path/to/repo
+$ borg key change\-passphrase \-v
 Enter passphrase for key /root/.config/borg/keys/mnt_backup:
 Enter new passphrase:
 Enter same passphrase again:
@@ -77,7 +74,7 @@ Key updated
 # Import a previously\-exported key into the specified
 # key file (creating or overwriting the output key)
 # (keyfile repositories only)
-$ BORG_KEY_FILE=/path/to/output\-key borg key import /path/to/repo /path/to/exported
+$ BORG_KEY_FILE=/path/to/output\-key borg key import /path/to/exported
 .ft P
 .fi
 .UNINDENT
@@ -89,9 +86,9 @@ Fully automated using environment variables:
 .sp
 .nf
 .ft C
-$ BORG_NEW_PASSPHRASE=old borg init \-e=repokey repo
+$ BORG_NEW_PASSPHRASE=old borg rcreate \-e=repokey
 # now "old" is the current passphrase.
-$ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase repo
+$ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change\-passphrase
 # now "new" is the current passphrase.
 .ft P
 .fi

docs/man/borg-key-export.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-EXPORT 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-key-export \- Export the repository key for backup
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-KEY-EXPORT" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-key-export \- Export the repository key for backup
 .SH SYNOPSIS
 .sp
-borg [common options] key export [options] [REPOSITORY] [PATH]
+borg [common options] key export [options] [PATH]
 .SH DESCRIPTION
 .sp
 If repository encryption is used, the repository is inaccessible
@@ -78,8 +78,6 @@ borg key export \-\-qr\-html /path/to/repo encrypted\-key\-backup.html
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
-.sp
-REPOSITORY
 .INDENT 0.0
 .TP
 .B PATH
@@ -88,10 +86,10 @@ where to store the backup
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-paper
+.B  \-\-paper
 Create an export suitable for printing and later type\-in
 .TP
-.B \-\-qr\-html
+.B  \-\-qr\-html
 Create an html file suitable for printing and later type\-in or qr scan
 .UNINDENT
 .SH SEE ALSO

docs/man/borg-key-import.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-IMPORT 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-key-import \- Import the repository key from backup
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-KEY-IMPORT" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-key-import \- Import the repository key from backup
 .SH SYNOPSIS
 .sp
-borg [common options] key import [options] [REPOSITORY] [PATH]
+borg [common options] key import [options] [PATH]
 .SH DESCRIPTION
 .sp
 This command restores a key previously backed up with the export command.
@@ -53,8 +53,6 @@ key import\fP creates a new key file in \fB$BORG_KEYS_DIR\fP\&.
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
-.sp
-REPOSITORY
 .INDENT 0.0
 .TP
 .B PATH
@@ -63,7 +61,7 @@ path to the backup (\(aq\-\(aq to read from stdin)
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-paper
+.B  \-\-paper
 interactively import from a backup done with \fB\-\-paper\fP
 .UNINDENT
 .SH SEE ALSO

docs/man/borg-key.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-key \- Manage a keyfile or repokey of a repository
 .
 .nr rst2man-indent-level 0
 .
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-KEY" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-key \- Manage a keyfile or repokey of a repository
 .SH SYNOPSIS
 .nf
 borg [common options] key export ...

docs/man/borg-list.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-LIST 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-list \- List archive or repository contents
 .
 .nr rst2man-indent-level 0
 .
@@ -30,12 +27,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-LIST" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-list \- List archive contents
 .SH SYNOPSIS
 .sp
-borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
+borg [common options] list [options] NAME [PATH...]
 .SH DESCRIPTION
 .sp
-This command lists the contents of a repository or an archive.
+This command lists the contents of an archive.
 .sp
 For more help on include/exclude patterns, see the \fIborg_patterns\fP command output.
 .SH OPTIONS
@@ -44,8 +44,8 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPOSITORY_OR_ARCHIVE
-repository or archive to list contents of
+.B NAME
+specify the archive name
 .TP
 .B PATH
 paths to list; patterns are supported
@@ -53,38 +53,14 @@ paths to list; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-consider\-checkpoints
-Show checkpoint archives in the repository contents list (default: hidden).
-.TP
-.B \-\-short
+.B  \-\-short
 only print file/directory names, nothing else
 .TP
 .BI \-\-format \ FORMAT
-specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")
-.TP
-.B \-\-json
-Only valid for listing repository contents. Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
-.TP
-.B \-\-json\-lines
-Only valid for listing archive contents. Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
-.UNINDENT
-.SS Archive filters
-.INDENT 0.0
-.TP
-.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
-only consider archive names starting with this prefix.
-.TP
-.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
-only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
-.TP
-.BI \-\-sort\-by \ KEYS
-Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-.TP
-.BI \-\-first \ N
-consider first N archives after other filters were applied
+specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}")
 .TP
-.BI \-\-last \ N
-consider last N archives after other filters were applied
+.B  \-\-json\-lines
+Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@@ -107,14 +83,7 @@ read include/exclude patterns from PATTERNFILE, one per line
 .sp
 .nf
 .ft C
-$ borg list /path/to/repo
-Monday                               Mon, 2016\-02\-15 19:15:11
-repo                                 Mon, 2016\-02\-15 19:26:54
-root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
-newname                              Mon, 2016\-02\-15 19:50:19
-\&...
-
-$ borg list /path/to/repo::root\-2016\-02\-15
+$ borg list root\-2016\-02\-15
 drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
 drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
 \-rwxr\-xr\-x root   root    1029624 Thu, 2014\-11\-13 00:08:51 bin/bash
@@ -122,14 +91,14 @@ lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdif
 \-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
 \&...
 
-$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern "\- bin/ba*"
+$ borg list root\-2016\-02\-15 \-\-pattern "\- bin/ba*"
 drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
 drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
 lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
 \-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
 \&...
 
-$ borg list /path/to/repo::archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
+$ borg list archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 .
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code/myproject
@@ -137,11 +106,11 @@ drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code/myproject
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
 \&...
 
-$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:\e.ext$\(aq
+$ borg list archiveA \-\-pattern \(aqre:\e.ext$\(aq
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
 \&...
 
-$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:.ext$\(aq
+$ borg list archiveA \-\-pattern \(aqre:.ext$\(aq
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext
 \-rw\-rw\-r\-\- user   user    1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text
 \&...
@@ -160,23 +129,13 @@ Examples:
 .sp
 .nf
 .ft C
-$ borg list \-\-format \(aq{archive}{NL}\(aq /path/to/repo
-ArchiveFoo
-ArchiveBar
-\&...
-
-# {VAR:NUMBER} \- pad to NUMBER columns.
-# Strings are left\-aligned, numbers are right\-aligned.
-# Note: time columns except \(ga\(gaisomtime\(ga\(ga, \(ga\(gaisoctime\(ga\(ga and \(ga\(gaisoatime\(ga\(ga cannot be padded.
-$ borg list \-\-format \(aq{archive:36} {time} [{id}]{NL}\(aq /path/to/repo
-ArchiveFoo                           Thu, 2021\-12\-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274]
-$ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo
+$ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(aq ArchiveFoo
 \-rw\-rw\-r\-\- user   user       1024 Thu, 2021\-12\-09 10:22:17 file\-foo
 \&...
 
 # {VAR:<NUMBER} \- pad to NUMBER columns left\-aligned.
 # {VAR:>NUMBER} \- pad to NUMBER columns right\-aligned.
-$ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo
+$ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq ArchiveFoo
 \-rw\-rw\-r\-\-   user   user 1024     Thu, 2021\-12\-09 10:22:17 file\-foo
 \&...
 .ft P
@@ -185,50 +144,13 @@ $ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{
 .UNINDENT
 .sp
 The following keys are always available:
-.INDENT 0.0
-.IP \(bu 2
-NEWLINE: OS dependent line separator
-.IP \(bu 2
-NL: alias of NEWLINE
-.IP \(bu 2
-NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below
-.IP \(bu 2
-SPACE
-.IP \(bu 2
-TAB
-.IP \(bu 2
-CR
-.IP \(bu 2
-LF
-.UNINDENT
-.sp
-Keys available only when listing archives in a repository:
-.INDENT 0.0
-.IP \(bu 2
-archive: archive name interpreted as text (might be missing non\-text characters, see barchive)
-.IP \(bu 2
-name: alias of "archive"
-.IP \(bu 2
-barchive: verbatim archive name, can contain any character except NUL
-.IP \(bu 2
-comment: archive comment interpreted as text (might be missing non\-text characters, see bcomment)
-.IP \(bu 2
-bcomment: verbatim archive comment, can contain any character except NUL
-.IP \(bu 2
-id: internal ID of the archive
-.IP \(bu 2
-start: time (start) of creation of the archive
-.IP \(bu 2
-time: alias of "start"
-.IP \(bu 2
-end: time (end) of creation of the archive
-.IP \(bu 2
-command_line: command line which was used to create the archive
-.IP \(bu 2
-hostname: hostname of host on which this archive was created
-.IP \(bu 2
-username: username of user who created this archive
-.UNINDENT
+\- NEWLINE: OS dependent line separator
+\- NL: alias of NEWLINE
+\- NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below
+\- SPACE
+\- TAB
+\- CR
+\- LF
 .sp
 Keys available only when listing files in an archive:
 .INDENT 0.0
@@ -249,20 +171,18 @@ path: path interpreted as text (might be missing non\-text characters, see bpath
 .IP \(bu 2
 bpath: verbatim POSIX path, can contain any character except NUL
 .IP \(bu 2
-source: link target for links (identical to linktarget)
+source: link target for symlinks (identical to linktarget)
 .IP \(bu 2
 linktarget
 .IP \(bu 2
+hlid: hard link identity (same if hardlinking same fs object)
+.IP \(bu 2
 flags
 .IP \(bu 2
 size
 .IP \(bu 2
-csize: compressed size
-.IP \(bu 2
 dsize: deduplicated size
 .IP \(bu 2
-dcsize: deduplicated compressed size
-.IP \(bu 2
 num_chunks: number of chunks in this file
 .IP \(bu 2
 unique_chunks: number of unique chunks in this file

docs/man/borg-mount.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-MOUNT" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
 .sp
-borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
+borg [common options] mount [options] MOUNTPOINT [PATH...]
 .SH DESCRIPTION
 .sp
 This command mounts an archive as a FUSE filesystem. This can be useful for
@@ -98,9 +98,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPOSITORY_OR_ARCHIVE
-repository or archive to mount
-.TP
 .B MOUNTPOINT
 where to mount filesystem
 .TP
@@ -110,19 +107,19 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-consider\-checkpoints
+.B  \-\-consider\-checkpoints
 Show checkpoint archives in the repository contents list (default: hidden).
 .TP
-.B \-f\fP,\fB  \-\-foreground
+.B  \-f\fP,\fB  \-\-foreground
 stay in foreground, do not daemonize
 .TP
-.B \-o
+.B  \-o
 Extra mount options
 .TP
-.B \-\-numeric\-owner
+.B  \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B \-\-numeric\-ids
+.B  \-\-numeric\-ids
 use numeric user and group identifiers from archive(s)
 .UNINDENT
 .SS Archive filters

docs/man/borg-patterns.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-patterns \- Details regarding patterns
 .
 .nr rst2man-indent-level 0
 .
@@ -30,45 +27,47 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-PATTERNS" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
 .sp
-The path/filenames used as input for the pattern matching start from the
-currently active recursion root. You usually give the recursion root(s)
-when invoking borg and these can be either relative or absolute paths.
-.sp
-So, when you give \fIrelative/\fP as root, the paths going into the matcher
-will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as
-root, they will look like \fI/absolute/.../file.ext\fP\&.
-.sp
-File paths in Borg archives are always stored normalized and relative.
-This means that e.g. \fBborg create /path/to/repo ../some/path\fP will
-store all files as \fIsome/path/.../file.ext\fP and \fBborg create
-/path/to/repo /home/user\fP will store all files as
-\fIhome/user/.../file.ext\fP\&.
-.sp
-A directory exclusion pattern can end either with or without a slash (\(aq/\(aq).
-If it ends with a slash, such as \fIsome/path/\fP, the directory will be
-included but not its content. If it does not end with a slash, such as
-\fIsome/path\fP, both the directory and content will be excluded.
+When specifying one or more file paths in a Borg command that supports
+patterns for the respective option or argument, you can apply the
+patterns described here to include only desired files and/or exclude
+unwanted ones. Patterns can be used
+.INDENT 0.0
+.IP \(bu 2
+for \fB\-\-exclude\fP option,
+.IP \(bu 2
+in the file given with \fB\-\-exclude\-from\fP option,
+.IP \(bu 2
+for \fB\-\-pattern\fP option,
+.IP \(bu 2
+in the file given with \fB\-\-patterns\-from\fP option and
+.IP \(bu 2
+for \fBPATH\fP arguments that explicitly support them.
+.UNINDENT
 .sp
-File patterns support these styles: fnmatch, shell, regular expressions,
-path prefixes and path full\-matches. By default, fnmatch is used for
-\fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP
-option. For commands that support patterns in their \fBPATH\fP argument
-like (\fBborg list\fP), the default pattern is path prefix.
+Borg always stores all file paths normalized and relative to the
+current recursion root. The recursion root is also named \fBPATH\fP in
+Borg commands like \fIborg create\fP that do a file discovery, so do not
+confuse the root with the \fBPATH\fP argument of e.g. \fIborg extract\fP\&.
 .sp
-Starting with Borg 1.2, for all but regular expression pattern matching
-styles, all paths are treated as relative, meaning that a leading path
-separator is removed after normalizing and before matching. This allows
-you to use absolute or relative patterns arbitrarily.
+Starting with Borg 1.2, paths that are matched against patterns always
+appear relative. If you give \fB/absolute/\fP as root, the paths going
+into the matcher will look relative like \fBabsolute/.../file.ext\fP\&.
+If you give \fB\&../some/path\fP as root, the paths will look like
+\fBsome/path/.../file.ext\fP\&.
 .sp
-If followed by a colon (\(aq:\(aq) the first two characters of a pattern are
-used as a style selector. Explicit style selection is necessary when a
-non\-default style is desired or when the desired pattern starts with
-two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
+File patterns support five different styles. If followed by a colon \(aq:\(aq,
+the first two characters of a pattern are used as a style selector.
+Explicit style selection is necessary if a non\-default style is desired
+or when the desired pattern starts with two alphanumeric characters
+followed by a colon (i.e. \fBaa:something/*\fP).
 .INDENT 0.0
 .TP
-.B \fI\%Fnmatch\fP, selector \fIfm:\fP
+.B \fI\%Fnmatch\fP, selector \fBfm:\fP
 This is the default style for \fB\-\-exclude\fP and \fB\-\-exclude\-from\fP\&.
 These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching
 any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq
@@ -76,7 +75,7 @@ matching any single character specified, including ranges, and \(aq[!...]\(aq
 matching any character not specified. For the purpose of these patterns,
 the path separator (backslash for Windows and \(aq/\(aq on other systems) is not
 treated specially. Wrap meta\-characters in brackets for a literal
-match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path
+match (i.e. \fB[?]\fP to match the literal character \(aq?\(aq). For a path
 to match a pattern, the full path must match, or it must match
 from the start of the full path to just before a path separator. Except
 for the root path, paths will never end in the path separator when
@@ -84,33 +83,31 @@ matching is attempted.  Thus, if a given pattern ends in a path
 separator, a \(aq*\(aq is appended before matching is attempted. A leading
 path separator is always removed.
 .TP
-.B Shell\-style patterns, selector \fIsh:\fP
+.B Shell\-style patterns, selector \fBsh:\fP
 This is the default style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP\&.
 Like fnmatch patterns these are similar to shell patterns. The difference
-is that the pattern may include \fI**/\fP for matching zero or more directory
-levels, \fI*\fP for matching zero or more arbitrary characters with the
+is that the pattern may include \fB**/\fP for matching zero or more directory
+levels, \fB*\fP for matching zero or more arbitrary characters with the
 exception of any path separator. A leading path separator is always removed.
 .TP
-.B Regular expressions, selector \fIre:\fP
-Regular expressions similar to those found in Perl are supported. Unlike
-shell patterns regular expressions are not required to match the full
+.B \fI\%Regular expressions\fP, selector \fBre:\fP
+Unlike shell patterns, regular expressions are not required to match the full
 path and any substring match is sufficient. It is strongly recommended to
 anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path
 separators (backslash for Windows and \(aq/\(aq on other systems) in paths are
-always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The
-regular expression syntax is described in the \fI\%Python documentation for
-the re module\fP\&.
+always normalized to a forward slash \(aq/\(aq before applying a pattern.
 .TP
-.B Path prefix, selector \fIpp:\fP
+.B Path prefix, selector \fBpp:\fP
 This pattern style is useful to match whole sub\-directories. The pattern
-\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein. A leading
-path separator is always removed.
+\fBpp:root/somedir\fP matches \fBroot/somedir\fP and everything therein.
+A leading path separator is always removed.
 .TP
-.B Path full\-match, selector \fIpf:\fP
+.B Path full\-match, selector \fBpf:\fP
 This pattern style is (only) useful to match full paths.
 This is kind of a pseudo pattern as it can not have any variable or
-unspecified parts \- the full path must be given. \fIpf:root/file.ext\fP matches
-\fIroot/file.ext\fP only. A leading path separator is always removed.
+unspecified parts \- the full path must be given. \fBpf:root/file.ext\fP
+matches \fBroot/file.ext\fP only. A leading path separator is always
+removed.
 .sp
 Implementation note: this is implemented via very time\-efficient O(1)
 hashtable lookups (this means you can have huge amounts of such patterns
@@ -125,12 +122,12 @@ Same logic applies for exclude.
 \fBNOTE:\fP
 .INDENT 0.0
 .INDENT 3.5
-\fIre:\fP, \fIsh:\fP and \fIfm:\fP patterns are all implemented on top of the Python SRE
-engine. It is very easy to formulate patterns for each of these types which
-requires an inordinate amount of time to match paths. If untrusted users
-are able to supply patterns, ensure they cannot supply \fIre:\fP patterns.
-Further, ensure that \fIsh:\fP and \fIfm:\fP patterns only contain a handful of
-wildcards at most.
+\fBre:\fP, \fBsh:\fP and \fBfm:\fP patterns are all implemented on top of
+the Python SRE engine. It is very easy to formulate patterns for each
+of these types which requires an inordinate amount of time to match
+paths. If untrusted users are able to supply patterns, ensure they
+cannot supply \fBre:\fP patterns. Further, ensure that \fBsh:\fP and
+\fBfm:\fP patterns only contain a handful of wildcards at most.
 .UNINDENT
 .UNINDENT
 .sp
@@ -139,8 +136,8 @@ from within a shell, the patterns should be quoted to protect them from
 expansion.
 .sp
 The \fB\-\-exclude\-from\fP option permits loading exclusion patterns from a text
-file with one pattern per line. Lines empty or starting with the number sign
-(\(aq#\(aq) after removing whitespace on both ends are ignored. The optional style
+file with one pattern per line. Lines empty or starting with the hash sign
+\(aq#\(aq after removing whitespace on both ends are ignored. The optional style
 selector prefix is also supported for patterns loaded from a file. Due to
 whitespace removal, paths with whitespace at the beginning or end can only be
 excluded using regular expressions.
@@ -155,74 +152,101 @@ Examples:
 .nf
 .ft C
 # Exclude \(aq/home/user/file.o\(aq but not \(aq/home/user/file.odt\(aq:
-$ borg create \-e \(aq*.o\(aq backup /
+$ borg create \-e \(aq*.o\(aq archive /
 
 # Exclude \(aq/home/user/junk\(aq and \(aq/home/user/subdir/junk\(aq but
 # not \(aq/home/user/importantjunk\(aq or \(aq/etc/junk\(aq:
-$ borg create \-e \(aq/home/*/junk\(aq backup /
+$ borg create \-e \(aqhome/*/junk\(aq archive /
 
 # Exclude the contents of \(aq/home/user/cache\(aq but not the directory itself:
-$ borg create \-e home/user/cache/ backup /
+$ borg create \-e home/user/cache/ archive /
 
 # The file \(aq/home/user/cache/important\(aq is *not* backed up:
-$ borg create \-e /home/user/cache/ backup / /home/user/cache/important
+$ borg create \-e home/user/cache/ archive / /home/user/cache/important
 
 # The contents of directories in \(aq/home\(aq are not backed up when their name
 # ends in \(aq.tmp\(aq
-$ borg create \-\-exclude \(aqre:^/home/[^/]+\e.tmp/\(aq backup /
+$ borg create \-\-exclude \(aqre:^home/[^/]+\e.tmp/\(aq archive /
 
 # Load exclusions from file
 $ cat >exclude.txt <<EOF
 # Comment line
-/home/*/junk
+home/*/junk
 *.tmp
 fm:aa:something/*
-re:^/home/[^/]+\e.tmp/
-sh:/home/*/.thumbnails
+re:^home/[^/]+\e.tmp/
+sh:home/*/.thumbnails
 # Example with spaces, no need to escape as it is processed by borg
 some file with spaces.txt
 EOF
-$ borg create \-\-exclude\-from exclude.txt backup /
+$ borg create \-\-exclude\-from exclude.txt archive /
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-A more general and easier to use way to define filename matching patterns exists
-with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you may
-specify the backup roots (starting points) and patterns for inclusion/exclusion.
-A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a
-file pattern). An include rule starts with the prefix +, an exclude rule starts
-with the prefix \-, an exclude\-norecurse rule starts with !, all followed by a pattern.
+A more general and easier to use way to define filename matching patterns
+exists with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using
+these, you may specify the backup roots, default pattern styles and
+patterns for inclusion and exclusion.
+.INDENT 0.0
+.TP
+.B Root path prefix \fBR\fP
+A recursion root path starts with the prefix \fBR\fP, followed by a path
+(a plain path, not a file pattern). Use this prefix to have the root
+paths in the patterns file rather than as command line arguments.
+.TP
+.B Pattern style prefix \fBP\fP
+To change the default pattern style, use the \fBP\fP prefix, followed by
+the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP).
+All patterns following this line will use this style until another style
+is specified.
+.TP
+.B Exclude pattern prefix \fB\-\fP
+Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.
+This has the same effect as the \fB\-\-exclude\fP option.
+.TP
+.B Exclude no\-recurse pattern prefix \fB!\fP
+Use the prefix \fB!\fP, followed by a pattern, to define an exclusion
+that does not recurse into subdirectories. This saves time, but
+prevents include patterns to match any files in subdirectories.
+.TP
+.B Include pattern prefix \fB+\fP
+Use the prefix \fB+\fP, followed by a pattern, to define inclusions.
+This is useful to include paths that are covered in an exclude
+pattern and would otherwise not be backed up.
+.UNINDENT
+.sp
+The first matching pattern is used, so if an include pattern matches
+before an exclude pattern, the file is backed up. Note that a no\-recurse
+exclude stops examination of subdirectories so that potential includes
+will not match \- use normal exludes for such use cases.
 .sp
-\fBNOTE:\fP
+\fBTip: You can easily test your patterns with \-\-dry\-run and  \-\-list\fP:
 .INDENT 0.0
 .INDENT 3.5
-Via \fB\-\-pattern\fP or \fB\-\-patterns\-from\fP you can define BOTH inclusion and exclusion
-of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP and
-\fB\-\-exclude\-from\fP ONLY excludes are defined.
+.sp
+.nf
+.ft C
+$ borg create \-\-dry\-run \-\-list \-\-patterns\-from patterns.txt archive
+.ft P
+.fi
 .UNINDENT
 .UNINDENT
 .sp
-Inclusion patterns are useful to include paths that are contained in an excluded
-path. The first matching pattern is used so if an include pattern matches before
-an exclude pattern, the file is backed up. If an exclude\-norecurse pattern matches
-a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for
-include rules below that directory.
+This will list the considered files one per line, prefixed with a
+character that indicates the action (e.g. \(aqx\(aq for excluding, see
+\fBItem flags\fP in \fIborg create\fP usage docs).
 .sp
 \fBNOTE:\fP
 .INDENT 0.0
 .INDENT 3.5
-It\(aqs possible that a sub\-directory/file is matched while parent directories are not.
-In that case, parent directories are not backed up thus their user, group, permission,
-etc. can not be restored.
+It\(aqs possible that a sub\-directory/file is matched while parent
+directories are not. In that case, parent directories are not backed
+up and thus their user, group, permission, etc. cannot be restored.
 .UNINDENT
 .UNINDENT
 .sp
-Note that the default pattern style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP is
-shell style (\fIsh:\fP), so those patterns behave similar to rsync include/exclude
-patterns. The pattern style can be set via the \fIP\fP prefix.
-.sp
 Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command line are
 considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP
 are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last.
@@ -235,10 +259,16 @@ Examples:
 .ft C
 # backup pics, but not the ones from 2018, except the good ones:
 # note: using = is essential to avoid cmdline argument parsing issues.
-borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics
+borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 archive pics
 
-# use a file with patterns:
-borg create \-\-patterns\-from patterns.lst repo::arch
+# backup only JPG/JPEG files (case insensitive) in all home directories:
+borg create \-\-pattern \(aq+ re:\e.jpe?g(?i)$\(aq archive /home
+
+# backup homes, but exclude big downloads (like .ISO files) or hidden files:
+borg create \-\-exclude \(aqre:\e.iso(?i)$\(aq \-\-exclude \(aqsh:home/**/.*\(aq archive /home
+
+# use a file with patterns (recursion root \(aq/\(aq via command line):
+borg create \-\-patterns\-from patterns.lst archive /
 .ft P
 .fi
 .UNINDENT
@@ -250,22 +280,17 @@ The patterns.lst file could look like that:
 .sp
 .nf
 .ft C
-# "sh:" pattern style is the default, so the following line is not needed:
-P sh
-R /
-# can be rebuild
-\- /home/*/.cache
-# they\(aqre downloads for a reason
-\- /home/*/Downloads
-# susan is a nice person
+# "sh:" pattern style is the default
+# exclude caches
+\- home/*/.cache
 # include susans home
-+ /home/susan
++ home/susan
 # also back up this exact file
-+ pf:/home/bobby/specialfile.txt
++ pf:home/bobby/specialfile.txt
 # don\(aqt backup the other home directories
-\- /home/*
-# don\(aqt even look in /proc
-! /proc
+\- home/*
+# don\(aqt even look in /dev, /proc, /run, /sys, /tmp (note: would exclude files like /device, too)
+! re:^(dev|proc|run|sys|tmp)
 .ft P
 .fi
 .UNINDENT
@@ -278,14 +303,14 @@ You can specify recursion roots either on the command line or in a patternfile:
 .nf
 .ft C
 # these two commands do the same thing
-borg create \-\-exclude /home/bobby/junk repo::arch /home/bobby /home/susan
-borg create \-\-patterns\-from patternfile.lst repo::arch
+borg create \-\-exclude home/bobby/junk archive /home/bobby /home/susan
+borg create \-\-patterns\-from patternfile.lst archive
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .sp
-The patternfile:
+patternfile.lst:
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -296,8 +321,7 @@ The patternfile:
 P fm
 R /home/bobby
 R /home/susan
-
-\- /home/bobby/junk
+\- home/bobby/junk
 .ft P
 .fi
 .UNINDENT

docs/man/borg-placeholders.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PLACEHOLDERS 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-placeholders \- Details regarding placeholders
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-PLACEHOLDERS" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-placeholders \- Details regarding placeholders
 .SH DESCRIPTION
 .sp
-Repository (or Archive) URLs, \fB\-\-prefix\fP, \fB\-\-glob\-archives\fP, \fB\-\-comment\fP
+Repository URLs, \fB\-\-name\fP, \fB\-\-prefix\fP, \fB\-\-glob\-archives\fP, \fB\-\-comment\fP
 and \fB\-\-remote\-path\fP values support these placeholders:
 .INDENT 0.0
 .TP

docs/man/borg-prune.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-prune \- Prune repository archives according to specified rules
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-PRUNE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-prune \- Prune repository archives according to specified rules
 .SH SYNOPSIS
 .sp
-borg [common options] prune [options] [REPOSITORY]
+borg [common options] prune [options]
 .SH DESCRIPTION
 .sp
 The prune command prunes a repository by deleting all archives not matching
@@ -91,52 +91,46 @@ Please note that the "All archives" stats refer to the state after pruning.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.INDENT 0.0
-.TP
-.B REPOSITORY
-repository to prune
-.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-n\fP,\fB  \-\-dry\-run
+.B  \-n\fP,\fB  \-\-dry\-run
 do not change repository
 .TP
-.B \-\-force
+.B  \-\-force
 force pruning of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
 .TP
-.B \-s\fP,\fB  \-\-stats
+.B  \-s\fP,\fB  \-\-stats
 print statistics for the deleted archive
 .TP
-.B \-\-list
+.B  \-\-list
 output verbose list of archives it keeps/prunes
 .TP
 .BI \-\-keep\-within \ INTERVAL
 keep all archives within this time interval
 .TP
-.B \-\-keep\-last\fP,\fB  \-\-keep\-secondly
+.B  \-\-keep\-last\fP,\fB  \-\-keep\-secondly
 number of secondly archives to keep
 .TP
-.B \-\-keep\-minutely
+.B  \-\-keep\-minutely
 number of minutely archives to keep
 .TP
-.B \-H\fP,\fB  \-\-keep\-hourly
+.B  \-H\fP,\fB  \-\-keep\-hourly
 number of hourly archives to keep
 .TP
-.B \-d\fP,\fB  \-\-keep\-daily
+.B  \-d\fP,\fB  \-\-keep\-daily
 number of daily archives to keep
 .TP
-.B \-w\fP,\fB  \-\-keep\-weekly
+.B  \-w\fP,\fB  \-\-keep\-weekly
 number of weekly archives to keep
 .TP
-.B \-m\fP,\fB  \-\-keep\-monthly
+.B  \-m\fP,\fB  \-\-keep\-monthly
 number of monthly archives to keep
 .TP
-.B \-y\fP,\fB  \-\-keep\-yearly
+.B  \-y\fP,\fB  \-\-keep\-yearly
 number of yearly archives to keep
 .TP
-.B \-\-save\-space
+.B  \-\-save\-space
 work slower, but using less space
 .UNINDENT
 .SS Archive filters
@@ -167,21 +161,21 @@ first so you will see what it would do without it actually doing anything.
 .ft C
 # Keep 7 end of day and 4 additional end of week archives.
 # Do a dry\-run without actually deleting anything.
-$ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4 /path/to/repo
+$ borg prune \-v \-\-list \-\-dry\-run \-\-keep\-daily=7 \-\-keep\-weekly=4
 
 # Same as above but only apply to archive names starting with the hostname
 # of the machine followed by a "\-" character:
-$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-prefix=\(aq{hostname}\-\(aq /path/to/repo
+$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-prefix=\(aq{hostname}\-\(aq
 # actually free disk space:
-$ borg compact /path/to/repo
+$ borg compact
 
 # Keep 7 end of day, 4 additional end of week archives,
 # and an end of month archive for every month:
-$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
+$ borg prune \-v \-\-list \-\-keep\-daily=7 \-\-keep\-weekly=4 \-\-keep\-monthly=\-1
 
 # Keep all backups in the last 10 days, 4 additional end of week archives,
 # and an end of month archive for every month:
-$ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1 /path/to/repo
+$ borg prune \-v \-\-list \-\-keep\-within=10d \-\-keep\-weekly=4 \-\-keep\-monthly=\-1
 .ft P
 .fi
 .UNINDENT

docs/man/borg-init.1 → docs/man/borg-rcreate.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INIT 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-init \- Initialize an empty repository
 .
 .nr rst2man-indent-level 0
 .
@@ -30,12 +27,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-RCREATE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-rcreate \- Create a new, empty repository
 .SH SYNOPSIS
 .sp
-borg [common options] init [options] [REPOSITORY]
+borg [common options] rcreate [options]
 .SH DESCRIPTION
 .sp
-This command initializes an empty repository. A repository is a filesystem
+This command creates a new, empty repository. A repository is a filesystem
 directory containing the deduplicated data from zero or more archives.
 .SS Encryption mode TLDR
 .sp
@@ -48,7 +48,7 @@ tips will come below):
 .sp
 .nf
 .ft C
-borg init \-\-encryption repokey /path/to/repo
+borg rcreate \-\-encryption repokey\-aes\-ocb
 .ft P
 .fi
 .UNINDENT
@@ -122,19 +122,19 @@ center;
 |l|l|l|l|l|.
 _
 T{
-\fBmode (* = keyfile or repokey)\fP
+Mode (K = keyfile or repokey)
 T}	T{
-\fBID\-Hash\fP
+ID\-Hash
 T}	T{
-\fBEncryption\fP
+Encryption
 T}	T{
-\fBAuthentication\fP
+Authentication
 T}	T{
-\fBV>=\fP
+V >=
 T}
 _
 T{
-\fB*\-blake2\-chacha20\-poly1305\fP
+K\-blake2\-chacha20\-poly1305
 T}	T{
 BLAKE2b
 T}	T{
@@ -142,11 +142,11 @@ CHACHA20
 T}	T{
 POLY1305
 T}	T{
-1.3
+2.0
 T}
 _
 T{
-\fB*\-chacha20\-poly1305\fP
+K\-chacha20\-poly1305
 T}	T{
 HMAC\-SHA\-256
 T}	T{
@@ -154,11 +154,11 @@ CHACHA20
 T}	T{
 POLY1305
 T}	T{
-1.3
+2.0
 T}
 _
 T{
-\fB*\-blake2\-aes\-ocb\fP
+K\-blake2\-aes\-ocb
 T}	T{
 BLAKE2b
 T}	T{
@@ -166,11 +166,11 @@ AES256\-OCB
 T}	T{
 AES256\-OCB
 T}	T{
-1.3
+2.0
 T}
 _
 T{
-\fB*\-aes\-ocb\fP
+K\-aes\-ocb
 T}	T{
 HMAC\-SHA\-256
 T}	T{
@@ -178,11 +178,11 @@ AES256\-OCB
 T}	T{
 AES256\-OCB
 T}	T{
-1.3
+2.0
 T}
 _
 T{
-\fB*\-blake2\fP
+K\-blake2
 T}	T{
 BLAKE2b
 T}	T{
@@ -194,7 +194,7 @@ T}	T{
 T}
 _
 T{
-\fB*\fP
+K
 T}	T{
 HMAC\-SHA\-256
 T}	T{
@@ -257,8 +257,6 @@ malicious tampering use an \fIauthenticated\fP mode. It\(aqs like \fIrepokey\fP
 \fB\-\-key\-algorithm argon2\fP is the default and is recommended.
 The key encryption key is derived from your passphrase via argon2\-id.
 Argon2 is considered more modern and secure than pbkdf2.
-.IP \(bu 2
-You can use \fB\-\-key\-algorithm pbkdf2\fP if you want to access your repo via old versions of borg.
 .UNINDENT
 .sp
 Our implementation of argon2\-based key algorithm follows the cryptographic best practices:
@@ -275,28 +273,25 @@ to break backwards compatibility anyway we took the opportunity to fix all 3 iss
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.INDENT 0.0
-.TP
-.B REPOSITORY
-repository to create
-.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
+.BI \-\-other\-repo \ SRC_REPOSITORY
+reuse the key material from the other repository
+.TP
 .BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE
 select encryption key mode \fB(required)\fP
 .TP
-.B \-\-append\-only
+.B  \-\-append\-only
 create an append\-only mode repository. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
 .TP
 .BI \-\-storage\-quota \ QUOTA
 Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
 .TP
-.B \-\-make\-parent\-dirs
+.B  \-\-make\-parent\-dirs
 create the parent directories of the repository directory, if they are missing.
 .TP
-.B \-\-key\-algorithm
+.B  \-\-key\-algorithm
 the algorithm we use to derive a key encryption key from your passphrase. Default: argon2
 .UNINDENT
 .SH EXAMPLES
@@ -305,29 +300,30 @@ the algorithm we use to derive a key encryption key from your passphrase. Defaul
 .sp
 .nf
 .ft C
-# Local repository, recommended repokey AEAD crypto modes
-$ borg init \-\-encryption=repokey\-aes\-ocb /path/to/repo
-$ borg init \-\-encryption=repokey\-chacha20\-poly1305 /path/to/repo
-$ borg init \-\-encryption=repokey\-blake2\-aes\-ocb /path/to/repo
-$ borg init \-\-encryption=repokey\-blake2\-chacha20\-poly1305 /path/to/repo
-
-# Local repository (no encryption), not recommended
-$ borg init \-\-encryption=none /path/to/repo
+# Local repository
+$ export BORG_REPO=/path/to/repo
+# recommended repokey AEAD crypto modes
+$ borg rcreate \-\-encryption=repokey\-aes\-ocb
+$ borg rcreate \-\-encryption=repokey\-chacha20\-poly1305
+$ borg rcreate \-\-encryption=repokey\-blake2\-aes\-ocb
+$ borg rcreate \-\-encryption=repokey\-blake2\-chacha20\-poly1305
+# no encryption, not recommended
+$ borg rcreate \-\-encryption=authenticated
+$ borg rcreate \-\-encryption=none
 
 # Remote repository (accesses a remote borg via ssh)
+$ export BORG_REPO=ssh://user@hostname/~/backup
 # repokey: stores the (encrypted) key into <REPO_DIR>/config
-$ borg init \-\-encryption=repokey\-aes\-ocb user@hostname:backup
-
-# Remote repository (accesses a remote borg via ssh)
+$ borg rcreate \-\-encryption=repokey\-aes\-ocb
 # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
-$ borg init \-\-encryption=keyfile\-aes\-ocb user@hostname:backup
+$ borg rcreate \-\-encryption=keyfile\-aes\-ocb
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
 .sp
-\fIborg\-common(1)\fP, \fIborg\-create(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-check(1)\fP, \fIborg\-list(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP
+\fIborg\-common(1)\fP, \fIborg\-rdelete(1)\fP, \fIborg\-rlist(1)\fP, \fIborg\-check(1)\fP, \fIborg\-key\-import(1)\fP, \fIborg\-key\-export(1)\fP, \fIborg\-key\-change\-passphrase(1)\fP
 .SH AUTHOR
 The Borg Collective
 .\" Generated by docutils manpage writer.

docs/man/borg-rdelete.1

@@ -0,0 +1,90 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "BORG-RDELETE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-rdelete \- Delete a repository
+.SH SYNOPSIS
+.sp
+borg [common options] rdelete [options]
+.SH DESCRIPTION
+.sp
+This command deletes the complete repository.
+.sp
+When you delete a complete repository, the security info and local cache for it
+(if any) are also deleted. Alternatively, you can delete just the local cache
+with the \fB\-\-cache\-only\fP option, or keep the security info with the
+\fB\-\-keep\-security\-info\fP option.
+.sp
+Always first use \fB\-\-dry\-run \-\-list\fP to see what would be deleted.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B  \-n\fP,\fB  \-\-dry\-run
+do not change repository
+.TP
+.B  \-\-list
+output verbose list of archives
+.TP
+.B  \-\-force
+force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
+.TP
+.B  \-\-cache\-only
+delete only the local cache for the given repository
+.TP
+.B  \-\-keep\-security\-info
+keep the local security info when deleting a repository
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# delete the whole repository and the related local cache:
+$ borg rdelete
+You requested to completely DELETE the repository *including* all archives it contains:
+repo                                 Mon, 2016\-02\-15 19:26:54
+root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
+newname                              Mon, 2016\-02\-15 19:50:19
+Type \(aqYES\(aq if you understand this and want to continue: YES
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-recreate.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RECREATE 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-recreate \- Re-create archives
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-RECREATE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-recreate \- Re-create archives
 .SH SYNOPSIS
 .sp
-borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
+borg [common options] recreate [options] [PATH...]
 .SH DESCRIPTION
 .sp
 Recreate the contents of existing archives.
@@ -91,25 +91,22 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPOSITORY_OR_ARCHIVE
-repository or archive to recreate
-.TP
 .B PATH
 paths to recreate; patterns are supported
 .UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-\-list
+.B  \-\-list
 output verbose list of items (files, dirs, ...)
 .TP
 .BI \-\-filter \ STATUSCHARS
 only display items with the given status characters (listed in borg create \-\-help)
 .TP
-.B \-n\fP,\fB  \-\-dry\-run
+.B  \-n\fP,\fB  \-\-dry\-run
 do not change anything
 .TP
-.B \-s\fP,\fB  \-\-stats
+.B  \-s\fP,\fB  \-\-stats
 print statistics at end
 .UNINDENT
 .SS Exclusion options
@@ -127,18 +124,33 @@ include/exclude paths matching PATTERN
 .BI \-\-patterns\-from \ PATTERNFILE
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
-.B \-\-exclude\-caches
+.B  \-\-exclude\-caches
 exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
 .TP
-.B \-\-keep\-exclude\-tags
+.B  \-\-keep\-exclude\-tags
 if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive
 .UNINDENT
-.SS Archive options
+.SS Archive filters
 .INDENT 0.0
 .TP
+.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
+only consider archive names starting with this prefix.
+.TP
+.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+.TP
+.BI \-\-sort\-by \ KEYS
+Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+.TP
+.BI \-\-first \ N
+consider first N archives after other filters were applied
+.TP
+.BI \-\-last \ N
+consider last N archives after other filters were applied
+.TP
 .BI \-\-target \ TARGET
 create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
 .TP
@@ -166,30 +178,25 @@ specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BI
 .sp
 .nf
 .ft C
-# Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
-# Archives created with Borg 1.1+ and the default chunker params are skipped
-# (archive ID stays the same).
-$ borg recreate /mnt/backup \-\-chunker\-params default \-\-progress
-
 # Create a backup with little but fast compression
-$ borg create /mnt/backup::archive /some/files \-\-compression lz4
+$ borg create archive /some/files \-\-compression lz4
 # Then compress it \- this might take longer, but the backup has already completed,
 # so no inconsistencies from a long\-running backup job.
-$ borg recreate /mnt/backup::archive \-\-recompress \-\-compression zlib,9
+$ borg recreate \-a archive \-\-recompress \-\-compression zlib,9
 
 # Remove unwanted files from all archives in a repository.
 # Note the relative path for the \-\-exclude option \- archives only contain relative paths.
-$ borg recreate /mnt/backup \-\-exclude home/icke/Pictures/drunk_photos
+$ borg recreate \-\-exclude home/icke/Pictures/drunk_photos
 
 # Change archive comment
-$ borg create \-\-comment "This is a comment" /mnt/backup::archivename ~
-$ borg info /mnt/backup::archivename
+$ borg create \-\-comment "This is a comment" archivename ~
+$ borg info \-a archivename
 Name: archivename
 Fingerprint: ...
 Comment: This is a comment
 \&...
-$ borg recreate \-\-comment "This is a better comment" /mnt/backup::archivename
-$ borg info /mnt/backup::archivename
+$ borg recreate \-\-comment "This is a better comment" \-a archivename
+$ borg info \-a archivename
 Name: archivename
 Fingerprint: ...
 Comment: This is a better comment

docs/man/borg-rename.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-rename \- Rename an existing archive
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-RENAME" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-rename \- Rename an existing archive
 .SH SYNOPSIS
 .sp
-borg [common options] rename [options] ARCHIVE NEWNAME
+borg [common options] rename [options] OLDNAME NEWNAME
 .SH DESCRIPTION
 .sp
 This command renames an archive in the repository.
@@ -44,11 +44,11 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B ARCHIVE
-archive to rename
+.B OLDNAME
+specify the archive name
 .TP
 .B NEWNAME
-the new archive name to use
+specify the new archive name
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
@@ -56,12 +56,12 @@ the new archive name to use
 .sp
 .nf
 .ft C
-$ borg create /path/to/repo::archivename ~
-$ borg list /path/to/repo
+$ borg create archivename ~
+$ borg rlist
 archivename                          Mon, 2016\-02\-15 19:50:19
 
-$ borg rename /path/to/repo::archivename newname
-$ borg list /path/to/repo
+$ borg rename archivename newname
+$ borg rlist
 newname                              Mon, 2016\-02\-15 19:50:19
 .ft P
 .fi

docs/man/borg-rinfo.1

@@ -0,0 +1,83 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "BORG-RINFO" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-rinfo \- Show repository infos
+.SH SYNOPSIS
+.sp
+borg [common options] rinfo [options]
+.SH DESCRIPTION
+.sp
+This command displays detailed information about the repository.
+.sp
+Please note that the deduplicated sizes of the individual archives do not add
+up to the deduplicated size of the repository ("all archives"), because the two
+are meaning different things:
+.sp
+This archive / deduplicated size = amount of data stored ONLY for this archive
+= unique chunks of this archive.
+All archives / deduplicated size = amount of data stored in the repo
+= all chunks in the repository.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B  \-\-json
+format output as JSON
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg rinfo
+Repository ID: 0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
+Location: /Users/tw/w/borg/path/to/repo
+Encrypted: Yes (repokey AES\-OCB)
+Cache: /Users/tw/.cache/borg/0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
+Security dir: /Users/tw/.config/borg/security/0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
+Original size: 152.14 MB
+Deduplicated size: 30.38 MB
+Unique chunks: 654
+Total chunks: 3302
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-rlist.1

@@ -0,0 +1,160 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "BORG-RLIST" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-rlist \- List the archives contained in a repository
+.SH SYNOPSIS
+.sp
+borg [common options] rlist [options]
+.SH DESCRIPTION
+.sp
+This command lists the archives contained in a repository.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B  \-\-consider\-checkpoints
+Show checkpoint archives in the repository contents list (default: hidden).
+.TP
+.B  \-\-short
+only print the archive names, nothing else
+.TP
+.BI \-\-format \ FORMAT
+specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}")
+.TP
+.B  \-\-json
+Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
+.UNINDENT
+.SS Archive filters
+.INDENT 0.0
+.TP
+.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
+only consider archive names starting with this prefix.
+.TP
+.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+.TP
+.BI \-\-sort\-by \ KEYS
+Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+.TP
+.BI \-\-first \ N
+consider first N archives after other filters were applied
+.TP
+.BI \-\-last \ N
+consider last N archives after other filters were applied
+.UNINDENT
+.SH EXAMPLES
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg rlist
+Monday                               Mon, 2016\-02\-15 19:15:11
+repo                                 Mon, 2016\-02\-15 19:26:54
+root\-2016\-02\-15                      Mon, 2016\-02\-15 19:36:29
+newname                              Mon, 2016\-02\-15 19:50:19
+\&...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH NOTES
+.SS The FORMAT specifier syntax
+.sp
+The \fB\-\-format\fP option uses python\(aqs \fI\%format string syntax\fP\&.
+.sp
+Examples:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ borg rlist \-\-format \(aq{archive}{NL}\(aq
+ArchiveFoo
+ArchiveBar
+\&...
+
+# {VAR:NUMBER} \- pad to NUMBER columns.
+# Strings are left\-aligned, numbers are right\-aligned.
+# Note: time columns except \(ga\(gaisomtime\(ga\(ga, \(ga\(gaisoctime\(ga\(ga and \(ga\(gaisoatime\(ga\(ga cannot be padded.
+$ borg rlist \-\-format \(aq{archive:36} {time} [{id}]{NL}\(aq /path/to/repo
+ArchiveFoo                           Thu, 2021\-12\-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274]
+\&...
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The following keys are always available:
+\- NEWLINE: OS dependent line separator
+\- NL: alias of NEWLINE
+\- NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below
+\- SPACE
+\- TAB
+\- CR
+\- LF
+.sp
+Keys available only when listing archives in a repository:
+.INDENT 0.0
+.IP \(bu 2
+archive: archive name interpreted as text (might be missing non\-text characters, see barchive)
+.IP \(bu 2
+name: alias of "archive"
+.IP \(bu 2
+barchive: verbatim archive name, can contain any character except NUL
+.IP \(bu 2
+comment: archive comment interpreted as text (might be missing non\-text characters, see bcomment)
+.IP \(bu 2
+bcomment: verbatim archive comment, can contain any character except NUL
+.IP \(bu 2
+id: internal ID of the archive
+.IP \(bu 2
+start: time (start) of creation of the archive
+.IP \(bu 2
+time: alias of "start"
+.IP \(bu 2
+end: time (end) of creation of the archive
+.IP \(bu 2
+command_line: command line which was used to create the archive
+.IP \(bu 2
+hostname: hostname of host on which this archive was created
+.IP \(bu 2
+username: username of user who created this archive
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-serve.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-SERVE 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-serve \- Start in server mode. This command is usually not used manually.
 .
 .nr rst2man-indent-level 0
 .
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-SERVE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-serve \- Start in server mode. This command is usually not used manually.
 .SH SYNOPSIS
 .sp
 borg [common options] serve [options]
@@ -48,7 +48,7 @@ restrict repository access to PATH. Can be specified multiple times to allow the
 .BI \-\-restrict\-to\-repository \ PATH
 restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
 .TP
-.B \-\-append\-only
+.B  \-\-append\-only
 only allow appending to repository segment files. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details.
 .TP
 .BI \-\-storage\-quota \ QUOTA

docs/man/borg-transfer.1

@@ -0,0 +1,100 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "BORG-TRANSFER" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-transfer \- archives transfer from other repository
+.SH SYNOPSIS
+.sp
+borg [common options] transfer [options]
+.SH DESCRIPTION
+.sp
+This command transfers archives from one repository to another repository.
+.sp
+Suggested use:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# initialize DST_REPO reusing key material from SRC_REPO, so that
+# chunking and chunk id generation will work in the same way as before.
+borg \-\-repo=DST_REPO init \-\-other\-repo=SRC_REPO \-\-encryption=DST_ENC
+
+# transfer archives from SRC_REPO to DST_REPO
+borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run  # check what it would do
+borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO            # do it!
+borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run  # check! anything left?
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The default is to transfer all archives, including checkpoint archives.
+.sp
+You could use the misc. archive filter options to limit which archives it will
+transfer, e.g. using the \-a option. This is recommended for big
+repositories with multiple data sets to keep the runtime per invocation lower.
+.SH OPTIONS
+.sp
+See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS optional arguments
+.INDENT 0.0
+.TP
+.B  \-n\fP,\fB  \-\-dry\-run
+do not change repository, just check
+.TP
+.BI \-\-other\-repo \ SRC_REPOSITORY
+transfer archives from the other repository
+.UNINDENT
+.SS Archive filters
+.INDENT 0.0
+.TP
+.BI \-P \ PREFIX\fR,\fB \ \-\-prefix \ PREFIX
+only consider archive names starting with this prefix.
+.TP
+.BI \-a \ GLOB\fR,\fB \ \-\-glob\-archives \ GLOB
+only consider archive names matching the glob. sh: rules apply, see "borg help patterns". \fB\-\-prefix\fP and \fB\-\-glob\-archives\fP are mutually exclusive.
+.TP
+.BI \-\-sort\-by \ KEYS
+Comma\-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+.TP
+.BI \-\-first \ N
+consider first N archives after other filters were applied
+.TP
+.BI \-\-last \ N
+consider last N archives after other filters were applied
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fIborg\-common(1)\fP
+.SH AUTHOR
+The Borg Collective
+.\" Generated by docutils manpage writer.
+.

docs/man/borg-umount.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UMOUNT 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-umount \- un-mount the FUSE filesystem
 .
 .nr rst2man-indent-level 0
 .
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-UMOUNT" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-umount \- un-mount the FUSE filesystem
 .SH SYNOPSIS
 .sp
 borg [common options] umount [options] MOUNTPOINT
@@ -57,21 +57,14 @@ mountpoint of the filesystem to umount
 # Mounting the repository shows all archives.
 # Archives are loaded lazily, expect some delay when navigating to an archive
 # for the first time.
-$ borg mount /path/to/repo /tmp/mymountpoint
+$ borg mount /tmp/mymountpoint
 $ ls /tmp/mymountpoint
 root\-2016\-02\-14 root\-2016\-02\-15
 $ borg umount /tmp/mymountpoint
 
-# Mounting a specific archive is possible as well.
-$ borg mount /path/to/repo::root\-2016\-02\-15 /tmp/mymountpoint
-$ ls /tmp/mymountpoint
-bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt
-root  sbin  srv  tmp  usr  var
-$ borg umount /tmp/mymountpoint
-
 # The "versions view" merges all archives in the repository
 # and provides a versioned view on files.
-$ borg mount \-o versions /path/to/repo /tmp/mymountpoint
+$ borg mount \-o versions /tmp/mymountpoint
 $ ls \-l /tmp/mymountpoint/home/user/doc.txt/
 total 24
 \-rw\-rw\-r\-\- 1 user group 12357 Aug 26 21:19 doc.cda00bc9.txt
@@ -81,12 +74,12 @@ $ borg umount /tmp/mymountpoint
 # Archive filters are supported.
 # These are especially handy for the "versions view",
 # which does not support lazy processing of archives.
-$ borg mount \-o versions \-\-glob\-archives \(aq*\-my\-home\(aq \-\-last 10 /path/to/repo /tmp/mymountpoint
+$ borg mount \-o versions \-\-glob\-archives \(aq*\-my\-home\(aq \-\-last 10 /tmp/mymountpoint
 
 # Exclusion options are supported.
 # These can speed up mounting and lower memory needs significantly.
 $ borg mount /path/to/repo /tmp/mymountpoint only/that/path
-$ borg mount \-\-exclude \(aq...\(aq /path/to/repo /tmp/mymountpoint
+$ borg mount \-\-exclude \(aq...\(aq /tmp/mymountpoint
 .ft P
 .fi
 .UNINDENT
@@ -98,13 +91,9 @@ $ borg mount \-\-exclude \(aq...\(aq /path/to/repo /tmp/mymountpoint
 .nf
 .ft C
 $ echo \(aq/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
-$ echo \(aq/mnt/backup::root\-2016\-02\-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0\(aq >> /etc/fstab
 $ mount /tmp/myrepo
-$ mount /tmp/myarchive
 $ ls /tmp/myrepo
 root\-2016\-02\-01 root\-2016\-02\-2015
-$ ls /tmp/myarchive
-bin  boot  etc      home  lib  lib64  lost+found  media  mnt  opt  root  sbin  srv  tmp  usr  var
 .ft P
 .fi
 .UNINDENT

docs/man/borg-upgrade.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-upgrade \- upgrade a repository from a previous version
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-UPGRADE" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-upgrade \- upgrade a repository from a previous version
 .SH SYNOPSIS
 .sp
-borg [common options] upgrade [options] [REPOSITORY]
+borg [common options] upgrade [options]
 .SH DESCRIPTION
 .sp
 Upgrade an existing, local Borg repository.
@@ -84,28 +84,22 @@ See \fB\-\-chunker\-params\fP option of \fBborg create\fP and \fBborg recreate\f
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS arguments
-.INDENT 0.0
-.TP
-.B REPOSITORY
-path to the repository to be upgraded
-.UNINDENT
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-n\fP,\fB  \-\-dry\-run
+.B  \-n\fP,\fB  \-\-dry\-run
 do not change repository
 .TP
-.B \-\-inplace
+.B  \-\-inplace
 rewrite repository in place, with no chance of going back to older versions of the repository.
 .TP
-.B \-\-force
+.B  \-\-force
 Force upgrade
 .TP
-.B \-\-tam
+.B  \-\-tam
 Enable manifest authentication (in key and cache) (Borg 1.0.9 and later).
 .TP
-.B \-\-disable\-tam
+.B  \-\-disable\-tam
 Disable manifest authentication (in key and cache).
 .UNINDENT
 .SH EXAMPLES

docs/man/borg-with-lock.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-WITH-LOCK 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg-with-lock \- run a user specified command with the repository lock held
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG-WITH-LOCK" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg-with-lock \- run a user specified command with the repository lock held
 .SH SYNOPSIS
 .sp
-borg [common options] with\-lock [options] REPOSITORY COMMAND [ARGS...]
+borg [common options] with\-lock [options] COMMAND [ARGS...]
 .SH DESCRIPTION
 .sp
 This command runs a user\-specified command while the repository lock is held.
@@ -57,9 +57,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPOSITORY
-repository to lock
-.TP
 .B COMMAND
 command to run
 .TP

docs/man/borg.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borg \- deduplicating and encrypting backup tool
 .
 .nr rst2man-indent-level 0
 .
@@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORG" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borg \- deduplicating and encrypting backup tool
 .SH SYNOPSIS
 .sp
 borg [common options] <command> [options] [arguments]
@@ -60,7 +60,7 @@ Before a backup can be made a repository has to be initialized:
 .sp
 .nf
 .ft C
-$ borg init \-\-encryption=repokey /path/to/repo
+$ borg \-r /path/to/repo rcreate \-\-encryption=repokey\-aes\-ocb
 .ft P
 .fi
 .UNINDENT
@@ -73,7 +73,7 @@ Backup the \fB~/src\fP and \fB~/Documents\fP directories into an archive called
 .sp
 .nf
 .ft C
-$ borg create /path/to/repo::Monday ~/src ~/Documents
+$ borg \-r /path/to/repo create Monday ~/src ~/Documents
 .ft P
 .fi
 .UNINDENT
@@ -85,7 +85,7 @@ The next day create a new archive called \fITuesday\fP:
 .sp
 .nf
 .ft C
-$ borg create \-\-stats /path/to/repo::Tuesday ~/src ~/Documents
+$ borg \-r /path/to/repo create \-\-stats Tuesday ~/src ~/Documents
 .ft P
 .fi
 .UNINDENT
@@ -93,29 +93,23 @@ $ borg create \-\-stats /path/to/repo::Tuesday ~/src ~/Documents
 .sp
 This backup will be a lot quicker and a lot smaller since only new never
 before seen data is stored. The \fB\-\-stats\fP option causes Borg to
-output statistics about the newly created archive such as the amount of unique
-data (not shared with other archives):
+output statistics about the newly created archive such as the deduplicated
+size (the amount of unique data not shared with other archives):
 .INDENT 3.0
 .INDENT 3.5
 .sp
 .nf
 .ft C
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+Repository: /path/to/repo
 Archive name: Tuesday
-Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
-Time (start): Tue, 2016\-02\-16 18:15:11
-Time (end):   Tue, 2016\-02\-16 18:15:11
-
-Duration: 0.19 seconds
-Number of files: 127
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
-                      Original size      Compressed size    Deduplicated size
-This archive:                4.16 MB              4.17 MB             26.78 kB
-All archives:                8.33 MB              8.34 MB              4.19 MB
-
-                      Unique chunks         Total chunks
-Chunk index:                     132                  261
-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+Archive fingerprint: bcd1b53f9b4991b7afc2b339f851b7ffe3c6d030688936fe4552eccc1877718d
+Time (start): Sat, 2022\-06\-25 20:21:43
+Time (end):   Sat, 2022\-06\-25 20:21:43
+Duration: 0.07 seconds
+Utilization of max. archive size: 0%
+Number of files: 699
+Original size: 31.14 MB
+Deduplicated size: 502 B
 .ft P
 .fi
 .UNINDENT
@@ -127,9 +121,9 @@ List all archives in the repository:
 .sp
 .nf
 .ft C
-$ borg list /path/to/repo
-Monday                               Mon, 2016\-02\-15 19:14:44
-Tuesday                              Tue, 2016\-02\-16 19:15:11
+$ borg \-r /path/to/repo rlist
+Monday                               Sat, 2022\-06\-25 20:21:14 [b80e24d2...b179f298]
+Tuesday                              Sat, 2022\-06\-25 20:21:43 [bcd1b53f...1877718d]
 .ft P
 .fi
 .UNINDENT
@@ -141,7 +135,7 @@ List the contents of the \fIMonday\fP archive:
 .sp
 .nf
 .ft C
-$ borg list /path/to/repo::Monday
+$ borg \-r /path/to/repo list Monday
 drwxr\-xr\-x user   group          0 Mon, 2016\-02\-15 18:22:30 home/user/Documents
 \-rw\-r\-\-r\-\- user   group       7961 Mon, 2016\-02\-15 18:22:30 home/user/Documents/Important.doc
 \&...
@@ -156,7 +150,7 @@ Restore the \fIMonday\fP archive by extracting the files relative to the current
 .sp
 .nf
 .ft C
-$ borg extract /path/to/repo::Monday
+$ borg \-r /path/to/repo extract Monday
 .ft P
 .fi
 .UNINDENT
@@ -168,11 +162,16 @@ Delete the \fIMonday\fP archive (please note that this does \fBnot\fP free repo
 .sp
 .nf
 .ft C
-$ borg delete /path/to/repo::Monday
+$ borg \-r /path/to/repo delete \-a Monday
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
+.sp
+Please note the \fB\-a\fP option here (short for \fB\-\-glob\-archives\fP) which enables you
+to give a globbing pattern to delete multiple archives, like \fB\-a \(aqoldcrap\-*\(aq\fP\&.
+You can also combine this with \fB\-\-first\fP, \fB\-\-last\fP and \fB\-\-sort\-by\fP\&.
+Be careful, always first use with \fB\-\-dry\-run\fP and \fB\-\-list\fP!
 .IP 8. 3
 Recover disk space by compacting the segment files in the repo:
 .INDENT 3.0
@@ -180,7 +179,7 @@ Recover disk space by compacting the segment files in the repo:
 .sp
 .nf
 .ft C
-$ borg compact /path/to/repo
+$ borg \-r /path/to/repo compact
 .ft P
 .fi
 .UNINDENT
@@ -208,10 +207,10 @@ in the example), but not in between them:
 .sp
 .nf
 .ft C
-borg create \-s \-\-progress repo::archive path  # good and preferred
-borg create repo::archive path \-s \-\-progress  # also works
-borg create \-s repo::archive path \-\-progress  # works, but ugly
-borg create repo::archive \-s \-\-progress path  # BAD
+borg create \-s \-\-progress archive path  # good and preferred
+borg create archive path \-s \-\-progress  # also works
+borg create \-s archive path \-\-progress  # works, but ugly
+borg create archive \-s \-\-progress path  # BAD
 .ft P
 .fi
 .UNINDENT
@@ -233,22 +232,7 @@ Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style
 .sp
 \fBRemote repositories\fP accessed via ssh \fI\%user@host\fP:
 .sp
-\fBuser@host:/path/to/repo\fP \- remote repo, absolute path
-.sp
-\fBssh://user@host:port/path/to/repo\fP \- same, alternative syntax, port can be given
-.sp
-\fBRemote repositories with relative paths\fP can be given using this syntax:
-.sp
-\fBuser@host:path/to/repo\fP \- path relative to current directory
-.sp
-\fBuser@host:~/path/to/repo\fP \- path relative to user\(aqs home directory
-.sp
-\fBuser@host:~other/path/to/repo\fP \- path relative to other\(aqs home directory
-.sp
-Note: giving \fBuser@host:/./path/to/repo\fP or \fBuser@host:/~/path/to/repo\fP or
-\fBuser@host:/~other/path/to/repo\fP is also supported, but not required here.
-.sp
-\fBRemote repositories with relative paths, alternative syntax with port\fP:
+\fBssh://user@host:port/path/to/repo\fP \- absolute path\(ga
 .sp
 \fBssh://user@host:port/./path/to/repo\fP \- path relative to current directory
 .sp
@@ -269,23 +253,21 @@ export BORG_REPO=\(aqssh://user@host:port/path/to/repo\(aq
 .UNINDENT
 .UNINDENT
 .sp
-Then just leave away the repo URL if only a repo URL is needed and you want
+Then just leave away the \fB\-\-repo\fP option if you want
 to use the default \- it will be read from BORG_REPO then.
+.SS Repository Locations / Archive names
 .sp
-Use \fB::\fP syntax to give the repo URL when syntax requires giving a positional
-argument for the repo (e.g. \fBborg mount :: /mnt\fP).
-.SS Repository / Archive Locations
+Many commands need to know the repository location, give it via \fB\-r\fP / \fB\-\-repo\fP
+or use the \fBBORG_REPO\fP environment variable.
 .sp
-Many commands want either a repository (just give the repo URL, see above) or
-an archive location, which is a repo URL followed by \fB::archive_name\fP\&.
+Commands needing one or two archive names usually get them as positional argument.
+.sp
+Commands working with an arbitrary amount of archives, usually take \fB\-a ARCH_GLOB\fP\&.
 .sp
 Archive names must not contain the \fB/\fP (slash) character. For simplicity,
 maybe also avoid blanks or other characters that have special meaning on the
 shell or in a filesystem (borg mount will use the archive name as directory
 name).
-.sp
-If you have set BORG_REPO (see above) and an archive location is needed, use
-\fB::archive_name\fP \- the repo URL part is then read from BORG_REPO.
 .SS Logging
 .sp
 Borg writes all log output to stderr by default. But please note that something
@@ -391,9 +373,11 @@ Borg uses some environment variables for automation:
 .INDENT 7.0
 .TP
 .B BORG_REPO
-When set, use the value to give the default repository location. If a command needs an archive
-parameter, you can abbreviate as \fB::archive\fP\&. If a command needs a repository parameter, you
-can either leave it away or abbreviate as \fB::\fP, if a positional parameter is required.
+When set, use the value to give the default repository location.
+Use this so you do not need to type \fB\-\-repo /path/to/my/repo\fP all the time.
+.TP
+.B BORG_OTHER_REPO
+Similar to BORG_REPO, but gives the default for \fB\-\-other\-repo\fP\&.
 .TP
 .B BORG_PASSPHRASE
 When set, use the value to answer the passphrase question for encrypted repositories.
@@ -614,7 +598,8 @@ know a list of affected hardware.
 If you are suspicious whether your Borg repository is still consistent
 and readable after one of the failures mentioned above occurred, run
 \fBborg check \-\-verify\-data\fP to make sure it is consistent.
-Requirements for Borg repository file systems.INDENT 0.0
+Requirements for Borg repository file systems
+.INDENT 0.0
 .IP \(bu 2
 Long file names
 .IP \(bu 2
@@ -772,7 +757,7 @@ special file \fIcontents\fP can be backed up in \fB\-\-read\-special\fP mode.
 By default the metadata to create them with mknod(2), mkfifo(2) etc. is stored.
 .UNINDENT
 .IP \(bu 2
-hardlinked regular files, devices, FIFOs (considering all items in the same archive)
+hardlinked regular files, devices, symlinks, FIFOs (considering all items in the same archive)
 .IP \(bu 2
 timestamps in nanosecond precision: mtime, atime, ctime
 .IP \(bu 2
@@ -907,10 +892,10 @@ The BSDs define additional flags.
 .sp
 \fIborg\-common(1)\fP for common command line options
 .sp
-\fIborg\-init(1)\fP,
+\fIborg\-rcreate(1)\fP, \fIborg\-rdelete(1)\fP, \fIborg\-rlist(1)\fP, \fIborg\-rinfo(1)\fP,
 \fIborg\-create(1)\fP, \fIborg\-mount(1)\fP, \fIborg\-extract(1)\fP,
 \fIborg\-list(1)\fP, \fIborg\-info(1)\fP,
-\fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP,
+\fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-compact(1)\fP,
 \fIborg\-recreate(1)\fP
 .sp
 \fIborg\-compression(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP

docs/man/borgfs.1

@@ -1,8 +1,5 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORGFS 1 "2022-04-14" "" "borg backup tool"
-.SH NAME
-borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .
 .nr rst2man-indent-level 0
 .
@@ -30,9 +27,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
+.TH "BORGFS" 1 "2022-06-25" "" "borg backup tool"
+.SH NAME
+borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .SH SYNOPSIS
 .sp
-borgfs [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
+borgfs [options] MOUNTPOINT [PATH...]
 .SH DESCRIPTION
 .sp
 This command mounts an archive as a FUSE filesystem. This can be useful for
@@ -98,9 +98,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
 .SS arguments
 .INDENT 0.0
 .TP
-.B REPOSITORY_OR_ARCHIVE
-repository or archive to mount
-.TP
 .B MOUNTPOINT
 where to mount filesystem
 .TP
@@ -110,22 +107,22 @@ paths to extract; patterns are supported
 .SS optional arguments
 .INDENT 0.0
 .TP
-.B \-V\fP,\fB  \-\-version
+.B  \-V\fP,\fB  \-\-version
 show version number and exit
 .TP
-.B \-\-consider\-checkpoints
+.B  \-\-consider\-checkpoints
 Show checkpoint archives in the repository contents list (default: hidden).
 .TP
-.B \-f\fP,\fB  \-\-foreground
+.B  \-f\fP,\fB  \-\-foreground
 stay in foreground, do not daemonize
 .TP
-.B \-o
+.B  \-o
 Extra mount options
 .TP
-.B \-\-numeric\-owner
+.B  \-\-numeric\-owner
 deprecated, use \fB\-\-numeric\-ids\fP instead
 .TP
-.B \-\-numeric\-ids
+.B  \-\-numeric\-ids
 use numeric user and group identifiers from archive(s)
 .UNINDENT
 .SS Archive filters

docs/man_intro.rst

@@ -42,10 +42,10 @@ SEE ALSO
 
 `borg-common(1)` for common command line options
 
-`borg-init(1)`,
+`borg-rcreate(1)`, `borg-rdelete(1)`, `borg-rlist(1)`, `borg-rinfo(1)`,
 `borg-create(1)`, `borg-mount(1)`, `borg-extract(1)`,
 `borg-list(1)`, `borg-info(1)`,
-`borg-delete(1)`, `borg-prune(1)`,
+`borg-delete(1)`, `borg-prune(1)`, `borg-compact(1)`,
 `borg-recreate(1)`
 
 `borg-compression(1)`, `borg-patterns(1)`, `borg-placeholders(1)`

docs/quickstart.rst

@@ -39,7 +39,7 @@ on file systems which do not support this mechanism (e.g. XFS) we recommend to r
 some space in Borg itself just to be safe by adjusting the ``additional_free_space``
 setting (a good starting point is ``2G``)::
 
-    borg config /path/to/repo additional_free_space 2G
+    borg config additional_free_space 2G
 
 If Borg runs out of disk space, it tries to free as much space as it
 can while aborting the current operation safely, which allows the user to free more space
@@ -47,8 +47,7 @@ by deleting/pruning archives. This mechanism is not bullet-proof in some
 circumstances [1]_.
 
 If you *really* run out of disk space, it can be hard or impossible to free space,
-because Borg needs free space to operate - even to delete backup
-archives.
+because Borg needs free space to operate - even to delete backup archives.
 
 You can use some monitoring process or just include the free space information
 in your backup log files (you check them regularly anyway, right?).
@@ -185,7 +184,7 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac
         --exclude 'home/*/.cache/*'     \
         --exclude 'var/tmp/*'           \
                                         \
-        ::'{hostname}-{now}'            \
+        '{hostname}-{now}'              \
         /etc                            \
         /home                           \
         /root                           \
@@ -315,30 +314,29 @@ You can use zstd for a wide range from high speed (and relatively low
 compression) using N=1 to high compression (and lower speed) using N=22.
 
 zstd is a modern compression algorithm and might be preferable over zlib and
-lzma, except if you need compatibility to older borg versions (< 1.1.4) that
-did not yet offer zstd.::
+lzma.::
 
-    $ borg create --compression zstd,N /path/to/repo::arch ~
+    $ borg create --compression zstd,N arch ~
 
 Other options are:
 
 If you have a fast repo storage and you want minimum CPU usage, no compression::
 
-    $ borg create --compression none /path/to/repo::arch ~
+    $ borg create --compression none arch ~
 
 If you have a less fast repo storage and you want a bit more compression (N=0..9,
 0 means no compression, 9 means high compression):
 
 ::
 
-    $ borg create --compression zlib,N /path/to/repo::arch ~
+    $ borg create --compression zlib,N arch ~
 
 If you have a very slow repo storage and you want high compression (N=0..9, 0 means
 low compression, 9 means high compression):
 
 ::
 
-    $ borg create --compression lzma,N /path/to/repo::arch ~
+    $ borg create --compression lzma,N arch ~
 
 You'll need to experiment a bit to find the best compression for your use case.
 Keep an eye on CPU load and throughput.
@@ -350,10 +348,10 @@ Repository encryption
 
 You can choose the repository encryption mode at repository creation time::
 
-    $ borg init --encryption=MODE PATH
+    $ borg rcreate --encryption=MODE
 
 For a list of available encryption MODEs and their descriptions, please refer
-to :ref:`borg_init`.
+to :ref:`borg_rcreate`.
 
 If you use encryption, all data is encrypted on the client before being written
 to the repository.
@@ -387,13 +385,6 @@ For automated backups the passphrase can be specified using the
     A backup inside of the backup that is encrypted with that key/passphrase
     won't help you with that, of course.
 
-    Only applies to repos using legacy encryption modes:
-    In case you lose your repository and the security information, but have an
-    older copy of it to restore from, don't use that later for creating new
-    backups – you would run into security issues (reuse of nonce counter
-    values). It is better to initialize a new Borg repository. See also:
-    :ref:`faq_corrupt_repo`
-
 .. _template: paperkey.html
 
 .. _remote_repos:
@@ -405,7 +396,7 @@ Borg can initialize and access repositories on remote hosts if the
 host is accessible using SSH.  This is fastest and easiest when Borg
 is installed on the remote host, in which case the following syntax is used::
 
-  $ borg init user@hostname:/path/to/repo
+  $ borg -r ssh://user@hostname:port/path/to/repo rcreate ...
 
 Note: please see the usage chapter for a full documentation of repo URLs.
 
@@ -421,7 +412,7 @@ it is still possible to use the remote host to store a repository by
 mounting the remote filesystem, for example, using sshfs::
 
   $ sshfs user@hostname:/path/to /path/to
-  $ borg init /path/to/repo
+  $ borg -r /path/to/repo rcreate ...
   $ fusermount -u /path/to
 
 You can also use other remote filesystems in a similar way. Just be careful,
@@ -517,13 +508,13 @@ Example with **borg mount**:
     # open a new, separate terminal (this terminal will be blocked until umount)
 
     # now we find out the archive names we have in the repo:
-    borg list /mnt/backup/borg_repo
+    borg rlist
 
     # mount one archive from a borg repo:
-    borg mount /mnt/backup/borg_repo::myserver-system-2019-08-11 /mnt/borg
+    borg mount -a myserver-system-2019-08-11 /mnt/borg
 
     # alternatively, mount all archives from a borg repo (slower):
-    borg mount /mnt/backup/borg_repo /mnt/borg
+    borg mount /mnt/borg
 
     # it may take a while until you will see stuff in /mnt/borg.
 
@@ -543,16 +534,16 @@ Example with **borg extract**:
     cd borg_restore
 
     # now we find out the archive names we have in the repo:
-    borg list /mnt/backup/borg_repo
+    borg rlist
 
     # we could find out the archive contents, esp. the path layout:
-    borg list /mnt/backup/borg_repo::myserver-system-2019-08-11
+    borg list myserver-system-2019-08-11
 
     # we extract only some specific path (note: no leading / !):
-    borg extract /mnt/backup/borg_repo::myserver-system-2019-08-11 path/to/extract
+    borg extract myserver-system-2019-08-11 path/to/extract
 
     # alternatively, we could fully extract the archive:
-    borg extract /mnt/backup/borg_repo::myserver-system-2019-08-11
+    borg extract myserver-system-2019-08-11
 
     # now move the files to the correct place...
 
@@ -574,6 +565,6 @@ case if unattended, automated backups were done).
 
 ::
 
-    borg mount ssh://borg@backup.example.org:2222/path/to/repo /mnt/borg
+    borg -r ssh://borg@backup.example.org:2222/path/to/repo mount /mnt/borg
     # or
-    borg extract ssh://borg@backup.example.org:2222/path/to/repo
+    borg -r ssh://borg@backup.example.org:2222/path/to/repo extract archive

docs/quickstart_example.rst.inc

@@ -1,62 +1,61 @@
 1. Before a backup can be made a repository has to be initialized::
 
-    $ borg init --encryption=repokey /path/to/repo
+    $ borg -r /path/to/repo rcreate --encryption=repokey-aes-ocb
 
 2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called
    *Monday*::
 
-    $ borg create /path/to/repo::Monday ~/src ~/Documents
+    $ borg -r /path/to/repo create Monday ~/src ~/Documents
 
 3. The next day create a new archive called *Tuesday*::
 
-    $ borg create --stats /path/to/repo::Tuesday ~/src ~/Documents
+    $ borg -r /path/to/repo create --stats Tuesday ~/src ~/Documents
 
    This backup will be a lot quicker and a lot smaller since only new never
    before seen data is stored. The ``--stats`` option causes Borg to
-   output statistics about the newly created archive such as the amount of unique
-   data (not shared with other archives)::
+   output statistics about the newly created archive such as the deduplicated
+   size (the amount of unique data not shared with other archives)::
 
-    ------------------------------------------------------------------------------
+    Repository: /path/to/repo
     Archive name: Tuesday
-    Archive fingerprint: bd31004d58f51ea06ff735d2e5ac49376901b21d58035f8fb05dbf866566e3c2
-    Time (start): Tue, 2016-02-16 18:15:11
-    Time (end):   Tue, 2016-02-16 18:15:11
-
-    Duration: 0.19 seconds
-    Number of files: 127
-    ------------------------------------------------------------------------------
-                          Original size      Compressed size    Deduplicated size
-    This archive:                4.16 MB              4.17 MB             26.78 kB
-    All archives:                8.33 MB              8.34 MB              4.19 MB
-
-                          Unique chunks         Total chunks
-    Chunk index:                     132                  261
-    ------------------------------------------------------------------------------
+    Archive fingerprint: bcd1b53f9b4991b7afc2b339f851b7ffe3c6d030688936fe4552eccc1877718d
+    Time (start): Sat, 2022-06-25 20:21:43
+    Time (end):   Sat, 2022-06-25 20:21:43
+    Duration: 0.07 seconds
+    Utilization of max. archive size: 0%
+    Number of files: 699
+    Original size: 31.14 MB
+    Deduplicated size: 502 B
 
 4. List all archives in the repository::
 
-    $ borg list /path/to/repo
-    Monday                               Mon, 2016-02-15 19:14:44
-    Tuesday                              Tue, 2016-02-16 19:15:11
+    $ borg -r /path/to/repo rlist
+    Monday                               Sat, 2022-06-25 20:21:14 [b80e24d2...b179f298]
+    Tuesday                              Sat, 2022-06-25 20:21:43 [bcd1b53f...1877718d]
 
 5. List the contents of the *Monday* archive::
 
-    $ borg list /path/to/repo::Monday
+    $ borg -r /path/to/repo list Monday
     drwxr-xr-x user   group          0 Mon, 2016-02-15 18:22:30 home/user/Documents
     -rw-r--r-- user   group       7961 Mon, 2016-02-15 18:22:30 home/user/Documents/Important.doc
     ...
 
 6. Restore the *Monday* archive by extracting the files relative to the current directory::
 
-    $ borg extract /path/to/repo::Monday
+    $ borg -r /path/to/repo extract Monday
 
 7. Delete the *Monday* archive (please note that this does **not** free repo disk space)::
 
-    $ borg delete /path/to/repo::Monday
+    $ borg -r /path/to/repo delete -a Monday
+
+   Please note the ``-a`` option here (short for ``--glob-archives``) which enables you
+   to give a globbing pattern to delete multiple archives, like ``-a 'oldcrap-*'``.
+   You can also combine this with ``--first``, ``--last`` and ``--sort-by``.
+   Be careful, always first use with ``--dry-run`` and ``--list``!
 
 8. Recover disk space by compacting the segment files in the repo::
 
-    $ borg compact /path/to/repo
+    $ borg -r /path/to/repo compact
 
 .. Note::
     Borg is quiet by default (it works on WARNING log level).

docs/usage.rst

@@ -36,7 +36,16 @@ Usage
 .. toctree::
    usage/general
 
-   usage/init
+   usage/rcreate
+   usage/rlist
+   usage/rinfo
+   usage/rdelete
+   usage/serve
+   usage/compact
+   usage/config
+   usage/lock
+   usage/key
+
    usage/create
    usage/extract
    usage/check
@@ -45,16 +54,13 @@ Usage
    usage/diff
    usage/delete
    usage/prune
-   usage/compact
    usage/info
    usage/mount
-   usage/key
-   usage/upgrade
    usage/recreate
    usage/tar
-   usage/serve
-   usage/config
-   usage/lock
+
+   usage/transfer
+   usage/upgrade
    usage/benchmark
 
    usage/help

docs/usage/benchmark_cpu.rst.inc

@@ -40,5 +40,6 @@ This command benchmarks misc. CPU bound borg operations.
 
 It creates input data in memory, runs the operation and then displays throughput.
 To reduce outside influence on the timings, please make sure to run this with:
+
 - an otherwise as idle as possible machine
 - enough free memory so there will be no slow down due to paging activity

docs/usage/benchmark_crud.rst.inc

@@ -6,23 +6,21 @@ borg benchmark crud
 -------------------
 .. code-block:: none
 
-    borg [common options] benchmark crud [options] REPOSITORY PATH
+    borg [common options] benchmark crud [options] PATH
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+----------------+----------------------------------------------+
-    | **positional arguments**                                                                                              |
-    +-------------------------------------------------------+----------------+----------------------------------------------+
-    |                                                       | ``REPOSITORY`` | repository to use for benchmark (must exist) |
-    +-------------------------------------------------------+----------------+----------------------------------------------+
-    |                                                       | ``PATH``       | path were to create benchmark input data     |
-    +-------------------------------------------------------+----------------+----------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                        |
-    |                                                                                                                       |
-    | :ref:`common_options`                                                                                                 |
-    +-------------------------------------------------------+----------------+----------------------------------------------+
+    +-------------------------------------------------------+----------+------------------------------------------+
+    | **positional arguments**                                                                                    |
+    +-------------------------------------------------------+----------+------------------------------------------+
+    |                                                       | ``PATH`` | path were to create benchmark input data |
+    +-------------------------------------------------------+----------+------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                              |
+    |                                                                                                             |
+    | :ref:`common_options`                                                                                       |
+    +-------------------------------------------------------+----------+------------------------------------------+
 
     .. raw:: html
 
@@ -34,8 +32,6 @@ borg benchmark crud
 
 .. only:: latex
 
-    REPOSITORY
-        repository to use for benchmark (must exist)
     PATH
         path were to create benchmark input data
 

docs/usage/break-lock.rst.inc

@@ -6,21 +6,17 @@ borg break-lock
 ---------------
 .. code-block:: none
 
-    borg [common options] break-lock [options] [REPOSITORY]
+    borg [common options] break-lock [options]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+----------------+-----------------------------------------+
-    | **positional arguments**                                                                                         |
-    +-------------------------------------------------------+----------------+-----------------------------------------+
-    |                                                       | ``REPOSITORY`` | repository for which to break the locks |
-    +-------------------------------------------------------+----------------+-----------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                   |
-    |                                                                                                                  |
-    | :ref:`common_options`                                                                                            |
-    +-------------------------------------------------------+----------------+-----------------------------------------+
+    +-------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                        |
+    |                                                       |
+    | :ref:`common_options`                                 |
+    +-------------------------------------------------------+
 
     .. raw:: html
 
@@ -32,8 +28,6 @@ borg break-lock
 
 .. only:: latex
 
-    REPOSITORY
-        repository for which to break the locks
 
 
     :ref:`common_options`

docs/usage/check.rst.inc

@@ -6,19 +6,17 @@ borg check
 ----------
 .. code-block:: none
 
-    borg [common options] check [options] [REPOSITORY_OR_ARCHIVE]
+    borg [common options] check [options]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to check consistency of                                                                                                          |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                                                       |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--name NAME``                       | specify the archive name                                                                                                                               |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--repository-only``                 | only perform repository checks                                                                                                                         |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--archives-only``                   | only perform archives checks                                                                                                                           |
@@ -58,11 +56,10 @@ borg check
 
 .. only:: latex
 
-    REPOSITORY_OR_ARCHIVE
-        repository or archive to check consistency of
 
 
     optional arguments
+        --name NAME       specify the archive name
         --repository-only    only perform repository checks
         --archives-only    only perform archives checks
         --verify-data     perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)

docs/usage/common-options.rst.inc

@@ -1,23 +1,24 @@
--h, --help         show this help message and exit
---critical         work on log level CRITICAL
---error            work on log level ERROR
---warning          work on log level WARNING (default)
+-h, --help               show this help message and exit
+--critical               work on log level CRITICAL
+--error                  work on log level ERROR
+--warning                work on log level WARNING (default)
 --info, -v, --verbose    work on log level INFO
---debug            enable debug output, work on log level DEBUG
---debug-topic TOPIC    enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
--p, --progress     show progress information
---iec              format using IEC units (1KiB = 1024B)
---log-json         Output one JSON object per log line instead of formatted text.
---lock-wait SECONDS    wait at most SECONDS for acquiring a repository/cache lock (default: 1).
---bypass-lock      Bypass locking mechanism
---show-version     show/log the borg version
---show-rc          show/log the return code (rc)
---umask M          set umask to M (local only, default: 0077)
---remote-path PATH    use PATH as borg executable on the remote (default: "borg")
+--debug                  enable debug output, work on log level DEBUG
+--debug-topic TOPIC      enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
+-p, --progress           show progress information
+--iec                    format using IEC units (1KiB = 1024B)
+--log-json               Output one JSON object per log line instead of formatted text.
+--lock-wait SECONDS      wait at most SECONDS for acquiring a repository/cache lock (default: 1).
+--bypass-lock            Bypass locking mechanism
+--show-version           show/log the borg version
+--show-rc                show/log the return code (rc)
+--umask M                set umask to M (local only, default: 0077)
+--remote-path PATH       use PATH as borg executable on the remote (default: "borg")
 --remote-ratelimit RATE    deprecated, use ``--upload-ratelimit`` instead
 --upload-ratelimit RATE    set network upload rate limit in kiByte/s (default: 0=unlimited)
 --remote-buffer UPLOAD_BUFFER    deprecated, use ``--upload-buffer`` instead
 --upload-buffer UPLOAD_BUFFER    set network upload buffer size in MiB. (default: 0=no buffer)
 --consider-part-files    treat part files like normal files (e.g. to list/extract them)
---debug-profile FILE    Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".
---rsh RSH          Use this command to connect to the 'borg serve' process (default: 'ssh')
+--debug-profile FILE     Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".
+--rsh RSH                Use this command to connect to the 'borg serve' process (default: 'ssh')
+-r REPO, --repo REPO     repository to use

docs/usage/compact.rst

@@ -5,9 +5,4 @@ Examples
 ::
 
     # compact segments and free repo disk space
-    $ borg compact /path/to/repo
-
-    # same as above plus clean up 17byte commit-only segments
-    $ borg compact --cleanup-commits /path/to/repo
-
-
+    $ borg compact

docs/usage/compact.rst.inc

@@ -6,16 +6,12 @@ borg compact
 ------------
 .. code-block:: none
 
-    borg [common options] compact [options] [REPOSITORY]
+    borg [common options] compact [options]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
-    | **positional arguments**                                                                                                                         |
-    +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
-    |                                                       | ``REPOSITORY``          | repository to compact                                          |
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
     | **optional arguments**                                                                                                                           |
     +-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
@@ -38,8 +34,6 @@ borg compact
 
 .. only:: latex
 
-    REPOSITORY
-        repository to compact
 
 
     optional arguments

docs/usage/config.rst

@@ -11,12 +11,12 @@ Examples
 ::
 
     # find cache directory
-    $ cd ~/.cache/borg/$(borg config /path/to/repo id)
+    $ cd ~/.cache/borg/$(borg config id)
 
     # reserve some space
-    $ borg config /path/to/repo additional_free_space 2G
+    $ borg config additional_free_space 2G
 
     # make a repo append-only
-    $ borg config /path/to/repo append_only 1
+    $ borg config append_only 1
 
 

docs/usage/config.rst.inc

@@ -6,7 +6,7 @@ borg config
 -----------
 .. code-block:: none
 
-    borg [common options] config [options] [REPOSITORY] [NAME] [VALUE]
+    borg [common options] config [options] [NAME] [VALUE]
 
 .. only:: html
 
@@ -15,8 +15,6 @@ borg config
     +-------------------------------------------------------+----------------------+----------------------------------------+
     | **positional arguments**                                                                                              |
     +-------------------------------------------------------+----------------------+----------------------------------------+
-    |                                                       | ``REPOSITORY``       | repository to configure                |
-    +-------------------------------------------------------+----------------------+----------------------------------------+
     |                                                       | ``NAME``             | name of config key                     |
     +-------------------------------------------------------+----------------------+----------------------------------------+
     |                                                       | ``VALUE``            | new value for key                      |
@@ -44,8 +42,6 @@ borg config
 
 .. only:: latex
 
-    REPOSITORY
-        repository to configure
     NAME
         name of config key
     VALUE

docs/usage/create.rst

@@ -5,83 +5,81 @@ Examples
 ::
 
     # Backup ~/Documents into an archive named "my-documents"
-    $ borg create /path/to/repo::my-documents ~/Documents
+    $ borg create my-documents ~/Documents
 
     # same, but list all files as we process them
-    $ borg create --list /path/to/repo::my-documents ~/Documents
+    $ borg create --list my-documents ~/Documents
 
     # Backup ~/Documents and ~/src but exclude pyc files
-    $ borg create /path/to/repo::my-files \
+    $ borg create my-files                \
         ~/Documents                       \
         ~/src                             \
         --exclude '*.pyc'
 
     # Backup home directories excluding image thumbnails (i.e. only
     # /home/<one directory>/.thumbnails is excluded, not /home/*/*/.thumbnails etc.)
-    $ borg create /path/to/repo::my-files /home \
-        --exclude 'sh:home/*/.thumbnails'
+    $ borg create my-files /home --exclude 'sh:home/*/.thumbnails'
 
     # Backup the root filesystem into an archive named "root-YYYY-MM-DD"
     # use zlib compression (good, but slow) - default is lz4 (fast, low compression ratio)
-    $ borg create -C zlib,6 --one-file-system /path/to/repo::root-{now:%Y-%m-%d} /
+    $ borg create -C zlib,6 --one-file-system root-{now:%Y-%m-%d} /
 
-    # Backup onto a remote host ("push" style) via ssh to port 2222,
-    # logging in as user "borg" and storing into /path/to/repo
-    $ borg create ssh://borg@backup.example.org:2222/path/to/repo::{fqdn}-root-{now} /
+    # Backup into an archive name like FQDN-root-TIMESTAMP
+    $ borg create '{fqdn}-root-{now}' /
 
     # Backup a remote host locally ("pull" style) using sshfs
     $ mkdir sshfs-mount
     $ sshfs root@example.com:/ sshfs-mount
     $ cd sshfs-mount
-    $ borg create /path/to/repo::example.com-root-{now:%Y-%m-%d} .
+    $ borg create example.com-root-{now:%Y-%m-%d} .
     $ cd ..
     $ fusermount -u sshfs-mount
 
     # Make a big effort in fine granular deduplication (big chunk management
     # overhead, needs a lot of RAM and disk space, see formula in internals
     # docs - same parameters as borg < 1.0 or attic):
-    $ borg create --chunker-params buzhash,10,23,16,4095 /path/to/repo::small /smallstuff
+    $ borg create --chunker-params buzhash,10,23,16,4095 small /smallstuff
 
     # Backup a raw device (must not be active/in use/mounted at that time)
-    $ borg create --read-special --chunker-params fixed,4194304 /path/to/repo::my-sdx /dev/sdX
+    $ borg create --read-special --chunker-params fixed,4194304 my-sdx /dev/sdX
 
     # Backup a sparse disk image (must not be active/in use/mounted at that time)
-    $ borg create --sparse --chunker-params fixed,4194304 /path/to/repo::my-disk my-disk.raw
+    $ borg create --sparse --chunker-params fixed,4194304 my-disk my-disk.raw
 
     # No compression (none)
-    $ borg create --compression none /path/to/repo::arch ~
+    $ borg create --compression none arch ~
 
     # Super fast, low compression (lz4, default)
-    $ borg create /path/to/repo::arch ~
+    $ borg create arch ~
 
     # Less fast, higher compression (zlib, N = 0..9)
-    $ borg create --compression zlib,N /path/to/repo::arch ~
+    $ borg create --compression zlib,N arch ~
 
     # Even slower, even higher compression (lzma, N = 0..9)
-    $ borg create --compression lzma,N /path/to/repo::arch ~
+    $ borg create --compression lzma,N arch ~
 
     # Only compress compressible data with lzma,N (N = 0..9)
-    $ borg create --compression auto,lzma,N /path/to/repo::arch ~
+    $ borg create --compression auto,lzma,N arch ~
 
     # Use short hostname, user name and current time in archive name
-    $ borg create /path/to/repo::{hostname}-{user}-{now} ~
+    $ borg create '{hostname}-{user}-{now}' ~
     # Similar, use the same datetime format that is default as of borg 1.1
-    $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S} ~
+    $ borg create '{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S}' ~
     # As above, but add nanoseconds
-    $ borg create /path/to/repo::{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S.%f} ~
+    $ borg create '{hostname}-{user}-{now:%Y-%m-%dT%H:%M:%S.%f}' ~
 
     # Backing up relative paths by moving into the correct directory first
     $ cd /home/user/Documents
     # The root directory of the archive will be "projectA"
-    $ borg create /path/to/repo::daily-projectA-{now:%Y-%m-%d} projectA
+    $ borg create 'daily-projectA-{now:%Y-%m-%d}' projectA
 
     # Use external command to determine files to archive
     # Use --paths-from-stdin with find to only backup files less than 1MB in size
-    $ find ~ -size -1000k | borg create --paths-from-stdin /path/to/repo::small-files-only
+    $ find ~ -size -1000k | borg create --paths-from-stdin small-files-only
     # Use --paths-from-command with find to only backup files from a given user
-    $ borg create --paths-from-command /path/to/repo::joes-files -- find /srv/samba/shared -user joe
+    $ borg create --paths-from-command joes-files -- find /srv/samba/shared -user joe
     # Use --paths-from-stdin with --paths-delimiter (for example, for filenames with newlines in them)
     $ find ~ -size -1000k -print0 | borg create \
         --paths-from-stdin \
         --paths-delimiter "\0" \
-        /path/to/repo::smallfiles-handle-newline
+        smallfiles-handle-newline

docs/usage/create.rst.inc

@@ -6,7 +6,7 @@ borg create
 -----------
 .. code-block:: none
 
-    borg [common options] create [options] ARCHIVE [PATH...]
+    borg [common options] create [options] NAME [PATH...]
 
 .. only:: html
 
@@ -15,7 +15,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                                                                         |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                                      |
+    |                                                       | ``NAME``                                          | specify the archive name                                                                                                                             |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                                          | paths to archive                                                                                                                                     |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -37,7 +37,7 @@ borg create
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-user USER``                             | set user USER in archive for stdin data (default: 'root')                                                                                            |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'root')                                                                                          |
+    |                                                       | ``--stdin-group GROUP``                           | set group GROUP in archive for stdin data (default: 'wheel')                                                                                         |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--stdin-mode M``                                | set mode to M in archive for stdin data (default: 0660)                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -124,8 +124,8 @@ borg create
 
 .. only:: latex
 
-    ARCHIVE
-        name of archive to create (must be also a valid directory name)
+    NAME
+        specify the archive name
     PATH
         paths to archive
 
@@ -139,7 +139,7 @@ borg create
         --no-cache-sync    experimental: do not synchronize the cache. Implies not using the files cache.
         --stdin-name NAME    use NAME in archive for stdin data (default: 'stdin')
         --stdin-user USER    set user USER in archive for stdin data (default: 'root')
-        --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'root')
+        --stdin-group GROUP    set group GROUP in archive for stdin data (default: 'wheel')
         --stdin-mode M    set mode to M in archive for stdin data (default: 0660)
         --content-from-command    interpret PATH as command and store its stdout. See also section Reading from stdin below.
         --paths-from-stdin    read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.

docs/usage/delete.rst

@@ -5,23 +5,15 @@ Examples
 ::
 
     # delete a single backup archive:
-    $ borg delete /path/to/repo::Monday
+    $ borg delete Monday
     # actually free disk space:
-    $ borg compact /path/to/repo
+    $ borg compact
 
     # delete all archives whose names begin with the machine's hostname followed by "-"
-    $ borg delete --prefix '{hostname}-' /path/to/repo
+    $ borg delete --prefix '{hostname}-'
 
     # delete all archives whose names contain "-2012-"
-    $ borg delete --glob-archives '*-2012-*' /path/to/repo
+    $ borg delete -a '*-2012-*'
 
     # see what would be deleted if delete was run without --dry-run
-    $ borg delete --list --dry-run -a '*-May-*' /path/to/repo
-
-    # delete the whole repository and the related local cache:
-    $ borg delete /path/to/repo
-    You requested to completely DELETE the repository *including* all archives it contains:
-    repo                                 Mon, 2016-02-15 19:26:54
-    root-2016-02-15                      Mon, 2016-02-15 19:36:29
-    newname                              Mon, 2016-02-15 19:50:19
-    Type 'YES' if you understand this and want to continue: YES
+    $ borg delete --list --dry-run -a '*-May-*'

docs/usage/delete.rst.inc

@@ -6,18 +6,12 @@ borg delete
 -----------
 .. code-block:: none
 
-    borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...]
+    borg [common options] delete [options]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to delete                                                                                                                        |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``ARCHIVE``                           | archives to delete                                                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                                                       |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -25,6 +19,8 @@ borg delete
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--list``                            | output verbose list of archives                                                                                                                        |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--consider-checkpoints``            | consider checkpoint archives for deletion (default: not considered).                                                                                   |
+    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``-s``, ``--stats``                   | print statistics for the deleted archive                                                                                                               |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``--cache-only``                      | delete only the local cache for the given repository                                                                                                   |
@@ -62,15 +58,12 @@ borg delete
 
 .. only:: latex
 
-    REPOSITORY_OR_ARCHIVE
-        repository or archive to delete
-    ARCHIVE
-        archives to delete
 
 
     optional arguments
         -n, --dry-run    do not change repository
         --list          output verbose list of archives
+        --consider-checkpoints    consider checkpoint archives for deletion (default: not considered).
         -s, --stats     print statistics for the deleted archive
         --cache-only    delete only the local cache for the given repository
         --force         force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
@@ -92,16 +85,11 @@ borg delete
 Description
 ~~~~~~~~~~~
 
-This command deletes an archive from the repository or the complete repository.
+This command deletes archives from the repository.
 
 Important: When deleting archives, repository disk space is **not** freed until
 you run ``borg compact``.
 
-When you delete a complete repository, the security info and local cache for it
-(if any) are also deleted. Alternatively, you can delete just the local cache
-with the ``--cache-only`` option, or keep the security info with the
-``--keep-security-info`` option.
-
 When in doubt, use ``--dry-run --list`` to see what would be deleted.
 
 When using ``--stats``, you will get some statistics about how much data was
@@ -115,6 +103,4 @@ pattern to match multiple archives using the ``--glob-archives GLOB`` option
 (for more info on these patterns, see :ref:`borg_patterns`). Note that these
 two options are mutually exclusive.
 
-To avoid accidentally deleting archives, especially when using glob patterns,
-it might be helpful to use the ``--dry-run`` to test out the command without
-actually making any changes to the repository.
+Always first use ``--dry-run --list`` to see what would be deleted.

docs/usage/diff.rst

@@ -4,41 +4,14 @@ Examples
 ~~~~~~~~
 ::
 
-    $ borg init -e=none testrepo
-    $ mkdir testdir
-    $ cd testdir
-    $ echo asdf > file1
-    $ dd if=/dev/urandom bs=1M count=4 > file2
-    $ touch file3
-    $ borg create ../testrepo::archive1 .
-
-    $ chmod a+x file1
-    $ echo "something" >> file2
-    $ borg create ../testrepo::archive2 .
-
-    $ echo "testing 123" >> file1
-    $ rm file3
-    $ touch file4
-    $ borg create ../testrepo::archive3 .
-
-    $ cd ..
-    $ borg diff testrepo::archive1 archive2
-    [-rw-r--r-- -> -rwxr-xr-x] file1
-       +135 B    -252 B file2
-
-    $ borg diff testrepo::archive2 archive3
-        +17 B      -5 B file1
-    added           0 B file4
-    removed         0 B file3
-
-    $ borg diff testrepo::archive1 archive3
+    $ borg diff archive1 archive2
         +17 B      -5 B [-rw-r--r-- -> -rwxr-xr-x] file1
        +135 B    -252 B file2
     added           0 B file4
     removed         0 B file3
 
-    $ borg diff --json-lines testrepo::archive1 archive3
+    $ borg diff archive1 archive2
     {"path": "file1", "changes": [{"type": "modified", "added": 17, "removed": 5}, {"type": "mode", "old_mode": "-rw-r--r--", "new_mode": "-rwxr-xr-x"}]}
     {"path": "file2", "changes": [{"type": "modified", "added": 135, "removed": 252}]}
     {"path": "file4", "changes": [{"type": "added", "size": 0}]}
-    {"path": "file3", "changes": [{"type": "removed", "size": 0}]}
+    {"path": "file3", "changes": [{"type": "removed", "size": 0}]}

docs/usage/diff.rst.inc

@@ -6,7 +6,7 @@ borg diff
 ---------
 .. code-block:: none
 
-    borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...]
+    borg [common options] diff [options] ARCHIVE1 ARCHIVE2 [PATH...]
 
 .. only:: html
 
@@ -15,9 +15,9 @@ borg diff
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                              |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``REPO::ARCHIVE1``                    | repository location and ARCHIVE1 name                                 |
+    |                                                       | ``ARCHIVE1``                          | ARCHIVE1 name                                                         |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE2``                          | ARCHIVE2 name (no repository location allowed)                        |
+    |                                                       | ``ARCHIVE2``                          | ARCHIVE2 name                                                         |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths of items inside the archives to compare; patterns are supported |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+
@@ -58,10 +58,10 @@ borg diff
 
 .. only:: latex
 
-    REPO::ARCHIVE1
-        repository location and ARCHIVE1 name
+    ARCHIVE1
+        ARCHIVE1 name
     ARCHIVE2
-        ARCHIVE2 name (no repository location allowed)
+        ARCHIVE2 name
     PATH
         paths of items inside the archives to compare; patterns are supported
 

docs/usage/export-tar.rst.inc

@@ -6,7 +6,7 @@ borg export-tar
 ---------------
 .. code-block:: none
 
-    borg [common options] export-tar [options] ARCHIVE FILE [PATH...]
+    borg [common options] export-tar [options] NAME FILE [PATH...]
 
 .. only:: html
 
@@ -15,7 +15,7 @@ borg export-tar
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                           | archive to export                                                                                         |
+    |                                                       | ``NAME``                              | specify the archive name                                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``FILE``                              | output tar file. "-" to write to stdout instead.                                                          |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -56,8 +56,8 @@ borg export-tar
 
 .. only:: latex
 
-    ARCHIVE
-        archive to export
+    NAME
+        specify the archive name
     FILE
         output tar file. "-" to write to stdout instead.
     PATH

docs/usage/extract.rst

@@ -5,19 +5,19 @@ Examples
 ::
 
     # Extract entire archive
-    $ borg extract /path/to/repo::my-files
+    $ borg extract my-files
 
     # Extract entire archive and list files while processing
-    $ borg extract --list /path/to/repo::my-files
+    $ borg extract --list my-files
 
     # Verify whether an archive could be successfully extracted, but do not write files to disk
-    $ borg extract --dry-run /path/to/repo::my-files
+    $ borg extract --dry-run my-files
 
     # Extract the "src" directory
-    $ borg extract /path/to/repo::my-files home/USERNAME/src
+    $ borg extract my-files home/USERNAME/src
 
     # Extract the "src" directory but exclude object files
-    $ borg extract /path/to/repo::my-files home/USERNAME/src --exclude '*.o'
+    $ borg extract my-files home/USERNAME/src --exclude '*.o'
 
     # Restore a raw device (must not be active/in use/mounted at that time)
-    $ borg extract --stdout /path/to/repo::my-sdx | dd of=/dev/sdx bs=10M
+    $ borg extract --stdout my-sdx | dd of=/dev/sdx bs=10M

docs/usage/extract.rst.inc

@@ -6,7 +6,7 @@ borg extract
 ------------
 .. code-block:: none
 
-    borg [common options] extract [options] ARCHIVE [PATH...]
+    borg [common options] extract [options] NAME [PATH...]
 
 .. only:: html
 
@@ -15,7 +15,7 @@ borg extract
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                           | archive to extract                                                                                        |
+    |                                                       | ``NAME``                              | specify the archive name                                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
     |                                                       | ``PATH``                              | paths to extract; patterns are supported                                                                  |
     +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+
@@ -68,8 +68,8 @@ borg extract
 
 .. only:: latex
 
-    ARCHIVE
-        archive to extract
+    NAME
+        specify the archive name
     PATH
         paths to extract; patterns are supported
 

docs/usage/general.rst

@@ -7,7 +7,7 @@ The following sections will describe each command in detail.
 
 Commands, options, parameters, paths and such are ``set in fixed-width``.
 Option values are `underlined`. Borg has few options accepting a fixed set
-of values (e.g. ``--encryption`` of :ref:`borg_init`).
+of values (e.g. ``--encryption`` of :ref:`borg_rcreate`).
 
 .. container:: experimental
 
@@ -54,5 +54,5 @@ Examples
 ::
 
     # Create an archive and log: borg version, files list, return code
-    $ borg create --show-version --list --show-rc /path/to/repo::my-files files
+    $ borg -r /path/to/repo create --show-version --list --show-rc my-files files
 

docs/usage/general/environment.rst.inc

@@ -5,9 +5,10 @@ Borg uses some environment variables for automation:
 
 General:
     BORG_REPO
-        When set, use the value to give the default repository location. If a command needs an archive
-        parameter, you can abbreviate as ``::archive``. If a command needs a repository parameter, you
-        can either leave it away or abbreviate as ``::``, if a positional parameter is required.
+        When set, use the value to give the default repository location.
+        Use this so you do not need to type ``--repo /path/to/my/repo`` all the time.
+    BORG_OTHER_REPO
+        Similar to BORG_REPO, but gives the default for ``--other-repo``.
     BORG_PASSPHRASE
         When set, use the value to answer the passphrase question for encrypted repositories.
         It is used when a passphrase is needed to access an encrypted repo as well as when a new

docs/usage/general/positional-arguments.rst.inc

@@ -7,9 +7,9 @@ in the example), but not in between them:
 
 ::
 
-    borg create -s --progress repo::archive path  # good and preferred
-    borg create repo::archive path -s --progress  # also works
-    borg create -s repo::archive path --progress  # works, but ugly
-    borg create repo::archive -s --progress path  # BAD
+    borg create -s --progress archive path  # good and preferred
+    borg create archive path -s --progress  # also works
+    borg create -s archive path --progress  # works, but ugly
+    borg create archive -s --progress path  # BAD
 
 This is due to a problem in the argparse module: https://bugs.python.org/issue15112

docs/usage/general/repository-locations.rst.inc

@@ -1,13 +1,14 @@
-Repository / Archive Locations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Repository Locations / Archive names
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Many commands want either a repository (just give the repo URL, see above) or
-an archive location, which is a repo URL followed by ``::archive_name``.
+Many commands need to know the repository location, give it via ``-r`` / ``--repo``
+or use the ``BORG_REPO`` environment variable.
+
+Commands needing one or two archive names usually get them as positional argument.
+
+Commands working with an arbitrary amount of archives, usually take ``-a ARCH_GLOB``.
 
 Archive names must not contain the ``/`` (slash) character. For simplicity,
 maybe also avoid blanks or other characters that have special meaning on the
 shell or in a filesystem (borg mount will use the archive name as directory
 name).
-
-If you have set BORG_REPO (see above) and an archive location is needed, use
-``::archive_name`` - the repo URL part is then read from BORG_REPO.

docs/usage/general/repository-urls.rst.inc

@@ -14,24 +14,7 @@ Note: you may also prepend a ``file://`` to a filesystem path to get URL style.
 
 **Remote repositories** accessed via ssh user@host:
 
-``user@host:/path/to/repo`` - remote repo, absolute path
-
-``ssh://user@host:port/path/to/repo`` - same, alternative syntax, port can be given
-
-
-**Remote repositories with relative paths** can be given using this syntax:
-
-``user@host:path/to/repo`` - path relative to current directory
-
-``user@host:~/path/to/repo`` - path relative to user's home directory
-
-``user@host:~other/path/to/repo`` - path relative to other's home directory
-
-Note: giving ``user@host:/./path/to/repo`` or ``user@host:/~/path/to/repo`` or
-``user@host:/~other/path/to/repo`` is also supported, but not required here.
-
-
-**Remote repositories with relative paths, alternative syntax with port**:
+``ssh://user@host:port/path/to/repo`` - absolute path`
 
 ``ssh://user@host:port/./path/to/repo`` - path relative to current directory
 
@@ -47,8 +30,5 @@ If you frequently need the same repo URL, it is a good idea to set the
 
     export BORG_REPO='ssh://user@host:port/path/to/repo'
 
-Then just leave away the repo URL if only a repo URL is needed and you want
+Then just leave away the ``--repo`` option if you want
 to use the default - it will be read from BORG_REPO then.
-
-Use ``::`` syntax to give the repo URL when syntax requires giving a positional
-argument for the repo (e.g. ``borg mount :: /mnt``).

docs/usage/help.rst.inc

@@ -6,42 +6,35 @@ borg help patterns
 ~~~~~~~~~~~~~~~~~~
 
 
-The path/filenames used as input for the pattern matching start from the
-currently active recursion root. You usually give the recursion root(s)
-when invoking borg and these can be either relative or absolute paths.
-
-So, when you give `relative/` as root, the paths going into the matcher
-will look like `relative/.../file.ext`. When you give `/absolute/` as
-root, they will look like `/absolute/.../file.ext`.
-
-File paths in Borg archives are always stored normalized and relative.
-This means that e.g. ``borg create /path/to/repo ../some/path`` will
-store all files as `some/path/.../file.ext` and ``borg create
-/path/to/repo /home/user`` will store all files as
-`home/user/.../file.ext`.
-
-A directory exclusion pattern can end either with or without a slash ('/').
-If it ends with a slash, such as `some/path/`, the directory will be
-included but not its content. If it does not end with a slash, such as
-`some/path`, both the directory and content will be excluded.
-
-File patterns support these styles: fnmatch, shell, regular expressions,
-path prefixes and path full-matches. By default, fnmatch is used for
-``--exclude`` patterns and shell-style is used for the ``--pattern``
-option. For commands that support patterns in their ``PATH`` argument
-like (``borg list``), the default pattern is path prefix.
-
-Starting with Borg 1.2, for all but regular expression pattern matching
-styles, all paths are treated as relative, meaning that a leading path
-separator is removed after normalizing and before matching. This allows
-you to use absolute or relative patterns arbitrarily.
-
-If followed by a colon (':') the first two characters of a pattern are
-used as a style selector. Explicit style selection is necessary when a
-non-default style is desired or when the desired pattern starts with
-two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
-
-`Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector `fm:`
+When specifying one or more file paths in a Borg command that supports
+patterns for the respective option or argument, you can apply the
+patterns described here to include only desired files and/or exclude
+unwanted ones. Patterns can be used
+
+- for ``--exclude`` option,
+- in the file given with ``--exclude-from`` option,
+- for ``--pattern`` option,
+- in the file given with ``--patterns-from`` option and
+- for ``PATH`` arguments that explicitly support them.
+
+Borg always stores all file paths normalized and relative to the
+current recursion root. The recursion root is also named ``PATH`` in
+Borg commands like `borg create` that do a file discovery, so do not
+confuse the root with the ``PATH`` argument of e.g. `borg extract`.
+
+Starting with Borg 1.2, paths that are matched against patterns always
+appear relative. If you give ``/absolute/`` as root, the paths going
+into the matcher will look relative like ``absolute/.../file.ext``.
+If you give ``../some/path`` as root, the paths will look like
+``some/path/.../file.ext``.
+
+File patterns support five different styles. If followed by a colon ':',
+the first two characters of a pattern are used as a style selector.
+Explicit style selection is necessary if a non-default style is desired
+or when the desired pattern starts with two alphanumeric characters
+followed by a colon (i.e. ``aa:something/*``).
+
+`Fnmatch <https://docs.python.org/3/library/fnmatch.html>`_, selector ``fm:``
     This is the default style for ``--exclude`` and ``--exclude-from``.
     These patterns use a variant of shell pattern syntax, with '\*' matching
     any number of characters, '?' matching any single character, '[...]'
@@ -49,7 +42,7 @@ two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
     matching any character not specified. For the purpose of these patterns,
     the path separator (backslash for Windows and '/' on other systems) is not
     treated specially. Wrap meta-characters in brackets for a literal
-    match (i.e. `[?]` to match the literal character `?`). For a path
+    match (i.e. ``[?]`` to match the literal character '?'). For a path
     to match a pattern, the full path must match, or it must match
     from the start of the full path to just before a path separator. Except
     for the root path, paths will never end in the path separator when
@@ -57,33 +50,31 @@ two alphanumeric characters followed by a colon (i.e. `aa:something/*`).
     separator, a '\*' is appended before matching is attempted. A leading
     path separator is always removed.
 
-Shell-style patterns, selector `sh:`
+Shell-style patterns, selector ``sh:``
     This is the default style for ``--pattern`` and ``--patterns-from``.
     Like fnmatch patterns these are similar to shell patterns. The difference
-    is that the pattern may include `**/` for matching zero or more directory
-    levels, `*` for matching zero or more arbitrary characters with the
+    is that the pattern may include ``**/`` for matching zero or more directory
+    levels, ``*`` for matching zero or more arbitrary characters with the
     exception of any path separator. A leading path separator is always removed.
 
-Regular expressions, selector `re:`
-    Regular expressions similar to those found in Perl are supported. Unlike
-    shell patterns regular expressions are not required to match the full
+`Regular expressions <https://docs.python.org/3/library/re.html>`_, selector ``re:``
+    Unlike shell patterns, regular expressions are not required to match the full
     path and any substring match is sufficient. It is strongly recommended to
     anchor patterns to the start ('^'), to the end ('$') or both. Path
     separators (backslash for Windows and '/' on other systems) in paths are
-    always normalized to a forward slash ('/') before applying a pattern. The
-    regular expression syntax is described in the `Python documentation for
-    the re module <https://docs.python.org/3/library/re.html>`_.
+    always normalized to a forward slash '/' before applying a pattern.
 
-Path prefix, selector `pp:`
+Path prefix, selector ``pp:``
     This pattern style is useful to match whole sub-directories. The pattern
-    `pp:root/somedir` matches `root/somedir` and everything therein. A leading
-    path separator is always removed.
+    ``pp:root/somedir`` matches ``root/somedir`` and everything therein.
+    A leading path separator is always removed.
 
-Path full-match, selector `pf:`
+Path full-match, selector ``pf:``
     This pattern style is (only) useful to match full paths.
     This is kind of a pseudo pattern as it can not have any variable or
-    unspecified parts - the full path must be given. `pf:root/file.ext` matches
-    `root/file.ext` only. A leading path separator is always removed.
+    unspecified parts - the full path must be given. ``pf:root/file.ext``
+    matches ``root/file.ext`` only. A leading path separator is always
+    removed.
 
     Implementation note: this is implemented via very time-efficient O(1)
     hashtable lookups (this means you can have huge amounts of such patterns
@@ -96,20 +87,20 @@ Path full-match, selector `pf:`
 
 .. note::
 
-    `re:`, `sh:` and `fm:` patterns are all implemented on top of the Python SRE
-    engine. It is very easy to formulate patterns for each of these types which
-    requires an inordinate amount of time to match paths. If untrusted users
-    are able to supply patterns, ensure they cannot supply `re:` patterns.
-    Further, ensure that `sh:` and `fm:` patterns only contain a handful of
-    wildcards at most.
+    ``re:``, ``sh:`` and ``fm:`` patterns are all implemented on top of
+    the Python SRE engine. It is very easy to formulate patterns for each
+    of these types which requires an inordinate amount of time to match
+    paths. If untrusted users are able to supply patterns, ensure they
+    cannot supply ``re:`` patterns. Further, ensure that ``sh:`` and
+    ``fm:`` patterns only contain a handful of wildcards at most.
 
 Exclusions can be passed via the command line option ``--exclude``. When used
 from within a shell, the patterns should be quoted to protect them from
 expansion.
 
 The ``--exclude-from`` option permits loading exclusion patterns from a text
-file with one pattern per line. Lines empty or starting with the number sign
-('#') after removing whitespace on both ends are ignored. The optional style
+file with one pattern per line. Lines empty or starting with the hash sign
+'#' after removing whitespace on both ends are ignored. The optional style
 selector prefix is also supported for patterns loaded from a file. Due to
 whitespace removal, paths with whitespace at the beginning or end can only be
 excluded using regular expressions.
@@ -120,63 +111,83 @@ run ``borg create --list --dry-run ...``.
 Examples::
 
     # Exclude '/home/user/file.o' but not '/home/user/file.odt':
-    $ borg create -e '*.o' backup /
+    $ borg create -e '*.o' archive /
 
     # Exclude '/home/user/junk' and '/home/user/subdir/junk' but
     # not '/home/user/importantjunk' or '/etc/junk':
-    $ borg create -e '/home/*/junk' backup /
+    $ borg create -e 'home/*/junk' archive /
 
     # Exclude the contents of '/home/user/cache' but not the directory itself:
-    $ borg create -e home/user/cache/ backup /
+    $ borg create -e home/user/cache/ archive /
 
     # The file '/home/user/cache/important' is *not* backed up:
-    $ borg create -e /home/user/cache/ backup / /home/user/cache/important
+    $ borg create -e home/user/cache/ archive / /home/user/cache/important
 
     # The contents of directories in '/home' are not backed up when their name
     # ends in '.tmp'
-    $ borg create --exclude 're:^/home/[^/]+\.tmp/' backup /
+    $ borg create --exclude 're:^home/[^/]+\.tmp/' archive /
 
     # Load exclusions from file
     $ cat >exclude.txt <<EOF
     # Comment line
-    /home/*/junk
+    home/*/junk
     *.tmp
     fm:aa:something/*
-    re:^/home/[^/]+\.tmp/
-    sh:/home/*/.thumbnails
+    re:^home/[^/]+\.tmp/
+    sh:home/*/.thumbnails
     # Example with spaces, no need to escape as it is processed by borg
     some file with spaces.txt
     EOF
-    $ borg create --exclude-from exclude.txt backup /
+    $ borg create --exclude-from exclude.txt archive /
 
-A more general and easier to use way to define filename matching patterns exists
-with the ``--pattern`` and ``--patterns-from`` options. Using these, you may
-specify the backup roots (starting points) and patterns for inclusion/exclusion.
-A root path starts with the prefix `R`, followed by a path (a plain path, not a
-file pattern). An include rule starts with the prefix +, an exclude rule starts
-with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern.
+A more general and easier to use way to define filename matching patterns
+exists with the ``--pattern`` and ``--patterns-from`` options. Using
+these, you may specify the backup roots, default pattern styles and
+patterns for inclusion and exclusion.
 
-.. note::
+Root path prefix ``R``
+    A recursion root path starts with the prefix ``R``, followed by a path
+    (a plain path, not a file pattern). Use this prefix to have the root
+    paths in the patterns file rather than as command line arguments.
 
-    Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion
-    of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and
-    ``--exclude-from`` ONLY excludes are defined.
+Pattern style prefix ``P``
+    To change the default pattern style, use the ``P`` prefix, followed by
+    the pattern style abbreviation (``fm``, ``pf``, ``pp``, ``re``, ``sh``).
+    All patterns following this line will use this style until another style
+    is specified.
 
-Inclusion patterns are useful to include paths that are contained in an excluded
-path. The first matching pattern is used so if an include pattern matches before
-an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches
-a directory, it won't recurse into it and won't discover any potential matches for
-include rules below that directory.
+Exclude pattern prefix ``-``
+    Use the prefix ``-``, followed by a pattern, to define an exclusion.
+    This has the same effect as the ``--exclude`` option.
 
-.. note::
+Exclude no-recurse pattern prefix ``!``
+    Use the prefix ``!``, followed by a pattern, to define an exclusion
+    that does not recurse into subdirectories. This saves time, but
+    prevents include patterns to match any files in subdirectories.
+
+Include pattern prefix ``+``
+    Use the prefix ``+``, followed by a pattern, to define inclusions.
+    This is useful to include paths that are covered in an exclude
+    pattern and would otherwise not be backed up.
+
+The first matching pattern is used, so if an include pattern matches
+before an exclude pattern, the file is backed up. Note that a no-recurse
+exclude stops examination of subdirectories so that potential includes
+will not match - use normal exludes for such use cases.
+
+**Tip: You can easily test your patterns with --dry-run and  --list**::
 
-    It's possible that a sub-directory/file is matched while parent directories are not.
-    In that case, parent directories are not backed up thus their user, group, permission,
-    etc. can not be restored.
+    $ borg create --dry-run --list --patterns-from patterns.txt archive
 
-Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is
-shell style (`sh:`), so those patterns behave similar to rsync include/exclude
-patterns. The pattern style can be set via the `P` prefix.
+This will list the considered files one per line, prefixed with a
+character that indicates the action (e.g. 'x' for excluding, see
+**Item flags** in `borg create` usage docs).
+
+.. note::
+
+    It's possible that a sub-directory/file is matched while parent
+    directories are not. In that case, parent directories are not backed
+    up and thus their user, group, permission, etc. cannot be restored.
 
 Patterns (``--pattern``) and excludes (``--exclude``) from the command line are
 considered first (in the order of appearance). Then patterns from ``--patterns-from``
@@ -186,45 +197,45 @@ Examples::
 
     # backup pics, but not the ones from 2018, except the good ones:
     # note: using = is essential to avoid cmdline argument parsing issues.
-    borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics
+    borg create --pattern=+pics/2018/good --pattern=-pics/2018 archive pics
 
-    # use a file with patterns:
-    borg create --patterns-from patterns.lst repo::arch
+    # backup only JPG/JPEG files (case insensitive) in all home directories:
+    borg create --pattern '+ re:\.jpe?g(?i)$' archive /home
+
+    # backup homes, but exclude big downloads (like .ISO files) or hidden files:
+    borg create --exclude 're:\.iso(?i)$' --exclude 'sh:home/**/.*' archive /home
+
+    # use a file with patterns (recursion root '/' via command line):
+    borg create --patterns-from patterns.lst archive /
 
 The patterns.lst file could look like that::
 
-    # "sh:" pattern style is the default, so the following line is not needed:
-    P sh
-    R /
-    # can be rebuild
-    - /home/*/.cache
-    # they're downloads for a reason
-    - /home/*/Downloads
-    # susan is a nice person
+    # "sh:" pattern style is the default
+    # exclude caches
+    - home/*/.cache
     # include susans home
-    + /home/susan
+    + home/susan
     # also back up this exact file
-    + pf:/home/bobby/specialfile.txt
+    + pf:home/bobby/specialfile.txt
     # don't backup the other home directories
-    - /home/*
-    # don't even look in /proc
-    ! /proc
+    - home/*
+    # don't even look in /dev, /proc, /run, /sys, /tmp (note: would exclude files like /device, too)
+    ! re:^(dev|proc|run|sys|tmp)
 
 You can specify recursion roots either on the command line or in a patternfile::
 
     # these two commands do the same thing
-    borg create --exclude /home/bobby/junk repo::arch /home/bobby /home/susan
-    borg create --patterns-from patternfile.lst repo::arch
+    borg create --exclude home/bobby/junk archive /home/bobby /home/susan
+    borg create --patterns-from patternfile.lst archive
 
-The patternfile::
+patternfile.lst::
 
     # note that excludes use fm: by default and patternfiles use sh: by default.
     # therefore, we need to specify fm: to have the same exact behavior.
     P fm
     R /home/bobby
     R /home/susan
-
-    - /home/bobby/junk
+    - home/bobby/junk
 
 This allows you to share the same patterns between multiple repositories
 without needing to specify them on the command line.
@@ -235,7 +246,7 @@ borg help placeholders
 ~~~~~~~~~~~~~~~~~~~~~~
 
 
-Repository (or Archive) URLs, ``--prefix``, ``--glob-archives``, ``--comment``
+Repository URLs, ``--name``, ``--prefix``, ``--glob-archives``, ``--comment``
 and ``--remote-path`` values support these placeholders:
 
 {hostname}

docs/usage/import-tar.rst.inc

@@ -6,7 +6,7 @@ borg import-tar
 ---------------
 .. code-block:: none
 
-    borg [common options] import-tar [options] ARCHIVE TARFILE
+    borg [common options] import-tar [options] NAME TARFILE
 
 .. only:: html
 
@@ -15,7 +15,7 @@ borg import-tar
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                                                          |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``ARCHIVE``                                       | name of archive to create (must be also a valid directory name)                                                                       |
+    |                                                       | ``NAME``                                          | specify the archive name                                                                                                              |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``TARFILE``                                       | input tar file. "-" to read from stdin instead.                                                                                       |
     +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -58,8 +58,8 @@ borg import-tar
 
 .. only:: latex
 
-    ARCHIVE
-        name of archive to create (must be also a valid directory name)
+    NAME
+        specify the archive name
     TARFILE
         input tar file. "-" to read from stdin instead.
 

docs/usage/info.rst

@@ -4,55 +4,17 @@ Examples
 ~~~~~~~~
 ::
 
-    $ borg info /path/to/repo::2017-06-29T11:00-srv
-    Archive name: 2017-06-29T11:00-srv
-    Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
+    $ borg info Tuesday2022-06-25T20:51:39
+    Archive name: Tuesday2022-06-25T20:51:39
+    Archive fingerprint: f7dea0788dfc026cc2be1c0f5b94beb4e4084eb3402fc40c38d8719b1bf2d943
     Comment:
-    Hostname: myhostname
-    Username: root
-    Time (start): Thu, 2017-06-29 11:03:07
-    Time (end): Thu, 2017-06-29 11:03:13
-    Duration: 5.66 seconds
-    Number of files: 17037
-    Command line: /usr/sbin/borg create /path/to/repo::2017-06-29T11:00-srv /srv
-    Utilization of max. archive size: 0%
-    ------------------------------------------------------------------------------
-                           Original size      Compressed size    Deduplicated size
-    This archive:               12.53 GB             12.49 GB              1.62 kB
-    All archives:              121.82 TB            112.41 TB            215.42 GB
-
-                           Unique chunks         Total chunks
-    Chunk index:                 1015213            626934122
-
-    $ borg info /path/to/repo --last 1
-    Archive name: 2017-06-29T11:00-srv
-    Archive fingerprint: b2f1beac2bd553b34e06358afa45a3c1689320d39163890c5bbbd49125f00fe5
-    Comment:
-    Hostname: myhostname
-    Username: root
-    Time (start): Thu, 2017-06-29 11:03:07
-    Time (end): Thu, 2017-06-29 11:03:13
-    Duration: 5.66 seconds
-    Number of files: 17037
-    Command line: /usr/sbin/borg create /path/to/repo::2017-06-29T11:00-srv /srv
-    Utilization of max. archive size: 0%
-    ------------------------------------------------------------------------------
-                           Original size      Compressed size    Deduplicated size
-    This archive:               12.53 GB             12.49 GB              1.62 kB
-    All archives:              121.82 TB            112.41 TB            215.42 GB
-
-                           Unique chunks         Total chunks
-    Chunk index:                 1015213            626934122
-
-    $ borg info /path/to/repo
-    Repository ID: d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
-    Location: /path/to/repo
-    Encrypted: Yes (repokey)
-    Cache: /root/.cache/borg/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
-    Security dir: /root/.config/borg/security/d857ce5788c51272c61535062e89eac4e8ef5a884ffbe976e0af9d8765dedfa5
-    ------------------------------------------------------------------------------
-                           Original size      Compressed size    Deduplicated size
-    All archives:              121.82 TB            112.41 TB            215.42 GB
-
-                           Unique chunks         Total chunks
-    Chunk index:                 1015213            626934122
+    Hostname: mba2020
+    Username: tw
+    Time (start): Sat, 2022-06-25 20:51:40
+    Time (end): Sat, 2022-06-25 20:51:40
+    Duration: 0.03 seconds
+    Command line: /Users/tw/w/borg-env/bin/borg -r path/to/repo create --stats 'Tuesday{now}' src --progress
+    Utilization of maximum supported archive size: 0%
+    Number of files: 244
+    Original size: 13.80 MB
+    Deduplicated size: 531 B

docs/usage/info.rst.inc

@@ -6,16 +6,12 @@ borg info
 ---------
 .. code-block:: none
 
-    borg [common options] info [options] [REPOSITORY_OR_ARCHIVE]
+    borg [common options] info [options]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to display information about                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                                                       |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -48,8 +44,6 @@ borg info
 
 .. only:: latex
 
-    REPOSITORY_OR_ARCHIVE
-        repository or archive to display information about
 
 
     optional arguments
@@ -70,7 +64,7 @@ borg info
 Description
 ~~~~~~~~~~~
 
-This command displays detailed information about the specified archive or repository.
+This command displays detailed information about the specified archive.
 
 Please note that the deduplicated sizes of the individual archives do not add
 up to the deduplicated size of the repository ("all archives"), because the two

docs/usage/init.rst

@@ -1,22 +0,0 @@
-.. include:: init.rst.inc
-
-Examples
-~~~~~~~~
-::
-
-    # Local repository, recommended repokey AEAD crypto modes
-    $ borg init --encryption=repokey-aes-ocb /path/to/repo
-    $ borg init --encryption=repokey-chacha20-poly1305 /path/to/repo
-    $ borg init --encryption=repokey-blake2-aes-ocb /path/to/repo
-    $ borg init --encryption=repokey-blake2-chacha20-poly1305 /path/to/repo
-
-    # Local repository (no encryption), not recommended
-    $ borg init --encryption=none /path/to/repo
-
-    # Remote repository (accesses a remote borg via ssh)
-    # repokey: stores the (encrypted) key into <REPO_DIR>/config
-    $ borg init --encryption=repokey-aes-ocb user@hostname:backup
-
-    # Remote repository (accesses a remote borg via ssh)
-    # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
-    $ borg init --encryption=keyfile-aes-ocb user@hostname:backup

docs/usage/key.rst

@@ -11,7 +11,7 @@ Examples
 ::
 
     # Create a key file protected repository
-    $ borg init --encryption=keyfile -v /path/to/repo
+    $ borg rcreate --encryption=keyfile -v
     Initializing repository at "/path/to/repo"
     Enter new passphrase:
     Enter same passphrase again:
@@ -23,7 +23,7 @@ Examples
     Done.
 
     # Change key file passphrase
-    $ borg key change-passphrase -v /path/to/repo
+    $ borg key change-passphrase -v
     Enter passphrase for key /root/.config/borg/keys/mnt_backup:
     Enter new passphrase:
     Enter same passphrase again:
@@ -33,15 +33,15 @@ Examples
     # Import a previously-exported key into the specified
     # key file (creating or overwriting the output key)
     # (keyfile repositories only)
-    $ BORG_KEY_FILE=/path/to/output-key borg key import /path/to/repo /path/to/exported
+    $ BORG_KEY_FILE=/path/to/output-key borg key import /path/to/exported
 
 Fully automated using environment variables:
 
 ::
 
-    $ BORG_NEW_PASSPHRASE=old borg init -e=repokey repo
+    $ BORG_NEW_PASSPHRASE=old borg rcreate -e=repokey
     # now "old" is the current passphrase.
-    $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change-passphrase repo
+    $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change-passphrase
     # now "new" is the current passphrase.
 
 

docs/usage/key_change-algorithm.rst.inc

@@ -6,23 +6,21 @@ borg key change-algorithm
 -------------------------
 .. code-block:: none
 
-    borg [common options] key change-algorithm [options] [REPOSITORY] ALGORITHM
+    borg [common options] key change-algorithm [options] ALGORITHM
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+----------------+----------------------+
-    | **positional arguments**                                                                      |
-    +-------------------------------------------------------+----------------+----------------------+
-    |                                                       | ``REPOSITORY`` |                      |
-    +-------------------------------------------------------+----------------+----------------------+
-    |                                                       | ``ALGORITHM``  | select key algorithm |
-    +-------------------------------------------------------+----------------+----------------------+
-    | .. class:: borg-common-opt-ref                                                                |
-    |                                                                                               |
-    | :ref:`common_options`                                                                         |
-    +-------------------------------------------------------+----------------+----------------------+
+    +-------------------------------------------------------+---------------+----------------------+
+    | **positional arguments**                                                                     |
+    +-------------------------------------------------------+---------------+----------------------+
+    |                                                       | ``ALGORITHM`` | select key algorithm |
+    +-------------------------------------------------------+---------------+----------------------+
+    | .. class:: borg-common-opt-ref                                                               |
+    |                                                                                              |
+    | :ref:`common_options`                                                                        |
+    +-------------------------------------------------------+---------------+----------------------+
 
     .. raw:: html
 
@@ -34,8 +32,6 @@ borg key change-algorithm
 
 .. only:: latex
 
-    REPOSITORY
-
     ALGORITHM
         select key algorithm
 

docs/usage/key_change-location.rst.inc

@@ -6,7 +6,7 @@ borg key change-location
 ------------------------
 .. code-block:: none
 
-    borg [common options] key change-location [options] [REPOSITORY] KEY_LOCATION
+    borg [common options] key change-location [options] KEY_LOCATION
 
 .. only:: html
 
@@ -15,8 +15,6 @@ borg key change-location
     +-------------------------------------------------------+------------------+----------------------------------------------------------------+
     | **positional arguments**                                                                                                                  |
     +-------------------------------------------------------+------------------+----------------------------------------------------------------+
-    |                                                       | ``REPOSITORY``   |                                                                |
-    +-------------------------------------------------------+------------------+----------------------------------------------------------------+
     |                                                       | ``KEY_LOCATION`` | select key location                                            |
     +-------------------------------------------------------+------------------+----------------------------------------------------------------+
     | **optional arguments**                                                                                                                    |
@@ -38,8 +36,6 @@ borg key change-location
 
 .. only:: latex
 
-    REPOSITORY
-
     KEY_LOCATION
         select key location
 
@@ -56,8 +52,10 @@ Description
 
 Change the location of a borg key. The key can be stored at different locations:
 
-keyfile: locally, usually in the home directory
-repokey: inside the repo (in the repo config)
+- keyfile: locally, usually in the home directory
+- repokey: inside the repo (in the repo config)
+
+Please note:
 
-Note: this command does NOT change the crypto algorithms, just the key location,
-      thus you must ONLY give the key location (keyfile or repokey).
+This command does NOT change the crypto algorithms, just the key location,
+thus you must ONLY give the key location (keyfile or repokey).

docs/usage/key_change-passphrase.rst.inc

@@ -6,21 +6,17 @@ borg key change-passphrase
 --------------------------
 .. code-block:: none
 
-    borg [common options] key change-passphrase [options] [REPOSITORY]
+    borg [common options] key change-passphrase [options]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+----------------+--+
-    | **positional arguments**                                                  |
-    +-------------------------------------------------------+----------------+--+
-    |                                                       | ``REPOSITORY`` |  |
-    +-------------------------------------------------------+----------------+--+
-    | .. class:: borg-common-opt-ref                                            |
-    |                                                                           |
-    | :ref:`common_options`                                                     |
-    +-------------------------------------------------------+----------------+--+
+    +-------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                        |
+    |                                                       |
+    | :ref:`common_options`                                 |
+    +-------------------------------------------------------+
 
     .. raw:: html
 
@@ -32,8 +28,6 @@ borg key change-passphrase
 
 .. only:: latex
 
-    REPOSITORY
-
 
 
     :ref:`common_options`

docs/usage/key_export.rst.inc

@@ -6,29 +6,27 @@ borg key export
 ---------------
 .. code-block:: none
 
-    borg [common options] key export [options] [REPOSITORY] [PATH]
+    borg [common options] key export [options] [PATH]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                        |
-    +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY`` |                                                                        |
-    +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    |                                                       | ``PATH``       | where to store the backup                                              |
-    +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                          |
-    +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    |                                                       | ``--paper``    | Create an export suitable for printing and later type-in               |
-    +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    |                                                       | ``--qr-html``  | Create an html file suitable for printing and later type-in or qr scan |
-    +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                  |
-    |                                                                                                                                                 |
-    | :ref:`common_options`                                                                                                                           |
-    +-------------------------------------------------------+----------------+------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                       |
+    +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
+    |                                                       | ``PATH``      | where to store the backup                                              |
+    +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                         |
+    +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
+    |                                                       | ``--paper``   | Create an export suitable for printing and later type-in               |
+    +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
+    |                                                       | ``--qr-html`` | Create an html file suitable for printing and later type-in or qr scan |
+    +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                 |
+    |                                                                                                                                                |
+    | :ref:`common_options`                                                                                                                          |
+    +-------------------------------------------------------+---------------+------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -40,8 +38,6 @@ borg key export
 
 .. only:: latex
 
-    REPOSITORY
-
     PATH
         where to store the backup
 

docs/usage/key_import.rst.inc

@@ -6,27 +6,25 @@ borg key import
 ---------------
 .. code-block:: none
 
-    borg [common options] key import [options] [REPOSITORY] [PATH]
+    borg [common options] key import [options] [PATH]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    | **positional arguments**                                                                                                          |
-    +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    |                                                       | ``REPOSITORY`` |                                                          |
-    +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    |                                                       | ``PATH``       | path to the backup ('-' to read from stdin)              |
-    +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    | **optional arguments**                                                                                                            |
-    +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    |                                                       | ``--paper``    | interactively import from a backup done with ``--paper`` |
-    +-------------------------------------------------------+----------------+----------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                    |
-    |                                                                                                                                   |
-    | :ref:`common_options`                                                                                                             |
-    +-------------------------------------------------------+----------------+----------------------------------------------------------+
+    +-------------------------------------------------------+-------------+----------------------------------------------------------+
+    | **positional arguments**                                                                                                       |
+    +-------------------------------------------------------+-------------+----------------------------------------------------------+
+    |                                                       | ``PATH``    | path to the backup ('-' to read from stdin)              |
+    +-------------------------------------------------------+-------------+----------------------------------------------------------+
+    | **optional arguments**                                                                                                         |
+    +-------------------------------------------------------+-------------+----------------------------------------------------------+
+    |                                                       | ``--paper`` | interactively import from a backup done with ``--paper`` |
+    +-------------------------------------------------------+-------------+----------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                 |
+    |                                                                                                                                |
+    | :ref:`common_options`                                                                                                          |
+    +-------------------------------------------------------+-------------+----------------------------------------------------------+
 
     .. raw:: html
 
@@ -38,8 +36,6 @@ borg key import
 
 .. only:: latex
 
-    REPOSITORY
-
     PATH
         path to the backup ('-' to read from stdin)
 

docs/usage/list.rst

@@ -4,14 +4,7 @@ Examples
 ~~~~~~~~
 ::
 
-    $ borg list /path/to/repo
-    Monday                               Mon, 2016-02-15 19:15:11
-    repo                                 Mon, 2016-02-15 19:26:54
-    root-2016-02-15                      Mon, 2016-02-15 19:36:29
-    newname                              Mon, 2016-02-15 19:50:19
-    ...
-
-    $ borg list /path/to/repo::root-2016-02-15
+    $ borg list root-2016-02-15
     drwxr-xr-x root   root          0 Mon, 2016-02-15 17:44:27 .
     drwxrwxr-x root   root          0 Mon, 2016-02-15 19:04:49 bin
     -rwxr-xr-x root   root    1029624 Thu, 2014-11-13 00:08:51 bin/bash
@@ -19,14 +12,14 @@ Examples
     -rwxr-xr-x root   root       2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
     ...
 
-    $ borg list /path/to/repo::root-2016-02-15 --pattern "- bin/ba*"
+    $ borg list root-2016-02-15 --pattern "- bin/ba*"
     drwxr-xr-x root   root          0 Mon, 2016-02-15 17:44:27 .
     drwxrwxr-x root   root          0 Mon, 2016-02-15 19:04:49 bin
     lrwxrwxrwx root   root          0 Fri, 2015-03-27 20:24:26 bin/bzcmp -> bzdiff
     -rwxr-xr-x root   root       2140 Fri, 2015-03-27 20:24:22 bin/bzdiff
     ...
 
-    $ borg list /path/to/repo::archiveA --format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
+    $ borg list archiveA --format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
     drwxrwxr-x user   user          0 Sun, 2015-02-01 11:00:00 .
     drwxrwxr-x user   user          0 Sun, 2015-02-01 11:00:00 code
     drwxrwxr-x user   user          0 Sun, 2015-02-01 11:00:00 code/myproject
@@ -34,11 +27,11 @@ Examples
     -rw-rw-r-- user   user    1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.text
     ...
 
-    $ borg list /path/to/repo/::archiveA --pattern 're:\.ext$'
+    $ borg list archiveA --pattern 're:\.ext$'
     -rw-rw-r-- user   user    1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
     ...
 
-    $ borg list /path/to/repo/::archiveA --pattern 're:.ext$'
+    $ borg list archiveA --pattern 're:.ext$'
     -rw-rw-r-- user   user    1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.ext
     -rw-rw-r-- user   user    1416192 Sun, 2015-02-01 11:00:00 code/myproject/file.text
     ...

docs/usage/list.rst.inc

@@ -6,57 +6,41 @@ borg list
 ---------
 .. code-block:: none
 
-    borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
+    borg [common options] list [options] NAME [PATH...]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                                                                                                                                       |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to list contents of                                                                                                                                                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``PATH``                              | paths to list; patterns are supported                                                                                                                                                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--consider-checkpoints``            | Show checkpoint archives in the repository contents list (default: hidden).                                                                                                                                                                                              |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--short``                           | only print file/directory names, nothing else                                                                                                                                                                                                                            |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--format FORMAT``                   | specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--json``                            | Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--json-lines``                      | Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                                                                                 |
-    |                                                                                                                                                                                                                                                                                                                                                                                                |
-    | :ref:`common_options`                                                                                                                                                                                                                                                                                                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                                                                                                                                    |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``    | only consider archive names starting with this prefix.                                                                                                                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB`` | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--sort-by KEYS``                    | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--first N``                         | consider first N archives after other filters were applied                                                                                                                                                                                                               |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--last N``                          | consider last N archives after other filters were applied                                                                                                                                                                                                                |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                                                                                                                                                          |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                                                                                                                                                                                           |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                                                                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                                                                                                                                                                                                                   |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                                             |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                                                                                                        |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``NAME``                              | specify the archive name                                                                                                                                                                                                        |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``PATH``                              | paths to list; patterns are supported                                                                                                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                                                                          |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--short``                           | only print file/directory names, nothing else                                                                                                                                                                                   |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--format FORMAT``                   | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}")                                                                                                                       |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--json-lines``                      | Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                  |
+    |                                                                                                                                                                                                                                                                                                                                 |
+    | :ref:`common_options`                                                                                                                                                                                                                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Exclusion options**                                                                                                                                                                                                                                                                                                           |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN                                                                                                                                                                                                  |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--exclude-from EXCLUDEFILE``        | read exclude patterns from EXCLUDEFILE, one per line                                                                                                                                                                            |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--pattern PATTERN``                 | include/exclude paths matching PATTERN                                                                                                                                                                                          |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--patterns-from PATTERNFILE``       | read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                    |
+    +-------------------------------------------------------+---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -68,31 +52,21 @@ borg list
 
 .. only:: latex
 
-    REPOSITORY_OR_ARCHIVE
-        repository or archive to list contents of
+    NAME
+        specify the archive name
     PATH
         paths to list; patterns are supported
 
 
     optional arguments
-        --consider-checkpoints    Show checkpoint archives in the repository contents list (default: hidden).
         --short     only print file/directory names, nothing else
-        --format FORMAT    specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}")
-        --json      Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
-        --json-lines    Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
+        --format FORMAT    specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}")
+        --json-lines    Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
 
 
     :ref:`common_options`
         |
 
-    Archive filters
-        -P PREFIX, --prefix PREFIX        only consider archive names starting with this prefix.
-        -a GLOB, --glob-archives GLOB     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-        --sort-by KEYS                    Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-        --first N                         consider first N archives after other filters were applied
-        --last N                          consider last N archives after other filters were applied
-
-
     Exclusion options
         -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
         --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
@@ -103,7 +77,7 @@ borg list
 Description
 ~~~~~~~~~~~
 
-This command lists the contents of a repository or an archive.
+This command lists the contents of an archive.
 
 For more help on include/exclude patterns, see the :ref:`borg_patterns` command output.
 
@@ -118,28 +92,17 @@ The ``--format`` option uses python's `format string syntax
 Examples:
 ::
 
-    $ borg list --format '{archive}{NL}' /path/to/repo
-    ArchiveFoo
-    ArchiveBar
-    ...
-
-    # {VAR:NUMBER} - pad to NUMBER columns.
-    # Strings are left-aligned, numbers are right-aligned.
-    # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded.
-    $ borg list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo
-    ArchiveFoo                           Thu, 2021-12-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274]
-    $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
+    $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' ArchiveFoo
     -rw-rw-r-- user   user       1024 Thu, 2021-12-09 10:22:17 file-foo
     ...
 
     # {VAR:<NUMBER} - pad to NUMBER columns left-aligned.
     # {VAR:>NUMBER} - pad to NUMBER columns right-aligned.
-    $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo
+    $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' ArchiveFoo
     -rw-rw-r--   user   user 1024     Thu, 2021-12-09 10:22:17 file-foo
     ...
 
 The following keys are always available:
-
 - NEWLINE: OS dependent line separator
 - NL: alias of NEWLINE
 - NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below
@@ -148,24 +111,6 @@ The following keys are always available:
 - CR
 - LF
 
-Keys available only when listing archives in a repository:
-
-- archive: archive name interpreted as text (might be missing non-text characters, see barchive)
-- name: alias of "archive"
-- barchive: verbatim archive name, can contain any character except NUL
-- comment: archive comment interpreted as text (might be missing non-text characters, see bcomment)
-- bcomment: verbatim archive comment, can contain any character except NUL
-- id: internal ID of the archive
-
-- start: time (start) of creation of the archive
-- time: alias of "start"
-- end: time (end) of creation of the archive
-- command_line: command line which was used to create the archive
-
-- hostname: hostname of host on which this archive was created
-- username: username of user who created this archive
-
-
 Keys available only when listing files in an archive:
 
 - type
@@ -176,14 +121,13 @@ Keys available only when listing files in an archive:
 - group
 - path: path interpreted as text (might be missing non-text characters, see bpath)
 - bpath: verbatim POSIX path, can contain any character except NUL
-- source: link target for links (identical to linktarget)
+- source: link target for symlinks (identical to linktarget)
 - linktarget
+- hlid: hard link identity (same if hardlinking same fs object)
 - flags
 
 - size
-- csize: compressed size
 - dsize: deduplicated size
-- dcsize: deduplicated compressed size
 - num_chunks: number of chunks in this file
 - unique_chunks: number of unique chunks in this file
 

docs/usage/mount.rst

@@ -10,21 +10,14 @@ Examples
     # Mounting the repository shows all archives.
     # Archives are loaded lazily, expect some delay when navigating to an archive
     # for the first time.
-    $ borg mount /path/to/repo /tmp/mymountpoint
+    $ borg mount /tmp/mymountpoint
     $ ls /tmp/mymountpoint
     root-2016-02-14 root-2016-02-15
     $ borg umount /tmp/mymountpoint
 
-    # Mounting a specific archive is possible as well.
-    $ borg mount /path/to/repo::root-2016-02-15 /tmp/mymountpoint
-    $ ls /tmp/mymountpoint
-    bin  boot  etc	home  lib  lib64  lost+found  media  mnt  opt
-    root  sbin  srv  tmp  usr  var
-    $ borg umount /tmp/mymountpoint
-
     # The "versions view" merges all archives in the repository
     # and provides a versioned view on files.
-    $ borg mount -o versions /path/to/repo /tmp/mymountpoint
+    $ borg mount -o versions /tmp/mymountpoint
     $ ls -l /tmp/mymountpoint/home/user/doc.txt/
     total 24
     -rw-rw-r-- 1 user group 12357 Aug 26 21:19 doc.cda00bc9.txt
@@ -34,12 +27,12 @@ Examples
     # Archive filters are supported.
     # These are especially handy for the "versions view",
     # which does not support lazy processing of archives.
-    $ borg mount -o versions --glob-archives '*-my-home' --last 10 /path/to/repo /tmp/mymountpoint
+    $ borg mount -o versions --glob-archives '*-my-home' --last 10 /tmp/mymountpoint
 
     # Exclusion options are supported.
     # These can speed up mounting and lower memory needs significantly.
     $ borg mount /path/to/repo /tmp/mymountpoint only/that/path
-    $ borg mount --exclude '...' /path/to/repo /tmp/mymountpoint
+    $ borg mount --exclude '...' /tmp/mymountpoint
 
 
 borgfs
@@ -48,13 +41,9 @@ borgfs
 ::
 
     $ echo '/mnt/backup /tmp/myrepo fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
-    $ echo '/mnt/backup::root-2016-02-15 /tmp/myarchive fuse.borgfs defaults,noauto 0 0' >> /etc/fstab
     $ mount /tmp/myrepo
-    $ mount /tmp/myarchive
     $ ls /tmp/myrepo
     root-2016-02-01 root-2016-02-2015
-    $ ls /tmp/myarchive
-    bin  boot  etc	home  lib  lib64  lost+found  media  mnt  opt  root  sbin  srv  tmp  usr  var
 
 .. Note::
 

docs/usage/mount.rst.inc

@@ -6,7 +6,7 @@ borg mount
 ----------
 .. code-block:: none
 
-    borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...]
+    borg [common options] mount [options] MOUNTPOINT [PATH...]
 
 .. only:: html
 
@@ -15,8 +15,6 @@ borg mount
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **positional arguments**                                                                                                                                                                                                                                                     |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY_OR_ARCHIVE``             | repository or archive to mount                                                                                                                         |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``MOUNTPOINT``                        | where to mount filesystem                                                                                                                              |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                                             | ``PATH``                              | paths to extract; patterns are supported                                                                                                               |
@@ -72,8 +70,6 @@ borg mount
 
 .. only:: latex
 
-    REPOSITORY_OR_ARCHIVE
-        repository or archive to mount
     MOUNTPOINT
         where to mount filesystem
     PATH

docs/usage/notes.rst

@@ -155,18 +155,18 @@ After the backup has completed, you remove the snapshots again.
 
     $ # create snapshots here
     $ lvdisplay > lvdisplay.txt
-    $ borg create --read-special /path/to/repo::arch lvdisplay.txt /dev/vg0/*-snapshot
+    $ borg create --read-special arch lvdisplay.txt /dev/vg0/*-snapshot
     $ # remove snapshots here
 
 Now, let's see how to restore some LVs from such a backup.
 
 ::
 
-    $ borg extract /path/to/repo::arch lvdisplay.txt
+    $ borg extract arch lvdisplay.txt
     $ # create empty LVs with correct sizes here (look into lvdisplay.txt).
     $ # we assume that you created an empty root and home LV and overwrite it now:
-    $ borg extract --stdout /path/to/repo::arch dev/vg0/root-snapshot > /dev/vg0/root
-    $ borg extract --stdout /path/to/repo::arch dev/vg0/home-snapshot > /dev/vg0/home
+    $ borg extract --stdout arch dev/vg0/root-snapshot > /dev/vg0/root
+    $ borg extract --stdout arch dev/vg0/home-snapshot > /dev/vg0/home
 
 
 .. _separate_compaction:
@@ -219,7 +219,7 @@ To activate append-only mode, set ``append_only`` to 1 in the repository config:
 
 ::
 
-    borg config /path/to/repo append_only 1
+    borg config append_only 1
 
 Note that you can go back-and-forth between normal and append-only operation with
 ``borg config``; it's not a "one way trip."
@@ -237,7 +237,7 @@ in ``.ssh/authorized_keys``:
     command="borg serve ..." ssh-rsa <key used for backup management>
 
 Running ``borg init`` via a ``borg serve --append-only`` server will *not* create
-an append-only repository. Running ``borg init --append-only`` creates an append-only
+an append-only repository. Running ``borg rcreate --append-only`` creates an append-only
 repository regardless of server settings.
 
 Example
@@ -282,7 +282,7 @@ than what you actually have in the repository now, after the rollback.
 
 Thus, you need to clear the cache::
 
-    borg delete --cache-only repo
+    borg rdelete --cache-only
 
 The cache will get rebuilt automatically. Depending on repo size and archive
 count, it may take a while.
@@ -307,7 +307,7 @@ mode, this is reversible, but ``borg check`` should be run before a writing/prun
 operation on an append-only repository to catch accidental or malicious corruption::
 
     # run without append-only mode
-    borg check --verify-data repo && borg compact repo
+    borg check --verify-data && borg compact
 
 Aside from checking repository & archive integrity you may want to also manually check
 backups to ensure their content seems correct.

docs/usage/prune.rst

@@ -18,21 +18,21 @@ first so you will see what it would do without it actually doing anything.
 
     # Keep 7 end of day and 4 additional end of week archives.
     # Do a dry-run without actually deleting anything.
-    $ borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4 /path/to/repo
+    $ borg prune -v --list --dry-run --keep-daily=7 --keep-weekly=4
 
     # Same as above but only apply to archive names starting with the hostname
     # of the machine followed by a "-" character:
-    $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --prefix='{hostname}-' /path/to/repo
+    $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --prefix='{hostname}-'
     # actually free disk space:
-    $ borg compact /path/to/repo
+    $ borg compact
 
     # Keep 7 end of day, 4 additional end of week archives,
     # and an end of month archive for every month:
-    $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --keep-monthly=-1 /path/to/repo
+    $ borg prune -v --list --keep-daily=7 --keep-weekly=4 --keep-monthly=-1
 
     # Keep all backups in the last 10 days, 4 additional end of week archives,
     # and an end of month archive for every month:
-    $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1 /path/to/repo
+    $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1
 
 There is also a visualized prune example in ``docs/misc/prune-example.txt``:
 

docs/usage/prune.rst.inc

@@ -6,16 +6,12 @@ borg prune
 ----------
 .. code-block:: none
 
-    borg [common options] prune [options] [REPOSITORY]
+    borg [common options] prune [options]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                     |
-    +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                                             | ``REPOSITORY``                        | repository to prune                                                                                                                                    |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                                                       |
     +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -66,8 +62,6 @@ borg prune
 
 .. only:: latex
 
-    REPOSITORY
-        repository to prune
 
 
     optional arguments

docs/usage/rcreate.rst

@@ -0,0 +1,25 @@
+.. _borg-rcreate:
+
+.. include:: rcreate.rst.inc
+
+Examples
+~~~~~~~~
+::
+
+    # Local repository
+    $ export BORG_REPO=/path/to/repo
+    # recommended repokey AEAD crypto modes
+    $ borg rcreate --encryption=repokey-aes-ocb
+    $ borg rcreate --encryption=repokey-chacha20-poly1305
+    $ borg rcreate --encryption=repokey-blake2-aes-ocb
+    $ borg rcreate --encryption=repokey-blake2-chacha20-poly1305
+    # no encryption, not recommended
+    $ borg rcreate --encryption=authenticated
+    $ borg rcreate --encryption=none
+
+    # Remote repository (accesses a remote borg via ssh)
+    $ export BORG_REPO=ssh://user@hostname/~/backup
+    # repokey: stores the (encrypted) key into <REPO_DIR>/config
+    $ borg rcreate --encryption=repokey-aes-ocb
+    # keyfile: stores the (encrypted) key into ~/.config/borg/keys/
+    $ borg rcreate --encryption=keyfile-aes-ocb

docs/usage/init.rst.inc → docs/usage/rcreate.rst.inc

@@ -1,24 +1,22 @@
 .. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
 
-.. _borg_init:
+.. _borg_rcreate:
 
-borg init
----------
+borg rcreate
+------------
 .. code-block:: none
 
-    borg [common options] init [options] [REPOSITORY]
+    borg [common options] rcreate [options]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                                                                            |
-    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY``                     | repository to create                                                                                                                                                                                                                   |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     | **optional arguments**                                                                                                                                                                                                                                                                                                              |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                       | ``--other-repo SRC_REPOSITORY``    | reuse the key material from the other repository                                                                                                                                                                                       |
+    +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``-e MODE``, ``--encryption MODE`` | select encryption key mode **(required)**                                                                                                                                                                                              |
     +-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
     |                                                       | ``--append-only``                  | create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details. |
@@ -44,11 +42,10 @@ borg init
 
 .. only:: latex
 
-    REPOSITORY
-        repository to create
 
 
     optional arguments
+        --other-repo SRC_REPOSITORY    reuse the key material from the other repository
         -e MODE, --encryption MODE     select encryption key mode **(required)**
         --append-only                  create an append-only mode repository. Note that this only affects the low level structure of the repository, and running `delete` or `prune` will still be allowed. See :ref:`append_only_mode` in Additional Notes for more details.
         --storage-quota QUOTA          Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
@@ -62,7 +59,7 @@ borg init
 Description
 ~~~~~~~~~~~
 
-This command initializes an empty repository. A repository is a filesystem
+This command creates a new, empty repository. A repository is a filesystem
 directory containing the deduplicated data from zero or more archives.
 
 Encryption mode TLDR
@@ -75,7 +72,7 @@ tips will come below):
 
 ::
 
-    borg init --encryption repokey /path/to/repo
+    borg rcreate --encryption repokey-aes-ocb
 
 Borg will:
 
@@ -137,13 +134,13 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st
 +-----------------------------------+--------------+----------------+--------------------+---------+
 | Mode (K = keyfile or repokey)     | ID-Hash      | Encryption     | Authentication     | V >=    |
 +-----------------------------------+--------------+----------------+--------------------+---------+
-| K-blake2-chacha20-poly1305        | BLAKE2b      | CHACHA20       | POLY1305           | 1.3     |
+| K-blake2-chacha20-poly1305        | BLAKE2b      | CHACHA20       | POLY1305           | 2.0     |
 +-----------------------------------+--------------+----------------+--------------------+---------+
-| K-chacha20-poly1305               | HMAC-SHA-256 | CHACHA20       | POLY1305           | 1.3     |
+| K-chacha20-poly1305               | HMAC-SHA-256 | CHACHA20       | POLY1305           | 2.0     |
 +-----------------------------------+--------------+----------------+--------------------+---------+
-| K-blake2-aes-ocb                  | BLAKE2b      | AES256-OCB     | AES256-OCB         | 1.3     |
+| K-blake2-aes-ocb                  | BLAKE2b      | AES256-OCB     | AES256-OCB         | 2.0     |
 +-----------------------------------+--------------+----------------+--------------------+---------+
-| K-aes-ocb                         | HMAC-SHA-256 | AES256-OCB     | AES256-OCB         | 1.3     |
+| K-aes-ocb                         | HMAC-SHA-256 | AES256-OCB     | AES256-OCB         | 2.0     |
 +-----------------------------------+--------------+----------------+--------------------+---------+
 | K-blake2                          | BLAKE2b      | AES256-CTR     | BLAKE2b            | 1.1     |
 +-----------------------------------+--------------+----------------+--------------------+---------+
@@ -172,8 +169,6 @@ Key derivation functions
   The key encryption key is derived from your passphrase via argon2-id.
   Argon2 is considered more modern and secure than pbkdf2.
 
-- You can use ``--key-algorithm pbkdf2`` if you want to access your repo via old versions of borg.
-
 Our implementation of argon2-based key algorithm follows the cryptographic best practices:
 
 - It derives two separate keys from your passphrase: one to encrypt your key and another one

docs/usage/rdelete.rst

@@ -0,0 +1,13 @@
+.. include:: rdelete.rst.inc
+
+Examples
+~~~~~~~~
+::
+
+    # delete the whole repository and the related local cache:
+    $ borg rdelete
+    You requested to completely DELETE the repository *including* all archives it contains:
+    repo                                 Mon, 2016-02-15 19:26:54
+    root-2016-02-15                      Mon, 2016-02-15 19:36:29
+    newname                              Mon, 2016-02-15 19:50:19
+    Type 'YES' if you understand this and want to continue: YES

docs/usage/rdelete.rst.inc

@@ -0,0 +1,66 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_rdelete:
+
+borg rdelete
+------------
+.. code-block:: none
+
+    borg [common options] rdelete [options]
+
+.. only:: html
+
+    .. class:: borg-options-table
+
+    +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                              |
+    +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                       | ``-n``, ``--dry-run``    | do not change repository                                                                         |
+    +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                       | ``--list``               | output verbose list of archives                                                                  |
+    +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                       | ``--force``              | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+    +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                       | ``--cache-only``         | delete only the local cache for the given repository                                             |
+    +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+    |                                                       | ``--keep-security-info`` | keep the local security info when deleting a repository                                          |
+    +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                      |
+    |                                                                                                                                                                                     |
+    | :ref:`common_options`                                                                                                                                                               |
+    +-------------------------------------------------------+--------------------------+--------------------------------------------------------------------------------------------------+
+
+    .. raw:: html
+
+        <script type='text/javascript'>
+        $(document).ready(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+
+
+    optional arguments
+        -n, --dry-run     do not change repository
+        --list            output verbose list of archives
+        --force           force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
+        --cache-only      delete only the local cache for the given repository
+        --keep-security-info    keep the local security info when deleting a repository
+
+
+    :ref:`common_options`
+        |
+
+Description
+~~~~~~~~~~~
+
+This command deletes the complete repository.
+
+When you delete a complete repository, the security info and local cache for it
+(if any) are also deleted. Alternatively, you can delete just the local cache
+with the ``--cache-only`` option, or keep the security info with the
+``--keep-security-info`` option.
+
+Always first use ``--dry-run --list`` to see what would be deleted.

docs/usage/recreate.rst

@@ -4,30 +4,25 @@ Examples
 ~~~~~~~~
 ::
 
-    # Make old (Attic / Borg 0.xx) archives deduplicate with Borg 1.x archives.
-    # Archives created with Borg 1.1+ and the default chunker params are skipped
-    # (archive ID stays the same).
-    $ borg recreate /mnt/backup --chunker-params default --progress
-
     # Create a backup with little but fast compression
-    $ borg create /mnt/backup::archive /some/files --compression lz4
+    $ borg create archive /some/files --compression lz4
     # Then compress it - this might take longer, but the backup has already completed,
     # so no inconsistencies from a long-running backup job.
-    $ borg recreate /mnt/backup::archive --recompress --compression zlib,9
+    $ borg recreate -a archive --recompress --compression zlib,9
 
     # Remove unwanted files from all archives in a repository.
     # Note the relative path for the --exclude option - archives only contain relative paths.
-    $ borg recreate /mnt/backup --exclude home/icke/Pictures/drunk_photos
+    $ borg recreate --exclude home/icke/Pictures/drunk_photos
 
     # Change archive comment
-    $ borg create --comment "This is a comment" /mnt/backup::archivename ~
-    $ borg info /mnt/backup::archivename
+    $ borg create --comment "This is a comment" archivename ~
+    $ borg info -a archivename
     Name: archivename
     Fingerprint: ...
     Comment: This is a comment
     ...
-    $ borg recreate --comment "This is a better comment" /mnt/backup::archivename
-    $ borg info /mnt/backup::archivename
+    $ borg recreate --comment "This is a better comment" -a archivename
+    $ borg info -a archivename
     Name: archivename
     Fingerprint: ...
     Comment: This is a better comment

docs/usage/recreate.rst.inc

@@ -6,65 +6,73 @@ borg recreate
 -------------
 .. code-block:: none
 
-    borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
+    borg [common options] recreate [options] [PATH...]
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **positional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``REPOSITORY_OR_ARCHIVE``                         | repository or archive to recreate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``PATH``                                          | paths to recreate; patterns are supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--filter STATUSCHARS``                          | only display items with the given status characters (listed in borg create --help)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-n``, ``--dry-run``                             | do not change anything                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-s``, ``--stats``                               | print statistics at end                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-    | :ref:`common_options`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Exclusion options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--pattern PATTERN``                             | include/exclude paths matching PATTERN                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--patterns-from PATTERNFILE``                   | read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    | **Archive options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--target TARGET``                               | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.                                                                                                                                                                                                                                                                                                                                                                                                                          |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--recompress MODE``                             | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered); `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level); and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-    |                                                       | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095                                                                                                                                                                                                                                                                                                                                                                              |
-    +-------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **positional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``PATH``                                          | paths to recreate; patterns are supported                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **optional arguments**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--list``                                        | output verbose list of items (files, dirs, ...)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--filter STATUSCHARS``                          | only display items with the given status characters (listed in borg create --help)                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-n``, ``--dry-run``                             | do not change anything                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-s``, ``--stats``                               | print statistics at end                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | .. class:: borg-common-opt-ref                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+    | :ref:`common_options`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Exclusion options**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-e PATTERN``, ``--exclude PATTERN``             | exclude paths matching PATTERN                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--exclude-from EXCLUDEFILE``                    | read exclude patterns from EXCLUDEFILE, one per line                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--pattern PATTERN``                             | include/exclude paths matching PATTERN                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--patterns-from PATTERNFILE``                   | read include/exclude patterns from PATTERNFILE, one per line                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--exclude-caches``                              | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html)                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--exclude-if-present NAME``                     | exclude directories that are tagged by containing a filesystem object with the given NAME                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--keep-exclude-tags``                           | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    | **Archive filters** — Archive filters can be applied to repository targets.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-P PREFIX``, ``--prefix PREFIX``                | only consider archive names starting with this prefix.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-a GLOB``, ``--glob-archives GLOB``             | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.                                                                                                                                                                                                                                                                                                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--sort-by KEYS``                                | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--first N``                                     | consider first N archives after other filters were applied                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--last N``                                      | consider last N archives after other filters were applied                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--target TARGET``                               | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--comment COMMENT``                             | add a comment text to the archive                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--timestamp TIMESTAMP``                         | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--recompress MODE``                             | recompress data chunks according to `MODE` and ``--compression``. Possible modes are `if-different`: recompress if current compression is with a different compression algorithm (the level is not considered); `always`: recompress even if current compression is with the same compression algorithm (use this to change the compression level); and `never`: do not recompress (use this option to explicitly prevent recompression). If no MODE is given, `if-different` will be used. Not passing --recompress is equivalent to "--recompress never". |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+    |                                                                             | ``--chunker-params PARAMS``                       | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: buzhash,19,23,21,4095                                                                                                                                                                                                                                                                                                                                                                              |
+    +-----------------------------------------------------------------------------+---------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
     .. raw:: html
 
@@ -76,8 +84,6 @@ borg recreate
 
 .. only:: latex
 
-    REPOSITORY_OR_ARCHIVE
-        repository or archive to recreate
     PATH
         paths to recreate; patterns are supported
 
@@ -102,7 +108,12 @@ borg recreate
         --keep-exclude-tags               if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
 
 
-    Archive options
+    Archive filters
+        -P PREFIX, --prefix PREFIX                    only consider archive names starting with this prefix.
+        -a GLOB, --glob-archives GLOB                 only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+        --sort-by KEYS                                Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+        --first N                                     consider first N archives after other filters were applied
+        --last N                                      consider last N archives after other filters were applied
         --target TARGET                               create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
         -c SECONDS, --checkpoint-interval SECONDS     write checkpoint every SECONDS seconds (Default: 1800)
         --comment COMMENT                             add a comment text to the archive

docs/usage/rename.rst

@@ -4,10 +4,10 @@ Examples
 ~~~~~~~~
 ::
 
-    $ borg create /path/to/repo::archivename ~
-    $ borg list /path/to/repo
+    $ borg create archivename ~
+    $ borg rlist
     archivename                          Mon, 2016-02-15 19:50:19
 
-    $ borg rename /path/to/repo::archivename newname
-    $ borg list /path/to/repo
+    $ borg rename archivename newname
+    $ borg rlist
     newname                              Mon, 2016-02-15 19:50:19

docs/usage/rename.rst.inc

@@ -6,23 +6,23 @@ borg rename
 -----------
 .. code-block:: none
 
-    borg [common options] rename [options] ARCHIVE NEWNAME
+    borg [common options] rename [options] OLDNAME NEWNAME
 
 .. only:: html
 
     .. class:: borg-options-table
 
-    +-------------------------------------------------------+-------------+-----------------------------+
-    | **positional arguments**                                                                          |
-    +-------------------------------------------------------+-------------+-----------------------------+
-    |                                                       | ``ARCHIVE`` | archive to rename           |
-    +-------------------------------------------------------+-------------+-----------------------------+
-    |                                                       | ``NEWNAME`` | the new archive name to use |
-    +-------------------------------------------------------+-------------+-----------------------------+
-    | .. class:: borg-common-opt-ref                                                                    |
-    |                                                                                                   |
-    | :ref:`common_options`                                                                             |
-    +-------------------------------------------------------+-------------+-----------------------------+
+    +-------------------------------------------------------+-------------+------------------------------+
+    | **positional arguments**                                                                           |
+    +-------------------------------------------------------+-------------+------------------------------+
+    |                                                       | ``OLDNAME`` | specify the archive name     |
+    +-------------------------------------------------------+-------------+------------------------------+
+    |                                                       | ``NEWNAME`` | specify the new archive name |
+    +-------------------------------------------------------+-------------+------------------------------+
+    | .. class:: borg-common-opt-ref                                                                     |
+    |                                                                                                    |
+    | :ref:`common_options`                                                                              |
+    +-------------------------------------------------------+-------------+------------------------------+
 
     .. raw:: html
 
@@ -34,10 +34,10 @@ borg rename
 
 .. only:: latex
 
-    ARCHIVE
-        archive to rename
+    OLDNAME
+        specify the archive name
     NEWNAME
-        the new archive name to use
+        specify the new archive name
 
 
     :ref:`common_options`

docs/usage/rinfo.rst

@@ -0,0 +1,16 @@
+.. include:: rinfo.rst.inc
+
+Examples
+~~~~~~~~
+::
+
+    $ borg rinfo
+    Repository ID: 0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
+    Location: /Users/tw/w/borg/path/to/repo
+    Encrypted: Yes (repokey AES-OCB)
+    Cache: /Users/tw/.cache/borg/0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
+    Security dir: /Users/tw/.config/borg/security/0e85a7811022326c067acb2a7181d5b526b7d2f61b34470fb8670c440a67f1a9
+    Original size: 152.14 MB
+    Deduplicated size: 30.38 MB
+    Unique chunks: 654
+    Total chunks: 3302

docs/usage/rinfo.rst.inc

@@ -0,0 +1,56 @@
+.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
+
+.. _borg_rinfo:
+
+borg rinfo
+----------
+.. code-block:: none
+
+    borg [common options] rinfo [options]
+
+.. only:: html
+
+    .. class:: borg-options-table
+
+    +-------------------------------------------------------+------------+-----------------------+
+    | **optional arguments**                                                                     |
+    +-------------------------------------------------------+------------+-----------------------+
+    |                                                       | ``--json`` | format output as JSON |
+    +-------------------------------------------------------+------------+-----------------------+
+    | .. class:: borg-common-opt-ref                                                             |
+    |                                                                                            |
+    | :ref:`common_options`                                                                      |
+    +-------------------------------------------------------+------------+-----------------------+
+
+    .. raw:: html
+
+        <script type='text/javascript'>
+        $(document).ready(function () {
+            $('.borg-options-table colgroup').remove();
+        })
+        </script>
+
+.. only:: latex
+
+
+
+    optional arguments
+        --json     format output as JSON
+
+
+    :ref:`common_options`
+        |
+
+Description
+~~~~~~~~~~~
+
+This command displays detailed information about the repository.
+
+Please note that the deduplicated sizes of the individual archives do not add
+up to the deduplicated size of the repository ("all archives"), because the two
+are meaning different things:
+
+This archive / deduplicated size = amount of data stored ONLY for this archive
+= unique chunks of this archive.
+All archives / deduplicated size = amount of data stored in the repo
+= all chunks in the repository.