mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

build_usage / build_man / doc updates

This commit is contained in:
Thomas Waldmann 2022-06-24 01:19:19 +02:00
parent 7f99aa155e
commit 51cf85e627
108 changed files with 2134 additions and 2083 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

247
docs/faq.rst
View File

@ -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,33 +226,9 @@ then use ``tar`` to perform the comparison:
::
borg export-tar /path/to/repo::archive-name - | tar --compare -f - -C /path/to/compare/to
borg export-tar 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.
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.

4
docs/installation.rst
View File

@ -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

7
docs/internals/data-structures.rst
View File

@ -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

4
docs/internals/frontends.rst
View File

@ -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.

117
docs/internals/security.rst
View File

@ -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

14
docs/man/borg-benchmark-cpu.1
View File

@ -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.

11
docs/man/borg-benchmark-crud.1
View File

@ -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

6
docs/man/borg-benchmark.1
View File

@ -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 ...

14
docs/man/borg-break-lock.1
View File

@ -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

27
docs/man/borg-check.1
View File

@ -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

35
docs/man/borg-common.1
View File

@ -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

21
docs/man/borg-compact.1
View File

@ -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

6
docs/man/borg-compression.1
View File

@ -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,

23
docs/man/borg-config.1
View File

@ -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

110
docs/man/borg-create.1
View File

@ -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

63
docs/man/borg-delete.1
View File

@ -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

57
docs/man/borg-diff.1
View File

@ -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

16
docs/man/borg-export-tar.1
View File

@ -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

44
docs/man/borg-extract.1
View File

@ -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

38
docs/man/borg-import-tar.1
View File

@ -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

82
docs/man/borg-info.1
View File

@ -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
$ 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 \(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

10
docs/man/borg-key-change-algorithm.1
View File

@ -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

27
docs/man/borg-key-change-location.1
View File

@ -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
keyfile: locally, usually in the home directory
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).
.IP \(bu 2
keyfile: locally, usually in the home directory
.IP \(bu 2
repokey: inside the repo (in the repo config)
.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

21
docs/man/borg-key-change-passphrase.1
View File

@ -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

14
docs/man/borg-key-export.1
View File

@ -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

12
docs/man/borg-key-import.1
View File

@ -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

6
docs/man/borg-key.1
View File

@ -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 ...

136
docs/man/borg-list.1
View File

@ -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}")
specify format for file listing (default: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{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
.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

21
docs/man/borg-mount.1
View File

@ -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

258
docs/man/borg-patterns.1
View File

@ -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.
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
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\&.
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
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\&.
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
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.
.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.
.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.
.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
\fBTip: You can easily test your patterns with \-\-dry\-run and \-\-list\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ borg create \-\-dry\-run \-\-list \-\-patterns\-from patterns.txt archive
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
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
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.
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
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.
.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.
.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

8
docs/man/borg-placeholders.1
View File

@ -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

48
docs/man/borg-prune.1
View File

@ -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

86
docs/man/borg-init.1 → docs/man/borg-rcreate.1
View File

@ -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.

90
docs/man/borg-rdelete.1 Normal file
View File

@ -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.
.

57
docs/man/borg-recreate.1
View File

@ -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

22
docs/man/borg-rename.1
View File

@ -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

83
docs/man/borg-rinfo.1 Normal file
View File

@ -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.
.

160
docs/man/borg-rlist.1 Normal file
View File

@ -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.
.

8
docs/man/borg-serve.1
View File

@ -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

100
docs/man/borg-transfer.1 Normal file
View File

@ -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.
.

25
docs/man/borg-umount.1
View File

@ -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

24
docs/man/borg-upgrade.1
View File

@ -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

11
docs/man/borg-with-lock.1
View File

@ -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

117
docs/man/borg.1
View File

@ -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

23
docs/man/borgfs.1
View File

@ -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

4
docs/man_intro.rst
View File

@ -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)`

51
docs/quickstart.rst
View File

@ -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

53
docs/quickstart_example.rst.inc
View File

@ -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).

20
docs/usage.rst
View File

@ -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

1
docs/usage/benchmark_cpu.rst.inc
View File

@ -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

24
docs/usage/benchmark_crud.rst.inc
View File

@ -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

18
docs/usage/break-lock.rst.inc
View File

@ -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`

11
docs/usage/check.rst.inc
View File

@ -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``)

35
docs/usage/common-options.rst.inc
View File

@ -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

7
docs/usage/compact.rst
View File

@ -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

8
docs/usage/compact.rst.inc
View File

@ -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

6
docs/usage/config.rst
View File

@ -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

6
docs/usage/config.rst.inc
View File

@ -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

48
docs/usage/create.rst
View File

@ -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

12
docs/usage/create.rst.inc
View File

@ -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.

18
docs/usage/delete.rst
View File

@ -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-*'

26
docs/usage/delete.rst.inc
View File

@ -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.

33
docs/usage/diff.rst
View File

@ -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}]}

