upstream/borgbackup
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2026-04-21 06:07:18 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

build_usage / build_man

Browse source
This commit is contained in:
Thomas Waldmann 2024-09-07 22:31:48 +02:00
parent 7442cbf8cf
commit b50ed04ffc
No known key found for this signature in database
GPG key ID: 243ACFA951F78E01
59 changed files with 485 additions and 465 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/man/borg-benchmark-cpu.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-BENCHMARK-CPU" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-benchmark-cpu \- Benchmark CPU bound operations.
.SH SYNOPSIS

2
docs/man/borg-benchmark-crud.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-BENCHMARK-CRUD" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.SH SYNOPSIS

2
docs/man/borg-benchmark.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-BENCHMARK" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-benchmark \- benchmark command
.SH SYNOPSIS

2
docs/man/borg-break-lock.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-BREAK-LOCK" 1 "2024-09-08" "" "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

32
docs/man/borg-check.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-CHECK" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.SH SYNOPSIS
@ -40,8 +40,8 @@ It consists of two major steps:
.INDENT 0.0
.IP 1. 3
Checking the consistency of the repository itself. This includes checking
the segment magic headers, and both the metadata and data of all objects in
the segments. The read data is checked by size and CRC. Bit rot and other
the file magic headers, and both the metadata and data of all objects in
the repository. The read data is checked by size and hash. Bit rot and other
types of accidental damage can be detected this way. Running the repository
check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
When checking a remote repository, please note that the checks run on the
@ -77,13 +77,12 @@ archive checks, nor enable repair mode. Consequently, if you want to use
.sp
\fBWarning:\fP Please note that partial repository checks (i.e. running it with
\fB\-\-max\-duration\fP) can only perform non\-cryptographic checksum checks on the
segment files. A full repository check (i.e. without \fB\-\-max\-duration\fP) can
also do a repository index check. Enabling partial repository checks excepts
archive checks for the same reason. Therefore partial checks may be useful with
very large repositories only where a full check would take too long.
repository files. Enabling partial repository checks excepts archive checks
for the same reason. Therefore partial checks may be useful with very large
repositories only where a full check would take too long.
.sp
The \fB\-\-verify\-data\fP option will perform a full integrity verification (as
opposed to checking the CRC32 of the segment) of data, which means reading the
opposed to checking just the xxh64) of data, which means reading the
data from the repository, decrypting and decompressing it. It is a complete
cryptographic verification and hence very time consuming, but will detect any
accidental and malicious corruption. Tamper\-resistance is only guaranteed for
@ -122,17 +121,15 @@ by definition, a potentially lossy task.
In practice, repair mode hooks into both the repository and archive checks:
.INDENT 0.0
.IP 1. 3
When checking the repository\(aqs consistency, repair mode will try to recover
as many objects from segments with integrity errors as possible, and ensure
that the index is consistent with the data stored in the segments.
When checking the repository\(aqs consistency, repair mode removes corrupted
objects from the repository after it did a 2nd try to read them correctly.
.IP 2. 3
When checking the consistency and correctness of archives, repair mode might
remove whole archives from the manifest if their archive metadata chunk is
corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
will replace corrupt or lost chunks with a same\-size replacement chunk of
zeroes. If a previously zeroed chunk reappears, repair mode will restore
this lost chunk using the new chunk. Lastly, repair mode will also delete
orphaned chunks (e.g. caused by read errors while creating the archive).
this lost chunk using the new chunk.
.UNINDENT
.sp
Most steps taken by repair mode have a one\-time effect on the repository, like
@ -152,6 +149,12 @@ replace the all\-zero replacement chunk by the reappeared chunk. If all lost
chunks of a \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq the file.
Consequently, if lost chunks were repaired earlier, it is advised to run
\fB\-\-repair\fP a second time after creating some new backups.
.sp
If \fB\-\-repair \-\-undelete\-archives\fP is given, Borg will scan the repository
for archive metadata and if it finds some where no corresponding archives
directory entry exists, it will create the entries. This is basically undoing
\fBborg delete archive\fP or \fBborg prune ...\fP commands and only possible before
\fBborg compact\fP would remove the archives\(aq data completely.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@ -170,6 +173,9 @@ perform cryptographic archive data integrity verification (conflicts with \fB\-\
.B \-\-repair
attempt to repair any inconsistencies found
.TP
.B \-\-undelete\-archives
attempt to undelete archives (use with \-\-repair)
.TP
.BI \-\-max\-duration \ SECONDS
do only a partial repo check for max. SECONDS seconds (Default: unlimited)
.UNINDENT

7
docs/man/borg-common.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-COMMON" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-common \- Common options of Borg commands
.SH SYNOPSIS
@ -64,10 +64,7 @@ format using IEC units (1KiB = 1024B)
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
Bypass locking mechanism
wait at most SECONDS for acquiring a repository/cache lock (default: 10).
.TP
.B \-\-show\-version
show/log the borg version

31
docs/man/borg-compact.1
View file

@ -27,40 +27,25 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-COMPACT" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-compact \- compact segment files in the repository
borg-compact \- Collect garbage in repository
.SH SYNOPSIS
.sp
borg [common options] compact [options]
.SH DESCRIPTION
.sp
This command frees repository space by compacting segments.
Free repository space by deleting unused chunks.
.sp
Use this regularly to avoid running out of space \- you do not need to use this
after each borg command though. It is especially useful after deleting archives,
because only compaction will really free repository space.
borg compact analyzes all existing archives to find out which chunks are
actually used. There might be unused chunks resulting from borg delete or prune,
which can be removed to free space in the repository.
.sp
borg compact does not need a key, so it is possible to invoke it from the
client or also from the server.
.sp
Depending on the amount of segments that need compaction, it may take a while,
so consider using the \fB\-\-progress\fP option.
.sp
A segment is compacted if the amount of saved space is above the percentage value
given by the \fB\-\-threshold\fP option. If omitted, a threshold of 10% is used.
When using \fB\-\-verbose\fP, borg will output an estimate of the freed space.
.sp
See \fIseparate_compaction\fP in Additional Notes for more details.
Differently than borg 1.x, borg2\(aqs compact needs the borg key if the repo is
encrypted.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS optional arguments
.INDENT 0.0
.TP
.BI \-\-threshold \ PERCENT
set minimum threshold for saved space in PERCENT (Default: 10)
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5

2
docs/man/borg-compression.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-COMPRESSION" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.SH DESCRIPTION

18
docs/man/borg-create.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-CREATE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.SH SYNOPSIS
@ -53,9 +53,7 @@ stdin\fP below for details.
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
.sp
The archive name needs to be unique. It must not end in \(aq.checkpoint\(aq or
\(aq.checkpoint.N\(aq (with N being a number), because these names are used for
checkpoints and treated in special ways.
The archive name needs to be unique.
.sp
In the archive name, you may use the following placeholders:
{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.
@ -155,12 +153,6 @@ only display items with the given status characters (see description)
.B \-\-json
output stats as JSON. Implies \fB\-\-stats\fP\&.
.TP
.B \-\-no\-cache\-sync
experimental: do not synchronize the chunks cache.
.TP
.B \-\-no\-cache\-sync\-forced
experimental: do not synchronize the chunks cache (forced).
.TP
.B \-\-prefer\-adhoc\-cache
experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with files cache).
.TP
@ -260,12 +252,6 @@ add a comment text to the archive
.BI \-\-timestamp \ TIMESTAMP
manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:MM] format, (+|\-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
.TP
.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.TP
.BI \-\-checkpoint\-volume \ BYTES
write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing)
.TP
.BI \-\-chunker\-params \ PARAMS
specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
.TP

21
docs/man/borg-delete.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-DELETE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-delete \- Delete archives
.SH SYNOPSIS
@ -42,16 +42,9 @@ you run \fBborg compact\fP\&.
.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
deleted \- the \(dqDeleted data\(dq deduplicated size there is most interesting as
that is how much your repository will shrink.
Please note that the \(dqAll archives\(dq stats refer to the state after deletion.
.sp
You can delete multiple archives by specifying a matching pattern,
using the \fB\-\-match\-archives PATTERN\fP option (for more info on these patterns,
see \fIborg_patterns\fP).
.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.
@ -63,18 +56,6 @@ do not change repository
.TP
.B \-\-list
output verbose list of archives
.TP
.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 \-\-force
force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work.
.TP
.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.UNINDENT
.SS Archive filters
.INDENT 0.0

2
docs/man/borg-diff.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-DIFF" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-diff \- Diff contents of two archives
.SH SYNOPSIS

2
docs/man/borg-export-tar.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-EXPORT-TAR" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-export-tar \- Export archive contents as a tarball
.SH SYNOPSIS

2
docs/man/borg-extract.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-EXTRACT" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.SH SYNOPSIS

8
docs/man/borg-import-tar.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-IMPORT-TAR" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-import-tar \- Create a backup archive from a tarball
.SH SYNOPSIS
@ -126,12 +126,6 @@ add a comment text to the archive
.BI \-\-timestamp \ TIMESTAMP
manually specify the archive creation date/time (yyyy\-mm\-ddThh:mm:ss[(+|\-)HH:MM] format, (+|\-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
.TP
.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.TP
.BI \-\-checkpoint\-volume \ BYTES
write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing)
.TP
.BI \-\-chunker\-params \ PARAMS
specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
.TP

2
docs/man/borg-info.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-INFO" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.SH SYNOPSIS

2
docs/man/borg-key-change-location.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-KEY-CHANGE-LOCATION" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-key-change-location \- Change repository key location
.SH SYNOPSIS

2
docs/man/borg-key-change-passphrase.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-key-change-passphrase \- Change repository key file passphrase
.SH SYNOPSIS

2
docs/man/borg-key-export.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-KEY-EXPORT" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-key-export \- Export the repository key for backup
.SH SYNOPSIS

2
docs/man/borg-key-import.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-KEY-IMPORT" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-key-import \- Import the repository key from backup
.SH SYNOPSIS

2
docs/man/borg-key.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-KEY" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-key \- Manage a keyfile or repokey of a repository
.SH SYNOPSIS

6
docs/man/borg-list.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-LIST" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-list \- List archive contents
.SH SYNOPSIS
@ -186,12 +186,8 @@ flags: file flags
.IP \(bu 2
size: file size
.IP \(bu 2
dsize: deduplicated size
.IP \(bu 2
num_chunks: number of chunks in this file
.IP \(bu 2
unique_chunks: number of unique chunks in this file
.IP \(bu 2
mtime: file modification time
.IP \(bu 2
ctime: file change time

2
docs/man/borg-match-archives.1
View file

@ -27,7 +27,7 @@ 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-MATCH-ARCHIVES" 1 "2024-07-19" "" "borg backup tool"
.TH "BORG-MATCH-ARCHIVES" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-match-archives \- Details regarding match-archives
.SH DESCRIPTION

5
docs/man/borg-mount.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-MOUNT" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.SH SYNOPSIS
@ -110,9 +110,6 @@ paths to extract; 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 \-f\fP,\fB \-\-foreground
stay in foreground, do not daemonize
.TP

2
docs/man/borg-patterns.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-PATTERNS" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.SH DESCRIPTION

2
docs/man/borg-placeholders.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-PLACEHOLDERS" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.SH DESCRIPTION

21
docs/man/borg-prune.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-PRUNE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-prune \- Prune repository archives according to specified rules
.SH SYNOPSIS
@ -45,11 +45,6 @@ certain number of historic backups. This retention policy is commonly referred t
\fI\%GFS\fP
(Grandfather\-father\-son) backup rotation scheme.
.sp
Also, prune automatically removes checkpoint archives (incomplete archives left
behind by interrupted backup runs) except if the checkpoint is the latest
archive (and thus still needed). Checkpoint archives are not considered when
comparing archive counts against the retention limits (\fB\-\-keep\-X\fP).
.sp
If you use \-\-match\-archives (\-a), then only archives that match the pattern are
considered for deletion and only those archives count towards the totals
specified by the rules.
@ -85,11 +80,6 @@ The \fB\-\-keep\-last N\fP option is doing the same as \fB\-\-keep\-secondly N\f
keep the last N archives under the assumption that you do not create more than one
backup archive in the same second).
.sp
When using \fB\-\-stats\fP, you will get some statistics about how much data was
deleted \- the \(dqDeleted data\(dq deduplicated size there is most interesting as
that is how much your repository will shrink.
Please note that the \(dqAll archives\(dq stats refer to the state after pruning.
.sp
You can influence how the \fB\-\-list\fP output is formatted by using the \fB\-\-short\fP
option (less wide output) or by giving a custom format using \fB\-\-format\fP (see
the \fBborg rlist\fP description for more details about the format string).
@ -102,12 +92,6 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.B \-n\fP,\fB \-\-dry\-run
do not change repository
.TP
.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
print statistics for the deleted archive
.TP
.B \-\-list
output verbose list of archives it keeps/prunes
.TP
@ -146,9 +130,6 @@ number of monthly archives to keep
.TP
.B \-y\fP,\fB \-\-keep\-yearly
number of yearly archives to keep
.TP
.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.UNINDENT
.SS Archive filters
.INDENT 0.0

15
docs/man/borg-rcompress.1
View file

@ -27,7 +27,7 @@ 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-RCOMPRESS" 1 "2024-07-19" "" "borg backup tool"
.TH "BORG-RCOMPRESS" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-rcompress \- Repository (re-)compression
.SH SYNOPSIS
@ -37,20 +37,14 @@ borg [common options] rcompress [options]
.sp
Repository (re\-)compression (and/or re\-obfuscation).
.sp
Reads all chunks in the repository (in on\-disk order, this is important for
compaction) and recompresses them if they are not already using the compression
type/level and obfuscation level given via \fB\-\-compression\fP\&.
Reads all chunks in the repository and recompresses them if they are not already
using the compression type/level and obfuscation level given via \fB\-\-compression\fP\&.
.sp
If the outcome of the chunk processing indicates a change in compression
type/level or obfuscation level, the processed chunk is written to the repository.
Please note that the outcome might not always be the desired compression
type/level \- if no compression gives a shorter output, that might be chosen.
.sp
Every \fB\-\-checkpoint\-interval\fP, progress is committed to the repository and
the repository is compacted (this is to keep temporary repo space usage in bounds).
A lower checkpoint interval means lower temporary repo space usage, but also
slower progress due to higher overhead (and vice versa).
.sp
Please note that this command can not work in low (or zero) free disk space
conditions.
.sp
@ -72,9 +66,6 @@ select compression algorithm, see the output of the \(dqborg help compression\(d
.TP
.B \-s\fP,\fB \-\-stats
print statistics
.TP
.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.UNINDENT
.SH EXAMPLES
.INDENT 0.0

15
docs/man/borg-rcreate.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-RCREATE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-rcreate \- Create a new, empty repository
.SH SYNOPSIS
@ -35,8 +35,8 @@ borg-rcreate \- Create a new, empty repository
borg [common options] rcreate [options]
.SH DESCRIPTION
.sp
This command creates a new, empty repository. A repository is a filesystem
directory containing the deduplicated data from zero or more archives.
This command creates a new, empty repository. A repository is a \fBborgstore\fP store
containing the deduplicated data from zero or more archives.
.SS Encryption mode TLDR
.sp
The encryption mode can only be configured when creating a new repository \- you can
@ -226,6 +226,12 @@ Optionally, if you use \fB\-\-copy\-crypt\-key\fP you can also keep the same cry
keys to manage.
.sp
Creating related repositories is useful e.g. if you want to use \fBborg transfer\fP later.
.SS Creating a related repository for data migration from borg 1.2 or 1.4
.sp
You can use \fBborg rcreate \-\-other\-repo ORIG_REPO \-\-from\-borg1 ...\fP to create a related
repository that uses the same secret key material as the given other/original repository.
.sp
Then use \fBborg transfer \-\-other\-repo ORIG_REPO \-\-from\-borg1 ...\fP to transfer the archives.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@ -235,6 +241,9 @@ See \fIborg\-common(1)\fP for common options of Borg commands.
.BI \-\-other\-repo \ SRC_REPOSITORY
reuse the key material from the other repository
.TP
.B \-\-from\-borg1
other repository is borg 1.x
.TP
.BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE
select encryption key mode \fB(required)\fP
.TP

2
docs/man/borg-rdelete.1
View file

@ -27,7 +27,7 @@ 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-RDELETE" 1 "2024-07-19" "" "borg backup tool"
.TH "BORG-RDELETE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-rdelete \- Delete a repository
.SH SYNOPSIS

8
docs/man/borg-recreate.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-RECREATE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-recreate \- Re-create archives
.SH SYNOPSIS
@ -157,12 +157,6 @@ consider archives newer than (now \- TIMESPAN), e.g. 7d or 12m.
.BI \-\-target \ TARGET
create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
.TP
.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
write checkpoint every SECONDS seconds (Default: 1800)
.TP
.BI \-\-checkpoint\-volume \ BYTES
write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing)
.TP
.BI \-\-comment \ COMMENT
add a comment text to the archive
.TP

2
docs/man/borg-rename.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-RENAME" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-rename \- Rename an existing archive
.SH SYNOPSIS

11
docs/man/borg-rinfo.1
View file

@ -27,7 +27,7 @@ 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-RINFO" 1 "2024-07-19" "" "borg backup tool"
.TH "BORG-RINFO" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-rinfo \- Show repository infos
.SH SYNOPSIS
@ -36,15 +36,6 @@ 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 (\(dqall archives\(dq), 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.

5
docs/man/borg-rlist.1
View file

@ -27,7 +27,7 @@ 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-RLIST" 1 "2024-07-19" "" "borg backup tool"
.TH "BORG-RLIST" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-rlist \- List the archives contained in a repository
.SH SYNOPSIS
@ -42,9 +42,6 @@ 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

94
docs/man/borg-rspace.1 Normal file
View file

@ -0,0 +1,94 @@
.\" 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-RSPACE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-rspace \- Manage reserved space in repository
.SH SYNOPSIS
.sp
borg [common options] rspace [options]
.SH DESCRIPTION
.sp
This command manages reserved space in a repository.
.sp
Borg can not work in disk\-full conditions (can not lock a repo and thus can
not run prune/delete or compact operations to free disk space).
.sp
To avoid running into dead\-end situations like that, you can put some objects
into a repository that take up some disk space. If you ever run into a
disk\-full situation, you can free that space and then borg will be able to
run normally, so you can free more disk space by using prune/delete/compact.
After that, don\(aqt forget to reserve space again, in case you run into that
situation again at a later time.
.sp
Examples:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# Create a new repository:
$ borg rcreate ...
# Reserve approx. 1GB of space for emergencies:
$ borg rspace \-\-reserve 1G
# Check amount of reserved space in the repository:
$ borg rspace
# EMERGENCY! Free all reserved space to get things back to normal:
$ borg rspace \-\-free
$ borg prune ...
$ borg delete ...
$ borg compact \-v # only this actually frees space of deleted archives
$ borg rspace \-\-reserve 1G # reserve space again for next time
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Reserved space is always rounded up to use full reservation blocks of 64MiB.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS optional arguments
.INDENT 0.0
.TP
.BI \-\-reserve \ SPACE
Amount of space to reserve (e.g. 100M, 1G). Default: 0.
.TP
.B \-\-free
Free all reserved space. Don\(aqt forget to reserve space later again.
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

2
docs/man/borg-serve.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-SERVE" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.SH SYNOPSIS

39
docs/man/borg-transfer.1
View file

@ -27,7 +27,7 @@ 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-TRANSFER" 1 "2024-07-19" "" "borg backup tool"
.TH "BORG-TRANSFER" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-transfer \- archives transfer from other repository, optionally upgrade data format
.SH SYNOPSIS
@ -46,7 +46,14 @@ any case) and keep data compressed \(dqas is\(dq (saves time as no data compress
If you want to globally change compression while transferring archives to the DST_REPO,
give \fB\-\-compress=WANTED_COMPRESSION \-\-recompress=always\fP\&.
.sp
Suggested use for general purpose archive transfer (not repo upgrades):
The default is to transfer all archives.
.sp
You could use the misc. archive filter options to limit which archives it will
transfer, e.g. using the \fB\-a\fP option. This is recommended for big
repositories with multiple data sets to keep the runtime per invocation lower.
.SS General purpose archive transfer
.sp
Transfer borg2 archives into a related other borg2 repository:
.INDENT 0.0
.INDENT 3.5
.sp
@ -54,7 +61,7 @@ Suggested use for general purpose archive transfer (not repo upgrades):
.ft C
# create a related 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 rcreate \-\-other\-repo=SRC_REPO \-\-encryption=DST_ENC
borg \-\-repo=DST_REPO rcreate \-\-encryption=DST_ENC \-\-other\-repo=SRC_REPO
# transfer archives from SRC_REPO to DST_REPO
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run # check what it would do
@ -64,26 +71,23 @@ borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-dry\-run # check!
.fi
.UNINDENT
.UNINDENT
.SS Data migration / upgrade from borg 1.x
.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 \fB\-a\fP option. This is recommended for big
repositories with multiple data sets to keep the runtime per invocation lower.
.sp
For repository upgrades (e.g. from a borg 1.2 repo to a related borg 2.0 repo), usage is
quite similar to the above:
To migrate your borg 1.x archives into a related, new borg2 repository, usage is quite similar
to the above, but you need the \fB\-\-from\-borg1\fP option:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# fast: compress metadata with zstd,3, but keep data chunks compressed as they are:
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-upgrader=From12To20 \e
\-\-compress=zstd,3 \-\-recompress=never
borg \-\-repo=DST_REPO rcreate \-\-encryption=DST_ENC \-\-other\-repo=SRC_REPO \-\-from\-borg1
# compress metadata and recompress data with zstd,3
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-upgrader=From12To20 \e
# to continue using lz4 compression as you did in SRC_REPO:
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-from\-borg1 \e
\-\-compress=lz4 \-\-recompress=never
# alternatively, to recompress everything to zstd,3:
borg \-\-repo=DST_REPO transfer \-\-other\-repo=SRC_REPO \-\-from\-borg1 \e
\-\-compress=zstd,3 \-\-recompress=always
.ft P
.fi
@ -101,6 +105,9 @@ do not change repository, just check
.BI \-\-other\-repo \ SRC_REPOSITORY
transfer archives from the other repository
.TP
.B \-\-from\-borg1
other repository is borg 1.x
.TP
.BI \-\-upgrader \ UPGRADER
use the upgrader to convert transferred data (default: no conversion)
.TP

2
docs/man/borg-umount.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-UMOUNT" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-umount \- un-mount the FUSE filesystem
.SH SYNOPSIS

2
docs/man/borg-version.1
View file

@ -27,7 +27,7 @@ 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-VERSION" 1 "2024-07-19" "" "borg backup tool"
.TH "BORG-VERSION" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-version \- Display the borg client / borg server version
.SH SYNOPSIS

2
docs/man/borg-with-lock.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG-WITH-LOCK" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.SH SYNOPSIS

70
docs/man/borg.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORG" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borg \- deduplicating and encrypting backup tool
.SH SYNOPSIS
@ -238,6 +238,10 @@ Note: you may also prepend a \fBfile://\fP to a filesystem path to get URL style
.sp
\fBssh://user@host:port/~/path/to/repo\fP \- path relative to user\(aqs home directory
.sp
\fBRemote repositories\fP accessed via sftp:
.sp
\fBsftp://user@host:port/path/to/repo\fP \- absolute path\(ga
.sp
If you frequently need the same repo URL, it is a good idea to set the
\fBBORG_REPO\fP environment variable to set a default for the repo URL:
.INDENT 0.0
@ -491,10 +495,6 @@ given order, e.g.:
Choose the implementation for the clientside cache, choose one of:
.INDENT 7.0
.IP \(bu 2
\fBlocal\fP: uses a persistent chunks cache and keeps it in a perfect state (precise refcounts and
sizes), requiring a potentially resource expensive cache sync in multi\-client scenarios.
Also has a persistent files cache.
.IP \(bu 2
\fBadhoc\fP: builds a non\-persistent chunks cache by querying the repo. Chunks cache contents
are somewhat sloppy for already existing chunks, concerning their refcount (\(dqinfinite\(dq) and
size (0). No files cache (slow, will chunk all input files). DEPRECATED.
@ -698,38 +698,48 @@ mode 600, root:root).
.UNINDENT
.SS File systems
.sp
We strongly recommend against using Borg (or any other database\-like
software) on non\-journaling file systems like FAT, since it is not
possible to assume any consistency in case of power failures (or a
sudden disconnect of an external drive or similar failures).
We recommend using a reliable, scalable journaling filesystem for the
repository, e.g. zfs, btrfs, ext4, apfs.
.sp
While Borg uses a data store that is resilient against these failures
when used on journaling file systems, it is not possible to guarantee
this with some hardware \-\- independent of the software used. We don\(aqt
know a list of affected hardware.
Borg now uses the \fBborgstore\fP package to implement the key/value store it
uses for the repository.
.sp
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
It currently uses the \fBfile:\fP Store (posixfs backend) either with a local
directory or via ssh and a remote \fBborg serve\fP agent using borgstore on the
remote side.
.sp
This means that it will store each chunk into a separate filesystem file
(for more details, see the \fBborgstore\fP project).
.sp
This has some pros and cons (compared to legacy borg 1.x\(aqs segment files):
.sp
Pros:
.INDENT 0.0
.IP \(bu 2
Long file names
Simplicity and better maintainability of the borg code.
.IP \(bu 2
At least three directory levels with short names
Sometimes faster, less I/O, better scalability: e.g. borg compact can just
remove unused chunks by deleting a single file and does not need to read
and re\-write segment files to free space.
.IP \(bu 2
Typically, file sizes up to a few hundred MB.
Large repositories may require large files (>2 GB).
In future, easier to adapt to other kinds of storage:
borgstore\(aqs backends are quite simple to implement.
A \fBsftp:\fP backend already exists, cloud storage might be easy to add.
.IP \(bu 2
Up to 1000 files per directory.
Parallel repository access with less locking is easier to implement.
.UNINDENT
.sp
Cons:
.INDENT 0.0
.IP \(bu 2
rename(2) / MoveFile(Ex) should work as specified, i.e. on the same file system
it should be a move (not a copy) operation, and in case of a directory
it should fail if the destination exists and is not an empty directory,
since this is used for locking.
The repository filesystem will have to deal with a big amount of files (there
are provisions in borgstore against having too many files in a single directory
by using a nested directory structure).
.IP \(bu 2
Also hardlinks are used for more safe and secure file updating (e.g. of the repo
config file), but the code tries to work also if hardlinks are not supported.
Bigger fs space usage overhead (will depend on allocation block size \- modern
filesystems like zfs are rather clever here using a variable block size).
.IP \(bu 2
Sometimes slower, due to less sequential / more random access operations.
.UNINDENT
.SS Units
.sp
@ -747,6 +757,10 @@ For more information about that, see: \fI\%https://xkcd.com/1179/\fP
.sp
Unless otherwise noted, we display local date and time.
Internally, we store and process date and time as UTC.
TIMESPAN
.sp
Some options accept a TIMESPAN parameter, which can be given as a
number of days (e.g. \fB7d\fP) or months (e.g. \fB12m\fP).
.SS Resource Usage
.sp
Borg might use a lot of resources depending on the size of the data set it is dealing with.

5
docs/man/borgfs.1
View file

@ -27,7 +27,7 @@ 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 "2024-07-19" "" "borg backup tool"
.TH "BORGFS" 1 "2024-09-08" "" "borg backup tool"
.SH NAME
borgfs \- Mount archive or an entire repository as a FUSE filesystem
.SH SYNOPSIS
@ -54,9 +54,6 @@ paths to extract; patterns are supported
.B \-V\fP,\fB \-\-version
show version number and exit
.TP
.B \-\-consider\-checkpoints
Show checkpoint archives in the repository contents list (default: hidden).
.TP
.B \-f\fP,\fB \-\-foreground
stay in foreground, do not daemonize
.TP

1
docs/usage.rst
View file

@ -37,6 +37,7 @@ Usage
usage/general
usage/rcreate
usage/rspace
usage/rlist
usage/rinfo
usage/rcompress

32
docs/usage/check.rst.inc
View file

@ -23,6 +23,8 @@ borg check
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--repair`` | attempt to repair any inconsistencies found |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--undelete-archives`` | attempt to undelete archives (use with --repair) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--max-duration SECONDS`` | do only a partial repo check for max. SECONDS seconds (Default: unlimited) |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
@ -65,6 +67,7 @@ borg check
--archives-only only perform archives checks
--verify-data perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
--repair attempt to repair any inconsistencies found
--undelete-archives attempt to undelete archives (use with --repair)
--max-duration SECONDS do only a partial repo check for max. SECONDS seconds (Default: unlimited)
@ -89,8 +92,8 @@ The check command verifies the consistency of a repository and its archives.
It consists of two major steps:
1. Checking the consistency of the repository itself. This includes checking
the segment magic headers, and both the metadata and data of all objects in
the segments. The read data is checked by size and CRC. Bit rot and other
the file magic headers, and both the metadata and data of all objects in
the repository. The read data is checked by size and hash. Bit rot and other
types of accidental damage can be detected this way. Running the repository
check can be split into multiple partial checks using ``--max-duration``.
When checking a remote repository, please note that the checks run on the
@ -125,13 +128,12 @@ archive checks, nor enable repair mode. Consequently, if you want to use
**Warning:** Please note that partial repository checks (i.e. running it with
``--max-duration``) can only perform non-cryptographic checksum checks on the
segment files. A full repository check (i.e. without ``--max-duration``) can
also do a repository index check. Enabling partial repository checks excepts
archive checks for the same reason. Therefore partial checks may be useful with
very large repositories only where a full check would take too long.
repository files. Enabling partial repository checks excepts archive checks
for the same reason. Therefore partial checks may be useful with very large
repositories only where a full check would take too long.
The ``--verify-data`` option will perform a full integrity verification (as
opposed to checking the CRC32 of the segment) of data, which means reading the
opposed to checking just the xxh64) of data, which means reading the
data from the repository, decrypting and decompressing it. It is a complete
cryptographic verification and hence very time consuming, but will detect any
accidental and malicious corruption. Tamper-resistance is only guaranteed for
@ -168,17 +170,15 @@ by definition, a potentially lossy task.
In practice, repair mode hooks into both the repository and archive checks:
1. When checking the repository's consistency, repair mode will try to recover
as many objects from segments with integrity errors as possible, and ensure
that the index is consistent with the data stored in the segments.
1. When checking the repository's consistency, repair mode removes corrupted
objects from the repository after it did a 2nd try to read them correctly.
2. When checking the consistency and correctness of archives, repair mode might
remove whole archives from the manifest if their archive metadata chunk is
corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
will replace corrupt or lost chunks with a same-size replacement chunk of
zeroes. If a previously zeroed chunk reappears, repair mode will restore
this lost chunk using the new chunk. Lastly, repair mode will also delete
orphaned chunks (e.g. caused by read errors while creating the archive).
this lost chunk using the new chunk.
Most steps taken by repair mode have a one-time effect on the repository, like
removing a lost archive from the repository. However, replacing a corrupt or
@ -196,4 +196,10 @@ repair mode Borg will check whether a previously lost chunk reappeared and will
replace the all-zero replacement chunk by the reappeared chunk. If all lost
chunks of a "zero-patched" file reappear, this effectively "heals" the file.
Consequently, if lost chunks were repaired earlier, it is advised to run
``--repair`` a second time after creating some new backups.
``--repair`` a second time after creating some new backups.
If ``--repair --undelete-archives`` is given, Borg will scan the repository
for archive metadata and if it finds some where no corresponding archives
directory entry exists, it will create the entries. This is basically undoing
``borg delete archive`` or ``borg prune ...`` commands and only possible before
``borg compact`` would remove the archives' data completely.

3
docs/usage/common-options.rst.inc
View file

@ -8,8 +8,7 @@
-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
--lock-wait SECONDS wait at most SECONDS for acquiring a repository/cache lock (default: 10).
--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)

39
docs/usage/compact.rst.inc
View file

@ -12,15 +12,11 @@ borg compact
.. class:: borg-options-table
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| **optional arguments** |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| | ``--threshold PERCENT`` | set minimum threshold for saved space in PERCENT (Default: 10) |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+-------------------------+----------------------------------------------------------------+
+-------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-------------------------------------------------------+
.. raw:: html
@ -34,30 +30,17 @@ borg compact
optional arguments
--threshold PERCENT set minimum threshold for saved space in PERCENT (Default: 10)
:ref:`common_options`
|
Description
~~~~~~~~~~~
This command frees repository space by compacting segments.
Free repository space by deleting unused chunks.
Use this regularly to avoid running out of space - you do not need to use this
after each borg command though. It is especially useful after deleting archives,
because only compaction will really free repository space.
borg compact analyzes all existing archives to find out which chunks are
actually used. There might be unused chunks resulting from borg delete or prune,
which can be removed to free space in the repository.
borg compact does not need a key, so it is possible to invoke it from the
client or also from the server.
Depending on the amount of segments that need compaction, it may take a while,
so consider using the ``--progress`` option.
A segment is compacted if the amount of saved space is above the percentage value
given by the ``--threshold`` option. If omitted, a threshold of 10% is used.
When using ``--verbose``, borg will output an estimate of the freed space.
See :ref:`separate_compaction` in Additional Notes for more details.
Differently than borg 1.x, borg2's compact needs the borg key if the repo is
encrypted.

16
docs/usage/create.rst.inc
View file

@ -31,10 +31,6 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | output stats as JSON. Implies ``--stats``. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--no-cache-sync`` | experimental: do not synchronize the chunks cache. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--no-cache-sync-forced`` | experimental: do not synchronize the chunks cache (forced). |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--prefer-adhoc-cache`` | experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with files cache). |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') |
@ -105,10 +101,6 @@ borg create
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--checkpoint-volume BYTES`` | write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
@ -136,8 +128,6 @@ borg create
--list output verbose list of items (files, dirs, ...)
--filter STATUSCHARS only display items with the given status characters (see description)
--json output stats as JSON. Implies ``--stats``.
--no-cache-sync experimental: do not synchronize the chunks cache.
--no-cache-sync-forced experimental: do not synchronize the chunks cache (forced).
--prefer-adhoc-cache experimental: prefer AdHocCache (w/o files cache) over AdHocWithFilesCache (with 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: do not store user/uid)
@ -180,8 +170,6 @@ borg create
Archive options
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)
--checkpoint-volume BYTES write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing)
--chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
@ -207,9 +195,7 @@ stdin* below for details.
The archive will consume almost no disk space for files or parts of files that
have already been stored in other archives.
The archive name needs to be unique. It must not end in '.checkpoint' or
'.checkpoint.N' (with N being a number), because these names are used for
checkpoints and treated in special ways.
The archive name needs to be unique.
In the archive name, you may use the following placeholders:
{now}, {utcnow}, {fqdn}, {hostname}, {user} and some others.

83
docs/usage/delete.rst.inc
View file

@ -12,43 +12,35 @@ borg delete
.. class:: borg-options-table
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **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 |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--force`` | force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, 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 |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of archives |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--sort-by KEYS`` | Comma-separated list of sorting keys; valid keys are: timestamp, archive, 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 |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
.. raw:: html
@ -63,12 +55,8 @@ borg 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
--force force deletion of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)
-n, --dry-run do not change repository
--list output verbose list of archives
:ref:`common_options`
@ -95,13 +83,6 @@ you run ``borg compact``.
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
deleted - the "Deleted data" deduplicated size there is most interesting as
that is how much your repository will shrink.
Please note that the "All archives" stats refer to the state after deletion.
You can delete multiple archives by specifying a matching pattern,
using the ``--match-archives PATTERN`` option (for more info on these patterns,
see :ref:`borg_patterns`).
Always first use ``--dry-run --list`` to see what would be deleted.
see :ref:`borg_patterns`).

6
docs/usage/import-tar.rst.inc
View file

@ -43,10 +43,6 @@ borg import-tar
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--checkpoint-volume BYTES`` | write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
@ -83,8 +79,6 @@ borg import-tar
Archive options
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)
--checkpoint-volume BYTES write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing)
--chunker-params PARAMS specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.

2
docs/usage/list.rst.inc
View file

@ -127,9 +127,7 @@ Keys available only when listing files in an archive:
- flags: file flags
- size: file size
- dsize: deduplicated size
- num_chunks: number of chunks in this file
- unique_chunks: number of unique chunks in this file
- mtime: file modification time
- ctime: file change time

3
docs/usage/mount.rst.inc
View file

@ -21,8 +21,6 @@ borg mount
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-f``, ``--foreground`` | stay in foreground, do not daemonize |
+-----------------------------------------------------------------------------+----------------------------------------------+-----------------------------------------------------------------------------------------------------------+
| | ``-o`` | Extra mount options |
@ -81,7 +79,6 @@ borg mount
optional arguments
--consider-checkpoints Show checkpoint archives in the repository contents list (default: hidden).
-f, --foreground stay in foreground, do not daemonize
-o Extra mount options
--numeric-ids use numeric user and group identifiers from archive(s)

113
docs/usage/prune.rst.inc
View file

@ -12,59 +12,53 @@ borg prune
.. class:: borg-options-table
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--force`` | force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the deleted archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of archives it keeps/prunes |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--short`` | use a less wide archive part format |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list-pruned`` | output verbose list of archives it prunes |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list-kept`` | output verbose list of archives it keeps |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--format FORMAT`` | specify format for the archive part (default: "{archive:<36} {time} [{id}]") |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--keep-within INTERVAL`` | keep all archives within this time interval |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--keep-minutely`` | number of minutely archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-H``, ``--keep-hourly`` | number of hourly archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-d``, ``--keep-daily`` | number of daily archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-w``, ``--keep-weekly`` | number of weekly archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-m``, ``--keep-monthly`` | number of monthly archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-y``, ``--keep-yearly`` | number of yearly archives to keep |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of archives it keeps/prunes |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--short`` | use a less wide archive part format |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list-pruned`` | output verbose list of archives it prunes |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--list-kept`` | output verbose list of archives it keeps |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--format FORMAT`` | specify format for the archive part (default: "{archive:<36} {time} [{id}]") |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--keep-within INTERVAL`` | keep all archives within this time interval |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--keep-last``, ``--keep-secondly`` | number of secondly archives to keep |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--keep-minutely`` | number of minutely archives to keep |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-H``, ``--keep-hourly`` | number of hourly archives to keep |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-d``, ``--keep-daily`` | number of daily archives to keep |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-w``, ``--keep-weekly`` | number of weekly archives to keep |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-m``, ``--keep-monthly`` | number of monthly archives to keep |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-y``, ``--keep-yearly`` | number of yearly archives to keep |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| **Archive filters** — Archive filters can be applied to repository targets. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``-a PATTERN``, ``--match-archives PATTERN`` | only consider archive names matching the pattern. see "borg help match-archives". |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--oldest TIMESPAN`` | consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--newest TIMESPAN`` | consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--older TIMESPAN`` | consider archives older than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
| | ``--newer TIMESPAN`` | consider archives newer than (now - TIMESPAN), e.g. 7d or 12m. |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------+
.. raw:: html
@ -80,8 +74,6 @@ borg prune
optional arguments
-n, --dry-run do not change repository
--force force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work.
-s, --stats print statistics for the deleted archive
--list output verbose list of archives it keeps/prunes
--short use a less wide archive part format
--list-pruned output verbose list of archives it prunes
@ -95,7 +87,6 @@ borg prune
-w, --keep-weekly number of weekly archives to keep
-m, --keep-monthly number of monthly archives to keep
-y, --keep-yearly number of yearly archives to keep
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)
:ref:`common_options`
@ -122,11 +113,6 @@ certain number of historic backups. This retention policy is commonly referred t
`GFS <https://en.wikipedia.org/wiki/Backup_rotation_scheme#Grandfather-father-son>`_
(Grandfather-father-son) backup rotation scheme.
Also, prune automatically removes checkpoint archives (incomplete archives left
behind by interrupted backup runs) except if the checkpoint is the latest
archive (and thus still needed). Checkpoint archives are not considered when
comparing archive counts against the retention limits (``--keep-X``).
If you use --match-archives (-a), then only archives that match the pattern are
considered for deletion and only those archives count towards the totals
specified by the rules.
@ -162,11 +148,6 @@ The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it
keep the last N archives under the assumption that you do not create more than one
backup archive in the same second).
When using ``--stats``, you will get some statistics about how much data was
deleted - the "Deleted data" deduplicated size there is most interesting as
that is how much your repository will shrink.
Please note that the "All archives" stats refer to the state after pruning.
You can influence how the ``--list`` output is formatted by using the ``--short``
option (less wide output) or by giving a custom format using ``--format`` (see
the ``borg rlist`` description for more details about the format string).

13
docs/usage/rcompress.rst.inc
View file

@ -19,8 +19,6 @@ borg rcompress
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
+-------------------------------------------------------+---------------------------------------------------+--------------------------------------------------------------------------------------------------+
| .. class:: borg-common-opt-ref |
| |
| :ref:`common_options` |
@ -41,7 +39,6 @@ borg rcompress
optional arguments
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
-s, --stats print statistics
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)
:ref:`common_options`
@ -52,20 +49,14 @@ Description
Repository (re-)compression (and/or re-obfuscation).
Reads all chunks in the repository (in on-disk order, this is important for
compaction) and recompresses them if they are not already using the compression
type/level and obfuscation level given via ``--compression``.
Reads all chunks in the repository and recompresses them if they are not already
using the compression type/level and obfuscation level given via ``--compression``.
If the outcome of the chunk processing indicates a change in compression
type/level or obfuscation level, the processed chunk is written to the repository.
Please note that the outcome might not always be the desired compression
type/level - if no compression gives a shorter output, that might be chosen.
Every ``--checkpoint-interval``, progress is committed to the repository and
the repository is compacted (this is to keep temporary repo space usage in bounds).
A lower checkpoint interval means lower temporary repo space usage, but also
slower progress due to higher overhead (and vice versa).
Please note that this command can not work in low (or zero) free disk space
conditions.

17
docs/usage/rcreate.rst.inc
View file

@ -17,6 +17,8 @@ borg rcreate
+-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--other-repo SRC_REPOSITORY`` | reuse the key material from the other repository |
+-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--from-borg1`` | other repository is borg 1.x |
+-------------------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-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. |
@ -46,6 +48,7 @@ borg rcreate
optional arguments
--other-repo SRC_REPOSITORY reuse the key material from the other repository
--from-borg1 other repository is borg 1.x
-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.
@ -59,8 +62,8 @@ borg rcreate
Description
~~~~~~~~~~~
This command creates a new, empty repository. A repository is a filesystem
directory containing the deduplicated data from zero or more archives.
This command creates a new, empty repository. A repository is a ``borgstore`` store
containing the deduplicated data from zero or more archives.
Encryption mode TLDR
++++++++++++++++++++
@ -173,4 +176,12 @@ Optionally, if you use ``--copy-crypt-key`` you can also keep the same crypt_key
(used for authenticated encryption). Might be desired e.g. if you want to have less
keys to manage.
Creating related repositories is useful e.g. if you want to use ``borg transfer`` later.
Creating related repositories is useful e.g. if you want to use ``borg transfer`` later.
Creating a related repository for data migration from borg 1.2 or 1.4
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
You can use ``borg rcreate --other-repo ORIG_REPO --from-borg1 ...`` to create a related
repository that uses the same secret key material as the given other/original repository.
Then use ``borg transfer --other-repo ORIG_REPO --from-borg1 ...`` to transfer the archives.

32
docs/usage/recreate.rst.inc
View file

@ -67,10 +67,6 @@ borg recreate
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--checkpoint-volume BYTES`` | write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory. |
@ -115,21 +111,19 @@ borg recreate
Archive filters
-a PATTERN, --match-archives PATTERN only consider archive names matching the pattern. see "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, 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
--oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
--newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m.
--older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d or 12m.
--newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.
--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)
--checkpoint-volume BYTES write checkpoint every BYTES bytes (Default: 0, meaning no volume based checkpointing)
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--chunker-params PARAMS rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the chunker defaults. default: do not rechunk
-a PATTERN, --match-archives PATTERN only consider archive names matching the pattern. see "borg help match-archives".
--sort-by KEYS Comma-separated list of sorting keys; valid keys are: timestamp, archive, 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
--oldest TIMESPAN consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g. 7d or 12m.
--newest TIMESPAN consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g. 7d or 12m.
--older TIMESPAN consider archives older than (now - TIMESPAN), e.g. 7d or 12m.
--newer TIMESPAN consider archives newer than (now - TIMESPAN), e.g. 7d or 12m.
--target TARGET create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
--comment COMMENT add a comment text to the archive
--timestamp TIMESTAMP manually specify the archive creation date/time (yyyy-mm-ddThh:mm:ss[(+|-)HH:MM] format, (+|-)HH:MM is the UTC offset, default: local time zone). Alternatively, give a reference file/directory.
-C COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--chunker-params PARAMS rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the chunker defaults. default: do not rechunk
Description

11
docs/usage/rinfo.rst.inc
View file

@ -44,13 +44,4 @@ borg rinfo
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.
This command displays detailed information about the repository.

3
docs/usage/rlist.rst.inc
View file

@ -15,8 +15,6 @@ borg rlist
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--consider-checkpoints`` | Show checkpoint archives in the repository contents list (default: hidden). |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--short`` | only print the archive names, nothing else |
+-----------------------------------------------------------------------------+----------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--format FORMAT`` | specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}") |
@ -59,7 +57,6 @@ borg rlist
optional arguments
--consider-checkpoints Show checkpoint archives in the repository contents list (default: hidden).
--short only print the archive names, nothing else
--format FORMAT specify format for archive listing (default: "{archive:<36} {time} [{id}]{NL}")
--json 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.

1
docs/usage/rspace.rst Normal file
View file

@ -0,0 +1 @@
.. include:: rspace.rst.inc

80
docs/usage/rspace.rst.inc Normal file
View file

@ -0,0 +1,80 @@
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
.. _borg_rspace:
borg rspace
-----------
.. code-block:: none
borg [common options] rspace [options]
.. only:: html
.. class:: borg-options-table
+-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
| **optional arguments** |
+-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
| | ``--reserve SPACE`` | Amount of space to reserve (e.g. 100M, 1G). Default: 0. |
+-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
| | ``--free`` | Free all reserved space. Don't forget to reserve space later again. |
+-------------------------------------------------------+---------------------+---------------------------------------------------------------------+
| .. 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
--reserve SPACE Amount of space to reserve (e.g. 100M, 1G). Default: 0.
--free Free all reserved space. Don't forget to reserve space later again.
:ref:`common_options`
|
Description
~~~~~~~~~~~
This command manages reserved space in a repository.
Borg can not work in disk-full conditions (can not lock a repo and thus can
not run prune/delete or compact operations to free disk space).
To avoid running into dead-end situations like that, you can put some objects
into a repository that take up some disk space. If you ever run into a
disk-full situation, you can free that space and then borg will be able to
run normally, so you can free more disk space by using prune/delete/compact.
After that, don't forget to reserve space again, in case you run into that
situation again at a later time.
Examples::
# Create a new repository:
$ borg rcreate ...
# Reserve approx. 1GB of space for emergencies:
$ borg rspace --reserve 1G
# Check amount of reserved space in the repository:
$ borg rspace
# EMERGENCY! Free all reserved space to get things back to normal:
$ borg rspace --free
$ borg prune ...
$ borg delete ...
$ borg compact -v # only this actually frees space of deleted archives
$ borg rspace --reserve 1G # reserve space again for next time
Reserved space is always rounded up to use full reservation blocks of 64MiB.

38
docs/usage/transfer.rst.inc
View file

@ -19,6 +19,8 @@ borg transfer
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--other-repo SRC_REPOSITORY`` | transfer archives from the other repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--from-borg1`` | other repository is borg 1.x |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--upgrader UPGRADER`` | use the upgrader to convert transferred data (default: no conversion) |
+-----------------------------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
@ -63,6 +65,7 @@ borg transfer
optional arguments
-n, --dry-run do not change repository, just check
--other-repo SRC_REPOSITORY transfer archives from the other repository
--from-borg1 other repository is borg 1.x
--upgrader UPGRADER use the upgrader to convert transferred data (default: no conversion)
-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 `always`: recompress unconditionally; and `never`: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, `always` will be used. Not passing --recompress is equivalent to "--recompress never".
@ -96,31 +99,40 @@ any case) and keep data compressed "as is" (saves time as no data compression is
If you want to globally change compression while transferring archives to the DST_REPO,
give ``--compress=WANTED_COMPRESSION --recompress=always``.
Suggested use for general purpose archive transfer (not repo upgrades)::
The default is to transfer all archives.
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.
General purpose archive transfer
++++++++++++++++++++++++++++++++
Transfer borg2 archives into a related other borg2 repository::
# create a related 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 rcreate --other-repo=SRC_REPO --encryption=DST_ENC
borg --repo=DST_REPO rcreate --encryption=DST_ENC --other-repo=SRC_REPO
# 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?
The default is to transfer all archives, including checkpoint archives.
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.
Data migration / upgrade from borg 1.x
++++++++++++++++++++++++++++++++++++++
For repository upgrades (e.g. from a borg 1.2 repo to a related borg 2.0 repo), usage is
quite similar to the above::
To migrate your borg 1.x archives into a related, new borg2 repository, usage is quite similar
to the above, but you need the ``--from-borg1`` option::
# fast: compress metadata with zstd,3, but keep data chunks compressed as they are:
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --upgrader=From12To20 \
--compress=zstd,3 --recompress=never
borg --repo=DST_REPO rcreate --encryption=DST_ENC --other-repo=SRC_REPO --from-borg1
# compress metadata and recompress data with zstd,3
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --upgrader=From12To20 \
# to continue using lz4 compression as you did in SRC_REPO:
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --from-borg1 \
--compress=lz4 --recompress=never
# alternatively, to recompress everything to zstd,3:
borg --repo=DST_REPO transfer --other-repo=SRC_REPO --from-borg1 \
--compress=zstd,3 --recompress=always