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

docs: ran build_man, build_usage

Browse source
This commit is contained in:
Marian Beermann 2017-05-17 11:52:48 +02:00
parent 3db27f950e
commit b7a6ac94c3
56 changed files with 327 additions and 126 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

101
docs/man/borg-benchmark-crud.1 Normal file
View file

@ -0,0 +1,101 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BENCHMARK-CRUD 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.
.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
..
.SH SYNOPSIS
.sp
borg [common options] benchmark crud <options> REPO PATH
.SH DESCRIPTION
.sp
This command benchmarks borg CRUD (create, read, update, delete) operations.
.sp
It creates input data below the given PATH and backups this data into the given REPO.
The REPO must already exist (it could be a fresh empty repo or an existing repo, the
command will create / read / update / delete some archives named borg\-test\-data* there.
.sp
Make sure you have free space there, you\(aqll need about 1GB each (+ overhead).
.sp
If your repository is encrypted and borg needs a passphrase to unlock the key, use:
.sp
BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
.sp
Measurements are done with different input file sizes and counts.
The file contents are very artificial (either all zero or all random),
thus the measurement results do not necessarily reflect performance with real data.
Also, due to the kind of content used, no compression is used in these benchmarks.
.INDENT 0.0
.TP
.B C\- == borg create (1st archive creation, no compression, do not use files cache)
C\-Z\- == all\-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
C\-R\- == random files. no dedup, measuring throughput through all processing stages.
.TP
.B R\- == borg extract (extract archive, dry\-run, do everything, but do not write files to disk)
R\-Z\- == all zero files. Measuring heavily duplicated files.
R\-R\- == random files. No duplication here, measuring throughput through all processing
.IP "System Message: ERROR/3 (docs/virtmanpage.rst:, line 56)"
Unexpected indentation.
.INDENT 7.0
.INDENT 3.5
stages, except writing to disk.
.UNINDENT
.UNINDENT
.TP
.B U\- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
The throughput value is kind of virtual here, it does not actually read the file.
U\-Z\- == needs to check the 2 all\-zero chunks\(aq existence in the repo.
U\-R\- == needs to check existence of a lot of different chunks in the repo.
.TP
.B D\- == borg delete archive (delete last remaining archive, measure deletion + compaction)
D\-Z\- == few chunks to delete / few segments to compact/remove.
D\-R\- == many chunks to delete / many segments to compact/remove.
.UNINDENT
.sp
Please note that there might be quite some variance in these measurements.
Try multiple measurements and having a otherwise idle machine (and network, if you use it).
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
.SS arguments
.INDENT 0.0
.TP
.B REPO
repo to use for benchmark (must exist)
.TP
.B PATH
path were to create benchmark input data
.UNINDENT
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

47
docs/man/borg-benchmark.1 Normal file
View file

@ -0,0 +1,47 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BENCHMARK 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-benchmark \- benchmark command
.
.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
..
.SH SYNOPSIS
.nf
borg [common options] benchmark crud ...
.fi
.sp
.SH DESCRIPTION
.sp
These commands do various benchmarks.
.SH SEE ALSO
.sp
\fIborg\-common(1)\fP, \fIborg\-benchmark\-crud(1)\fP
.SH AUTHOR
The Borg Collective
.\" Generated by docutils manpage writer.
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BREAK-LOCK 1 "2017-04-29" "" "borg backup tool"
.TH BORG-BREAK-LOCK 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg break\-lock <options> REPOSITORY
borg [common options] break\-lock <options> REPOSITORY
.SH DESCRIPTION
.sp
This command breaks the repository and cache locks.

4
docs/man/borg-change-passphrase.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHANGE-PASSPHRASE 1 "2017-04-29" "" "borg backup tool"
.TH BORG-CHANGE-PASSPHRASE 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-change-passphrase \- Change repository key file passphrase
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg change\-passphrase <options> REPOSITORY
borg [common options] change\-passphrase <options> REPOSITORY
.SH DESCRIPTION
.sp
The key files used for repository encryption are optionally passphrase

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHECK 1 "2017-04-29" "" "borg backup tool"
.TH BORG-CHECK 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg check <options> REPOSITORY_OR_ARCHIVE
borg [common options] check <options> REPOSITORY_OR_ARCHIVE
.SH DESCRIPTION
.sp
The check command verifies the consistency of a repository and the corresponding archives.
@ -120,9 +120,6 @@ attempt to repair any inconsistencies found
.TP
.B \-\-save\-space
work slower, but using less space
.TP
.B \-p\fP,\fB \-\-progress
show progress display while checking
.UNINDENT
.SS filters
.INDENT 0.0

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMMON 1 "2017-04-29" "" "borg backup tool"
.TH BORG-COMMON 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-common \- Common options of Borg commands
.
@ -54,6 +54,9 @@ enable debug output, work on log level DEBUG
.BI \-\-debug\-topic \ TOPIC
enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
.TP
.B \-p\fP,\fB \-\-progress
show progress information
.TP
.B \-\-log\-json
Output one JSON object per log line instead of formatted text.
.TP
@ -80,6 +83,9 @@ set remote network upload rate limit in kiByte/s (default: 0=unlimited)
.TP
.B \-\-consider\-part\-files
treat part files like normal files (e.g. to list/extract them)
.TP
.BI \-\-debug\-profile \ FILE
Write execution profile in Borg format into FILE. For local use a Python\-compatible file can be generated by suffixing FILE with ".pyprof".
.UNINDENT
.SH SEE ALSO
.sp

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMPRESSION 1 "2017-04-29" "" "borg backup tool"
.TH BORG-COMPRESSION 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CREATE 1 "2017-04-29" "" "borg backup tool"
.TH BORG-CREATE 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg create <options> ARCHIVE PATH
borg [common options] create <options> ARCHIVE PATH
.SH DESCRIPTION
.sp
This command creates a backup archive containing all files found while recursively
@ -63,6 +63,10 @@ creation of a new archive to ensure fast operation. This is because the file cac
is used to determine changed files quickly uses absolute filenames.
If this is not possible, consider creating a bind mount to a stable location.
.sp
The \-\-progress option shows (from left to right) Original, Compressed and Deduplicated
(O, C and D, respectively), then the Number of files (N) processed so far, followed by
the currently processed path.
.sp
See the output of the "borg help patterns" command for more help on exclude patterns.
See the output of the "borg help placeholders" command for more help on placeholders.
.SH OPTIONS
@ -86,9 +90,6 @@ do not create a backup archive
.B \-s\fP,\fB \-\-stats
print statistics for the created archive
.TP
.B \-p\fP,\fB \-\-progress
show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False
.TP
.B \-\-list
output verbose list of items (files, dirs, ...)
.TP

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DELETE 1 "2017-04-29" "" "borg backup tool"
.TH BORG-DELETE 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-delete \- Delete an existing repository or archives
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg delete <options> TARGET
borg [common options] delete <options> TARGET
.SH DESCRIPTION
.sp
This command deletes an archive from the repository or the complete repository.
@ -50,9 +50,6 @@ archive or repository to delete
.SS optional arguments
.INDENT 0.0
.TP
.B \-p\fP,\fB \-\-progress
show progress display while deleting a single archive
.TP
.B \-s\fP,\fB \-\-stats
print statistics for the deleted archive
.TP

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DIFF 1 "2017-04-29" "" "borg backup tool"
.TH BORG-DIFF 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-diff \- Diff contents of two archives
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg diff <options> REPO_ARCHIVE1 ARCHIVE2 PATH
borg [common options] diff <options> REPO_ARCHIVE1 ARCHIVE2 PATH
.SH DESCRIPTION
.sp
This command finds differences (file contents, user/group/mode) between archives.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXPORT-TAR 1 "2017-05-16" "" "borg backup tool"
.TH BORG-EXPORT-TAR 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-export-tar \- Export archive contents as a tarball
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg export\-tar <options> ARCHIVE FILE PATH
borg [common options] export\-tar <options> ARCHIVE FILE PATH
.SH DESCRIPTION
.sp
This command creates a tarball from an archive.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXTRACT 1 "2017-04-29" "" "borg backup tool"
.TH BORG-EXTRACT 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg extract <options> ARCHIVE PATH
borg [common options] extract <options> ARCHIVE PATH
.SH DESCRIPTION
.sp
This command extracts the contents of an archive. By default the entire
@ -45,6 +45,9 @@ See the output of the "borg help patterns" command for more help on exclude patt
By using \fB\-\-dry\-run\fP, you can do all extraction steps except actually writing the
output data: reading metadata and data chunks from the repo, checking the hash/hmac,
decrypting, decompressing.
.sp
\fB\-\-progress\fP can be slower than no progress display, since it makes one additional
pass over the archive metadata.
.SH OPTIONS
.sp
See \fIborg\-common(1)\fP for common options of Borg commands.
@ -60,9 +63,6 @@ paths to extract; patterns are supported
.SS optional arguments
.INDENT 0.0
.TP
.B \-p\fP,\fB \-\-progress
show progress while extracting (may be slower)
.TP
.B \-\-list
output verbose list of items (files, dirs, ...)
.TP

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INFO 1 "2017-04-29" "" "borg backup tool"
.TH BORG-INFO 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg info <options> REPOSITORY_OR_ARCHIVE
borg [common options] info <options> REPOSITORY_OR_ARCHIVE
.SH DESCRIPTION
.sp
This command displays detailed information about the specified archive or repository.

12
docs/man/borg-init.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INIT 1 "2017-04-29" "" "borg backup tool"
.TH BORG-INIT 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-init \- Initialize an empty repository
.
@ -32,13 +32,13 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg init <options> REPOSITORY
borg [common options] init <options> REPOSITORY
.SH DESCRIPTION
.sp
This command initializes an empty repository. A repository is a filesystem
directory containing the deduplicated data from zero or more archives.
.sp
Encryption can be enabled at repository init time.
Encryption can be enabled at repository init time. It cannot be changed later.
.sp
It is not recommended to work without encryption. Repository encryption protects
you e.g. against the case that an attacker has access to your backup repository.
@ -94,8 +94,8 @@ These modes are new and \fInot\fP compatible with borg 1.0.x.
.sp
\fIauthenticated\fP mode uses no encryption, but authenticates repository contents
through the same keyed BLAKE2b\-256 hash as the other blake2 modes (it uses it
as chunk ID hash). The key is stored like repokey.
This mode is new and not compatible with borg 1.0.x.
as the chunk ID hash). The key is stored like repokey.
This mode is new and \fInot\fP compatible with borg 1.0.x.
.sp
\fInone\fP mode uses no encryption and no authentication. It uses sha256 as chunk
ID hash. Not recommended, rather consider using an authenticated or
@ -123,7 +123,7 @@ repository to create
.INDENT 0.0
.TP
.B \-e\fP,\fB \-\-encryption
select encryption key mode
select encryption key mode \fB(required)\fP
.TP
.B \-a\fP,\fB \-\-append\-only
create an append\-only mode repository

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-04-29" "" "borg backup tool"
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-key-change-passphrase \- Change repository key file passphrase
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg key change\-passphrase <options> REPOSITORY
borg [common options] key change\-passphrase <options> REPOSITORY
.SH DESCRIPTION
.sp
The key files used for repository encryption are optionally passphrase

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-EXPORT 1 "2017-04-29" "" "borg backup tool"
.TH BORG-KEY-EXPORT 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-key-export \- Export the repository key for backup
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg key export <options> REPOSITORY PATH
borg [common options] key export <options> REPOSITORY PATH
.SH DESCRIPTION
.sp
If repository encryption is used, the repository is inaccessible

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-IMPORT 1 "2017-04-29" "" "borg backup tool"
.TH BORG-KEY-IMPORT 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-key-import \- Import the repository key from backup
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg key import <options> REPOSITORY PATH
borg [common options] key import <options> REPOSITORY PATH
.SH DESCRIPTION
.sp
This command allows to restore a key previously backed up with the

4
docs/man/borg-key-migrate-to-repokey.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-04-29" "" "borg backup tool"
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg key migrate\-to\-repokey <options> REPOSITORY
borg [common options] key migrate\-to\-repokey <options> REPOSITORY
.SH DESCRIPTION
.sp
This command migrates a repository from passphrase mode (removed in Borg 1.0)

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY 1 "2017-04-29" "" "borg backup tool"
.TH BORG-KEY 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-key \- Manage a keyfile or repokey of a repository
.
@ -32,10 +32,10 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.nf
borg key export ...
borg key import ...
borg key change\-passphrase ...
borg key migrate\-to\-repokey ...
borg [common options] key export ...
borg [common options] key import ...
borg [common options] key change\-passphrase ...
borg [common options] key migrate\-to\-repokey ...
.fi
.sp
.SH SEE ALSO

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-LIST 1 "2017-04-29" "" "borg backup tool"
.TH BORG-LIST 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-list \- List archive or repository contents
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg list <options> REPOSITORY_OR_ARCHIVE PATH
borg [common options] list <options> REPOSITORY_OR_ARCHIVE PATH
.SH DESCRIPTION
.sp
This command lists the contents of a repository or an archive.
@ -61,7 +61,10 @@ specify format for file listing
(default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
.TP
.B \-\-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. A "bpath" key is therefore not available.
Only valid for listing repository contents. Format output as JSON. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
.TP
.B \-\-json\-lines
Only valid for listing archive contents. Format output as JSON Lines. The form of \-\-format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
.UNINDENT
.SS filters
.INDENT 0.0

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-MOUNT 1 "2017-04-29" "" "borg backup tool"
.TH BORG-MOUNT 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
borg [common options] mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
.SH DESCRIPTION
.sp
This command mounts an archive as a FUSE filesystem. This can be useful for

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PATTERNS 1 "2017-04-29" "" "borg backup tool"
.TH BORG-PATTERNS 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PLACEHOLDERS 1 "2017-04-29" "" "borg backup tool"
.TH BORG-PLACEHOLDERS 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PRUNE 1 "2017-04-29" "" "borg backup tool"
.TH BORG-PRUNE 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-prune \- Prune repository archives according to specified rules
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg prune <options> REPOSITORY
borg [common options] prune <options> REPOSITORY
.SH DESCRIPTION
.sp
The prune command prunes a repository by deleting all archives not matching
@ -91,9 +91,6 @@ do not change repository
.B \-\-force
force pruning of corrupted archives
.TP
.B \-p\fP,\fB \-\-progress
show progress display while deleting archives
.TP
.B \-s\fP,\fB \-\-stats
print statistics for the deleted archive
.TP

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RECREATE 1 "2017-04-29" "" "borg backup tool"
.TH BORG-RECREATE 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-recreate \- Re-create archives
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg recreate <options> REPOSITORY_OR_ARCHIVE PATH
borg [common options] recreate <options> REPOSITORY_OR_ARCHIVE PATH
.SH DESCRIPTION
.sp
Recreate the contents of existing archives.
@ -92,9 +92,6 @@ output verbose list of items (files, dirs, ...)
.BI \-\-filter \ STATUSCHARS
only display items with the given status characters
.TP
.B \-p\fP,\fB \-\-progress
show progress display while recreating archives
.TP
.B \-n\fP,\fB \-\-dry\-run
do not change anything
.TP

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RENAME 1 "2017-04-29" "" "borg backup tool"
.TH BORG-RENAME 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-rename \- Rename an existing archive
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg rename <options> ARCHIVE NEWNAME
borg [common options] rename <options> ARCHIVE NEWNAME
.SH DESCRIPTION
.sp
This command renames an archive in the repository.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-SERVE 1 "2017-04-29" "" "borg backup tool"
.TH BORG-SERVE 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg serve <options>
borg [common options] serve <options>
.SH DESCRIPTION
.sp
This command starts a repository server process. This command is usually not used manually.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UMOUNT 1 "2017-04-29" "" "borg backup tool"
.TH BORG-UMOUNT 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-umount \- un-mount the FUSE filesystem
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg umount <options> MOUNTPOINT
borg [common options] umount <options> MOUNTPOINT
.SH DESCRIPTION
.sp
This command un\-mounts a FUSE filesystem that was mounted with \fBborg mount\fP\&.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UPGRADE 1 "2017-04-29" "" "borg backup tool"
.TH BORG-UPGRADE 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-upgrade \- upgrade a repository from a previous version
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg upgrade <options> REPOSITORY
borg [common options] upgrade <options> REPOSITORY
.SH DESCRIPTION
.sp
Upgrade an existing, local Borg repository.
@ -129,9 +129,6 @@ path to the repository to be upgraded
.SS optional arguments
.INDENT 0.0
.TP
.B \-p\fP,\fB \-\-progress
show progress display while upgrading the repository
.TP
.B \-n\fP,\fB \-\-dry\-run
do not change repository
.TP

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-WITH-LOCK 1 "2017-04-29" "" "borg backup tool"
.TH BORG-WITH-LOCK 1 "2017-05-17" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.
@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg with\-lock <options> REPOSITORY COMMAND ARGS
borg [common options] with\-lock <options> REPOSITORY COMMAND ARGS
.SH DESCRIPTION
.sp
This command runs a user\-specified command while the repository lock is held.

2
docs/man/borg.1
View file

@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
borg <command> [options] [arguments]
borg [common options] <command> [options] [arguments]
.SH DESCRIPTION
.\" we don't include the README.rst here since we want to keep this terse.
.

59
docs/usage/benchmark_crud.rst.inc Normal file
View file

@ -0,0 +1,59 @@
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
.. _borg_benchmark_crud:
borg benchmark crud
-------------------
::
borg [common options] benchmark crud <options> REPO PATH
positional arguments
REPO
repo to use for benchmark (must exist)
PATH
path were to create benchmark input data
`Common options`_
|
Description
~~~~~~~~~~~
This command benchmarks borg CRUD (create, read, update, delete) operations.
It creates input data below the given PATH and backups this data into the given REPO.
The REPO must already exist (it could be a fresh empty repo or an existing repo, the
command will create / read / update / delete some archives named borg-test-data* there.
Make sure you have free space there, you'll need about 1GB each (+ overhead).
If your repository is encrypted and borg needs a passphrase to unlock the key, use:
BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
Measurements are done with different input file sizes and counts.
The file contents are very artificial (either all zero or all random),
thus the measurement results do not necessarily reflect performance with real data.
Also, due to the kind of content used, no compression is used in these benchmarks.
C- == borg create (1st archive creation, no compression, do not use files cache)
C-Z- == all-zero files. full dedup, this is primarily measuring reader/chunker/hasher.
C-R- == random files. no dedup, measuring throughput through all processing stages.
R- == borg extract (extract archive, dry-run, do everything, but do not write files to disk)
R-Z- == all zero files. Measuring heavily duplicated files.
R-R- == random files. No duplication here, measuring throughput through all processing
stages, except writing to disk.
U- == borg create (2nd archive creation of unchanged input files, measure files cache speed)
The throughput value is kind of virtual here, it does not actually read the file.
U-Z- == needs to check the 2 all-zero chunks' existence in the repo.
U-R- == needs to check existence of a lot of different chunks in the repo.
D- == borg delete archive (delete last remaining archive, measure deletion + compaction)
D-Z- == few chunks to delete / few segments to compact/remove.
D-R- == many chunks to delete / many segments to compact/remove.
Please note that there might be quite some variance in these measurements.
Try multiple measurements and having a otherwise idle machine (and network, if you use it).

2
docs/usage/break-lock.rst.inc
View file

@ -6,7 +6,7 @@ borg break-lock
---------------
::
borg break-lock <options> REPOSITORY
borg [common options] break-lock <options> REPOSITORY
positional arguments
REPOSITORY

2
docs/usage/change-passphrase.rst.inc
View file

@ -6,7 +6,7 @@ borg change-passphrase
----------------------
::
borg change-passphrase <options> REPOSITORY
borg [common options] change-passphrase <options> REPOSITORY
positional arguments
REPOSITORY

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

@ -6,7 +6,7 @@ borg check
----------
::
borg check <options> REPOSITORY_OR_ARCHIVE
borg [common options] check <options> REPOSITORY_OR_ARCHIVE
positional arguments
REPOSITORY_OR_ARCHIVE
@ -23,8 +23,6 @@ optional arguments
| attempt to repair any inconsistencies found
``--save-space``
| work slower, but using less space
``-p``, ``--progress``
| show progress display while checking
`Common options`_
|

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

@ -12,6 +12,8 @@
| enable debug output, work on log level DEBUG
``--debug-topic TOPIC``
| enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
``-p``, ``--progress``
| show progress information
``--log-json``
| Output one JSON object per log line instead of formatted text.
``--lock-wait N``
@ -29,4 +31,6 @@
``--remote-ratelimit rate``
| set remote network upload rate limit in kiByte/s (default: 0=unlimited)
``--consider-part-files``
| treat part files like normal files (e.g. to list/extract them)
| treat part files like normal files (e.g. to list/extract them)
``--debug-profile FILE``
| Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".

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

@ -6,7 +6,7 @@ borg create
-----------
::
borg create <options> ARCHIVE PATH
borg [common options] create <options> ARCHIVE PATH
positional arguments
ARCHIVE
@ -19,8 +19,6 @@ optional arguments
| do not create a backup archive
``-s``, ``--stats``
| print statistics for the created archive
``-p``, ``--progress``
| show progress display while creating the archive, showing Original, Compressed and Deduplicated sizes, followed by the Number of files seen and the path being processed, default: False
``--list``
| output verbose list of items (files, dirs, ...)
``--filter STATUSCHARS``
@ -104,6 +102,10 @@ creation of a new archive to ensure fast operation. This is because the file cac
is used to determine changed files quickly uses absolute filenames.
If this is not possible, consider creating a bind mount to a stable location.
The --progress option shows (from left to right) Original, Compressed and Deduplicated
(O, C and D, respectively), then the Number of files (N) processed so far, followed by
the currently processed path.
See the output of the "borg help patterns" command for more help on exclude patterns.
See the output of the "borg help placeholders" command for more help on placeholders.

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

@ -6,15 +6,13 @@ borg delete
-----------
::
borg delete <options> TARGET
borg [common options] delete <options> TARGET
positional arguments
TARGET
archive or repository to delete
optional arguments
``-p``, ``--progress``
| show progress display while deleting a single archive
``-s``, ``--stats``
| print statistics for the deleted archive
``-c``, ``--cache-only``

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

@ -6,7 +6,7 @@ borg diff
---------
::
borg diff <options> REPO_ARCHIVE1 ARCHIVE2 PATH
borg [common options] diff <options> REPO_ARCHIVE1 ARCHIVE2 PATH
positional arguments
REPO_ARCHIVE1

2
docs/usage/export-tar.rst.inc
View file

@ -6,7 +6,7 @@ borg export-tar
---------------
::
borg export-tar <options> ARCHIVE FILE PATH
borg [common options] export-tar <options> ARCHIVE FILE PATH
positional arguments
ARCHIVE

9
docs/usage/extract.rst.inc
View file

@ -6,7 +6,7 @@ borg extract
------------
::
borg extract <options> ARCHIVE PATH
borg [common options] extract <options> ARCHIVE PATH
positional arguments
ARCHIVE
@ -15,8 +15,6 @@ positional arguments
paths to extract; patterns are supported
optional arguments
``-p``, ``--progress``
| show progress while extracting (may be slower)
``--list``
| output verbose list of items (files, dirs, ...)
``-n``, ``--dry-run``
@ -53,4 +51,7 @@ See the output of the "borg help patterns" command for more help on exclude patt
By using ``--dry-run``, you can do all extraction steps except actually writing the
output data: reading metadata and data chunks from the repo, checking the hash/hmac,
decrypting, decompressing.
decrypting, decompressing.
``--progress`` can be slower than no progress display, since it makes one additional
pass over the archive metadata.

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

@ -6,7 +6,7 @@ borg info
---------
::
borg info <options> REPOSITORY_OR_ARCHIVE
borg [common options] info <options> REPOSITORY_OR_ARCHIVE
positional arguments
REPOSITORY_OR_ARCHIVE

10
docs/usage/init.rst.inc
View file

@ -6,7 +6,7 @@ borg init
---------
::
borg init <options> REPOSITORY
borg [common options] init <options> REPOSITORY
positional arguments
REPOSITORY
@ -14,7 +14,7 @@ positional arguments
optional arguments
``-e``, ``--encryption``
| select encryption key mode
| select encryption key mode **(required)**
``-a``, ``--append-only``
| create an append-only mode repository
@ -27,7 +27,7 @@ Description
This command initializes an empty repository. A repository is a filesystem
directory containing the deduplicated data from zero or more archives.
Encryption can be enabled at repository init time.
Encryption can be enabled at repository init time. It cannot be changed later.
It is not recommended to work without encryption. Repository encryption protects
you e.g. against the case that an attacker has access to your backup repository.
@ -82,8 +82,8 @@ These modes are new and *not* compatible with borg 1.0.x.
`authenticated` mode uses no encryption, but authenticates repository contents
through the same keyed BLAKE2b-256 hash as the other blake2 modes (it uses it
as chunk ID hash). The key is stored like repokey.
This mode is new and not compatible with borg 1.0.x.
as the chunk ID hash). The key is stored like repokey.
This mode is new and *not* compatible with borg 1.0.x.
`none` mode uses no encryption and no authentication. It uses sha256 as chunk
ID hash. Not recommended, rather consider using an authenticated or

2
docs/usage/key_change-passphrase.rst.inc
View file

@ -6,7 +6,7 @@ borg key change-passphrase
--------------------------
::
borg key change-passphrase <options> REPOSITORY
borg [common options] key change-passphrase <options> REPOSITORY
positional arguments
REPOSITORY

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

@ -6,7 +6,7 @@ borg key export
---------------
::
borg key export <options> REPOSITORY PATH
borg [common options] key export <options> REPOSITORY PATH
positional arguments
REPOSITORY

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

@ -6,7 +6,7 @@ borg key import
---------------
::
borg key import <options> REPOSITORY PATH
borg [common options] key import <options> REPOSITORY PATH
positional arguments
REPOSITORY

2
docs/usage/key_migrate-to-repokey.rst.inc
View file

@ -6,7 +6,7 @@ borg key migrate-to-repokey
---------------------------
::
borg key migrate-to-repokey <options> REPOSITORY
borg [common options] key migrate-to-repokey <options> REPOSITORY
positional arguments
REPOSITORY

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

@ -6,7 +6,7 @@ borg list
---------
::
borg list <options> REPOSITORY_OR_ARCHIVE PATH
borg [common options] list <options> REPOSITORY_OR_ARCHIVE PATH
positional arguments
REPOSITORY_OR_ARCHIVE
@ -21,7 +21,9 @@ optional arguments
| specify format for file listing
| (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{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. A "bpath" key is therefore not available.
| Only valid for listing repository contents. Format output as JSON. The form of --format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
``--json-lines``
| Only valid for listing archive contents. Format output as JSON Lines. The form of --format is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
`Common options`_
|

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

@ -6,7 +6,7 @@ borg mount
----------
::
borg mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
borg [common options] mount <options> REPOSITORY_OR_ARCHIVE MOUNTPOINT
positional arguments
REPOSITORY_OR_ARCHIVE

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

@ -6,7 +6,7 @@ borg prune
----------
::
borg prune <options> REPOSITORY
borg [common options] prune <options> REPOSITORY
positional arguments
REPOSITORY
@ -17,8 +17,6 @@ optional arguments
| do not change repository
``--force``
| force pruning of corrupted archives
``-p``, ``--progress``
| show progress display while deleting archives
``-s``, ``--stats``
| print statistics for the deleted archive
``--list``

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

@ -6,7 +6,7 @@ borg recreate
-------------
::
borg recreate <options> REPOSITORY_OR_ARCHIVE PATH
borg [common options] recreate <options> REPOSITORY_OR_ARCHIVE PATH
positional arguments
REPOSITORY_OR_ARCHIVE
@ -19,8 +19,6 @@ optional arguments
| output verbose list of items (files, dirs, ...)
``--filter STATUSCHARS``
| only display items with the given status characters
``-p``, ``--progress``
| show progress display while recreating archives
``-n``, ``--dry-run``
| do not change anything
``-s``, ``--stats``

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

@ -6,7 +6,7 @@ borg rename
-----------
::
borg rename <options> ARCHIVE NEWNAME
borg [common options] rename <options> ARCHIVE NEWNAME
positional arguments
ARCHIVE

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

@ -6,7 +6,7 @@ borg serve
----------
::
borg serve <options>
borg [common options] serve <options>
optional arguments
``--restrict-to-path PATH``

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

@ -6,7 +6,7 @@ borg umount
-----------
::
borg umount <options> MOUNTPOINT
borg [common options] umount <options> MOUNTPOINT
positional arguments
MOUNTPOINT

4
docs/usage/upgrade.rst.inc
View file

@ -6,15 +6,13 @@ borg upgrade
------------
::
borg upgrade <options> REPOSITORY
borg [common options] upgrade <options> REPOSITORY
positional arguments
REPOSITORY
path to the repository to be upgraded
optional arguments
``-p``, ``--progress``
| show progress display while upgrading the repository
``-n``, ``--dry-run``
| do not change repository
``-i``, ``--inplace``

2
docs/usage/with-lock.rst.inc
View file

@ -6,7 +6,7 @@ borg with-lock
--------------
::
borg with-lock <options> REPOSITORY COMMAND ARGS
borg [common options] with-lock <options> REPOSITORY COMMAND ARGS
positional arguments
REPOSITORY