12
docs/usage/diff.rst.inc
View File

@ -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

8
docs/usage/export-tar.rst.inc
View File

@ -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

12
docs/usage/extract.rst
View File

@ -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

8
docs/usage/extract.rst.inc
View File

@ -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

4
docs/usage/general.rst
View File

@ -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

7
docs/usage/general/environment.rst.inc
View File

@ -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

8
docs/usage/general/positional-arguments.rst.inc
View File

@ -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

15
docs/usage/general/repository-locations.rst.inc
View File

@ -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.

24
docs/usage/general/repository-urls.rst.inc
View File

@ -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``).

233
docs/usage/help.rst.inc
View File

@ -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.
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
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`.
- 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.
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`.
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`.
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.
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 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.
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/*``).
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:`
`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.
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.
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.
Exclude pattern prefix ``-``
Use the prefix ``-``, followed by a pattern, to define an exclusion.
This has the same effect as the ``--exclude`` option.
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**::
$ borg create --dry-run --list --patterns-from patterns.txt archive
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::
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.
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.
.. 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 thus their user, group, permission,
etc. can not be restored.
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.
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}

8
docs/usage/import-tar.rst.inc
View File

@ -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.

64
docs/usage/info.rst
View File

@ -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

10
docs/usage/info.rst.inc
View File

@ -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

22
docs/usage/init.rst
View File

@ -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

10
docs/usage/key.rst
View File

@ -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.

24
docs/usage/key_change-algorithm.rst.inc
View File

@ -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

16
docs/usage/key_change-location.rst.inc
View File

@ -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)
Note: this command does NOT change the crypto algorithms, just the key location,
thus you must ONLY give the key location (keyfile or repokey).
Please note:
This command does NOT change the crypto algorithms, just the key location,
thus you must ONLY give the key location (keyfile or repokey).

18
docs/usage/key_change-passphrase.rst.inc
View File

@ -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`

36
docs/usage/key_export.rst.inc
View File

@ -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

32
docs/usage/key_import.rst.inc
View File

@ -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)

17
docs/usage/list.rst
View File

@ -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
...

134
docs/usage/list.rst.inc
View File

@ -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

19
docs/usage/mount.rst
View File

@ -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::

6
docs/usage/mount.rst.inc
View File

@ -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

16
docs/usage/notes.rst
View File

@ -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.

10
docs/usage/prune.rst
View File

@ -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``:

8
docs/usage/prune.rst.inc
View File

@ -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

25
docs/usage/rcreate.rst Normal file
View File

@ -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

31
docs/usage/init.rst.inc → docs/usage/rcreate.rst.inc
View File

@ -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

13
docs/usage/rdelete.rst Normal file
View File

@ -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

66
docs/usage/rdelete.rst.inc Normal file
View File

@ -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.

19
docs/usage/recreate.rst
View File

@ -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

125
docs/usage/recreate.rst.inc
View File

@ -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

8
docs/usage/rename.rst
View File

@ -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

30
docs/usage/rename.rst.inc
View File

@ -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`

16
docs/usage/rinfo.rst Normal file
View File

@ -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

56
docs/usage/rinfo.rst.inc Normal file
View File

@ -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.

Some files were not shown because too many files have changed in this diff Show More