build_man

2026-04-09 10:56:23 -04:00 · 2020-12-24 22:35:58 +01:00 · 2020-12-24 22:35:58 +01:00 · d53ecb3ded
commit d53ecb3ded
parent 4e0a56d59a
33 changed files with 74 additions and 37 deletions
--- a/docs/man/borg-benchmark-crud.1
+++ b/docs/man/borg-benchmark-crud.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK-CRUD 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-BENCHMARK-CRUD 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .
--- a/docs/man/borg-benchmark.1
+++ b/docs/man/borg-benchmark.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BENCHMARK 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-BENCHMARK 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .
--- a/docs/man/borg-break-lock.1
+++ b/docs/man/borg-break-lock.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-BREAK-LOCK 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-BREAK-LOCK 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .
--- a/docs/man/borg-change-passphrase.1
+++ b/docs/man/borg-change-passphrase.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHANGE-PASSPHRASE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-CHANGE-PASSPHRASE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-change-passphrase \- Change repository key file passphrase
 .
--- a/docs/man/borg-check.1
+++ b/docs/man/borg-check.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CHECK 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-CHECK 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .
--- a/docs/man/borg-common.1
+++ b/docs/man/borg-common.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMMON 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-COMMON 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .
--- a/docs/man/borg-compression.1
+++ b/docs/man/borg-compression.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-COMPRESSION 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-COMPRESSION 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .
--- a/docs/man/borg-config.1
+++ b/docs/man/borg-config.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CONFIG 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-CONFIG 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-config \- get, set, and delete values in a repository or cache config file
 .
--- a/docs/man/borg-create.1
+++ b/docs/man/borg-create.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-CREATE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-CREATE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .
@ -117,6 +117,7 @@ the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP optio
 exclusive because the data is not actually compressed and deduplicated during a dry run.
 .sp
 See the output of the "borg help patterns" command for more help on exclude patterns.
+.sp
 See the output of the "borg help placeholders" command for more help on placeholders.
 .SH OPTIONS
 .sp
@ -156,6 +157,15 @@ do not load/update the file metadata cache used to detect unchanged files
 .TP
 .BI \-\-stdin\-name \ NAME
 use NAME in archive for stdin data (default: "stdin")
+.TP
+.BI \-\-stdin\-user \ USER
+set user USER in archive for stdin data (default: \(aqroot\(aq)
+.TP
+.BI \-\-stdin\-group \ GROUP
+set group GROUP in archive for stdin data (default: \(aqroot\(aq)
+.TP
+.BI \-\-stdin\-mode \ M
+set mode to M in archive for stdin data (default: 0660)
 .UNINDENT
 .SS Exclusion options
 .INDENT 0.0
@ -188,7 +198,7 @@ exclude files flagged NODUMP
 .INDENT 0.0
 .TP
 .B \-x\fP,\fB  \-\-one\-file\-system
-stay in the same file system and do not store mount points of other file systems
+stay in the same file system and do not store mount points of other file systems.  This might behave different from your expectations, see the docs.
 .TP
 .B \-\-numeric\-owner
 only store numeric user and group identifiers
@ -320,6 +330,17 @@ all of its contents will be omitted from the backup.  If, however, you wish to
 only include the objects specified by \fB\-\-exclude\-if\-present\fP in your backup,
 and not include any other contents of the containing folder, this can be enabled
 through using the \fB\-\-keep\-exclude\-tags\fP option.
+.sp
+The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
+It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its
+parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different
+from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
+with device number different from their parent, which the kernel does not consider a mountpoint and also the
+other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
+subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
+using \fB\-\-one\-file\-system\fP, one should make doubly sure that the backup works as intended especially when using
+btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
+installer.
 .SS Item flags
 .sp
 \fB\-\-list\fP outputs a list of all files, directories and other
--- a/docs/man/borg-delete.1
+++ b/docs/man/borg-delete.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DELETE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-DELETE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-delete \- Delete an existing repository or archives
 .
--- a/docs/man/borg-diff.1
+++ b/docs/man/borg-diff.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-DIFF 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-DIFF 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-diff \- Diff contents of two archives
 .
--- a/docs/man/borg-export-tar.1
+++ b/docs/man/borg-export-tar.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXPORT-TAR 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-EXPORT-TAR 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-export-tar \- Export archive contents as a tarball
 .
--- a/docs/man/borg-extract.1
+++ b/docs/man/borg-extract.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-EXTRACT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-EXTRACT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-extract \- Extract archive contents
 .
--- a/docs/man/borg-info.1
+++ b/docs/man/borg-info.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INFO 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-INFO 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-info \- Show archive details such as disk space used
 .
--- a/docs/man/borg-init.1
+++ b/docs/man/borg-init.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-INIT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-INIT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-init \- Initialize an empty repository
 .
--- a/docs/man/borg-key-change-passphrase.1
+++ b/docs/man/borg-key-change-passphrase.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key-change-passphrase \- Change repository key file passphrase
 .
--- a/docs/man/borg-key-export.1
+++ b/docs/man/borg-key-export.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-EXPORT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY-EXPORT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key-export \- Export the repository key for backup
 .
--- a/docs/man/borg-key-import.1
+++ b/docs/man/borg-key-import.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-IMPORT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY-IMPORT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key-import \- Import the repository key from backup
 .
--- a/docs/man/borg-key-migrate-to-repokey.1
+++ b/docs/man/borg-key-migrate-to-repokey.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
 .
--- a/docs/man/borg-key.1
+++ b/docs/man/borg-key.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-KEY 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-KEY 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-key \- Manage a keyfile or repokey of a repository
 .
--- a/docs/man/borg-list.1
+++ b/docs/man/borg-list.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-LIST 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-LIST 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-list \- List archive or repository contents
 .
@ -119,6 +119,13 @@ lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdif
 \-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
 \&...

+$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern "\- bin/ba*"
+drwxr\-xr\-x root   root          0 Mon, 2016\-02\-15 17:44:27 .
+drwxrwxr\-x root   root          0 Mon, 2016\-02\-15 19:04:49 bin
+lrwxrwxrwx root   root          0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
+\-rwxr\-xr\-x root   root       2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
+\&...
+
 $ borg list /path/to/repo::archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 .
 drwxrwxr\-x user   user          0 Sun, 2015\-02\-01 11:00:00 code
--- a/docs/man/borg-mount.1
+++ b/docs/man/borg-mount.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-MOUNT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-MOUNT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-mount \- Mount archive or an entire repository as a FUSE filesystem
 .
--- a/docs/man/borg-patterns.1
+++ b/docs/man/borg-patterns.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PATTERNS 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-PATTERNS 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .
@ -168,8 +168,10 @@ $ cat >exclude.txt <<EOF
 /home/*/junk
 *.tmp
 fm:aa:something/*
-re:^/home/[^/]\e.tmp/
-sh:/home/*/.thumbnails
+re:^home/[^/]\e.tmp/
+sh:home/*/.thumbnails
+ # Example with spaces, no need to escape as it is processed by borg
+some file with spaces.txt
 EOF
 $ borg create \-\-exclude\-from exclude.txt backup /
 .ft P
--- a/docs/man/borg-placeholders.1
+++ b/docs/man/borg-placeholders.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PLACEHOLDERS 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-PLACEHOLDERS 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-placeholders \- Details regarding placeholders
 .
--- a/docs/man/borg-prune.1
+++ b/docs/man/borg-prune.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-PRUNE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-PRUNE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-prune \- Prune repository archives according to specified rules
 .
--- a/docs/man/borg-recreate.1
+++ b/docs/man/borg-recreate.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RECREATE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-RECREATE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-recreate \- Re-create archives
 .
--- a/docs/man/borg-rename.1
+++ b/docs/man/borg-rename.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-RENAME 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-RENAME 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-rename \- Rename an existing archive
 .
--- a/docs/man/borg-serve.1
+++ b/docs/man/borg-serve.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-SERVE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-SERVE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-serve \- Start in server mode. This command is usually not used manually.
 .
--- a/docs/man/borg-umount.1
+++ b/docs/man/borg-umount.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UMOUNT 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-UMOUNT 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-umount \- un-mount the FUSE filesystem
 .
--- a/docs/man/borg-upgrade.1
+++ b/docs/man/borg-upgrade.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-UPGRADE 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-UPGRADE 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-upgrade \- upgrade a repository from a previous version
 .
--- a/docs/man/borg-with-lock.1
+++ b/docs/man/borg-with-lock.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORG-WITH-LOCK 1 "2020-10-06" "" "borg backup tool"
+.TH BORG-WITH-LOCK 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borg-with-lock \- run a user specified command with the repository lock held
 .
--- a/docs/man/borg.1
+++ b/docs/man/borg.1
@ -205,7 +205,7 @@ borg create repo::archive \-s \-\-progress path  # BAD
 .UNINDENT
 .UNINDENT
 .sp
-This is due to a problem in the argparse module: \fI\%http://bugs.python.org/issue15112\fP
+This is due to a problem in the argparse module: \fI\%https://bugs.python.org/issue15112\fP
 .SS Repository URLs
 .sp
 \fBLocal filesystem\fP (or locally mounted network filesystem):
@ -441,6 +441,11 @@ the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
 When set, use the given path as borg executable on the remote (defaults to "borg" if unset).
 Using \fB\-\-remote\-path PATH\fP commandline option overrides the environment variable.
 .TP
+.B BORG_FILES_CACHE_SUFFIX
+When set to a value at least one character long, instructs borg to use a specifically named
+(based on the suffix) alternative files cache. This can be used to avoid loading and saving
+cache entries for backup sources other than the current sources.
+.TP
 .B BORG_FILES_CACHE_TTL
 When set to a numeric value, this determines the maximum "time to live" for the files cache
 entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
@ -584,7 +589,9 @@ Up to 1000 files per directory (10000 for repositories initialized with Borg 1.0
 .IP \(bu 2
 mkdir(2) should be atomic, since it is used for locking
 .IP \(bu 2
-Hardlinks are needed for \fIborg_upgrade\fP \fB\-\-inplace\fP
+Hardlinks are needed for \fIborg_upgrade\fP (if \fB\-\-inplace\fP option is not used).
+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.
 .UNINDENT
 .SS Units
 .sp
--- a/docs/man/borgfs.1
+++ b/docs/man/borgfs.1
@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH BORGFS 1 "2020-10-06" "" "borg backup tool"
+.TH BORGFS 1 "2020-12-24" "" "borg backup tool"
 .SH NAME
 borgfs \- Mount archive or an entire repository as a FUSE filesystem
 .