diff --git a/Vagrantfile b/Vagrantfile index 2a4a3d8f2..93b67f5e8 100644 --- a/Vagrantfile +++ b/Vagrantfile @@ -102,7 +102,6 @@ def packages_openbsd pkg_add git # no fakeroot pkg_add py3-pip pkg_add py3-virtualenv - ln -sf /usr/local/bin/virtualenv-3 /usr/local/bin/virtualenv EOF end @@ -225,7 +224,7 @@ def install_pythons(boxname) . ~/.bash_profile pyenv install 3.5.3 # tests, 3.5.3 is first to support openssl 1.1 pyenv install 3.6.2 # tests - pyenv install 3.7.11 # binary build, use latest 3.7.x release + pyenv install 3.7.12 # binary build, use latest 3.7.x release pyenv install 3.8.0 # tests pyenv install 3.9.0 # tests pyenv install 3.10.0 # tests @@ -246,8 +245,8 @@ def build_pyenv_venv(boxname) . ~/.bash_profile cd /vagrant/borg # use the latest 3.7 release - pyenv global 3.7.11 - pyenv virtualenv 3.7.11 borg-env + pyenv global 3.7.12 + pyenv virtualenv 3.7.12 borg-env ln -s ~/.pyenv/versions/borg-env . EOF end @@ -310,8 +309,8 @@ def run_tests(boxname) if which pyenv 2> /dev/null; then # for testing, use the earliest point releases of the supported python versions. # on some dists, 3.10 does not compile, so if pyenv fails due to this, try without 3.10. - pyenv global 3.5.3 3.6.2 3.7.11 3.8.0 3.9.0 3.10.0 || pyenv global 3.5.3 3.6.2 3.7.11 3.8.0 3.9.0 - pyenv local 3.5.3 3.6.2 3.7.11 3.8.0 3.9.0 3.10.0 || pyenv local 3.5.3 3.6.2 3.7.11 3.8.0 3.9.0 + pyenv global 3.5.3 3.6.2 3.7.12 3.8.0 3.9.0 3.10.0 || pyenv global 3.5.3 3.6.2 3.7.12 3.8.0 3.9.0 + pyenv local 3.5.3 3.6.2 3.7.12 3.8.0 3.9.0 3.10.0 || pyenv local 3.5.3 3.6.2 3.7.12 3.8.0 3.9.0 fi # otherwise: just use the system python if which fakeroot 2> /dev/null; then @@ -475,11 +474,10 @@ Vagrant.configure(2) do |config| end config.vm.define "openbsd64" do |b| - b.vm.box = "openbsd64-64" # note: basic openbsd install for vagrant WITH sudo and rsync pre-installed + b.vm.box = "generic/openbsd6" b.vm.provider :virtualbox do |v| v.memory = 1024 + $wmem end - b.ssh.shell = "sh" b.vm.provision "fs init", :type => :shell, :inline => fs_init("vagrant") b.vm.provision "packages openbsd", :type => :shell, :inline => packages_openbsd b.vm.provision "build env", :type => :shell, :privileged => false, :inline => build_sys_venv("openbsd64") diff --git a/docs/changes.rst b/docs/changes.rst index af6ce9350..e29445fa9 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -217,8 +217,8 @@ The best check that everything is ok is to run a dry-run extraction:: Changelog ========= -Version 1.1.18 (not released yet) ---------------------------------- +Version 1.1.18 (2022-06-05) +--------------------------- Compatibility notes: @@ -256,7 +256,7 @@ New features: Fixes: - check: improve error handling for corrupt archive metadata block, - make robust_iterator more robust, #4777 + make robust_iterator more robust, #4777 - diff: support presence change for blkdev, chrdev and fifo items, #6483 - diff: reduce memory consumption, fix is_hardlink_master - init: disallow overwriting of existing keyfiles @@ -287,8 +287,10 @@ Fixes: Other changes: -- fix xxh64 related build (setup.py) - upgrade bundled xxhash code to 0.8.1 +- fix xxh64 related build (setup.py and post-0.8.1 patch for static_assert). + The patch was required to build the bundled xxhash code on FreeBSD, see + https://github.com/Cyan4973/xxHash/pull/670 - msgpack build: remove endianness macro, #6105 - update and fix shell completions - fuse: remove unneeded version check and compat code @@ -308,6 +310,7 @@ Other changes: - allow extra compiler flags for every extension build - C code: make switch fallthrough explicit - Cython code: fix "useless trailing comma" cython warnings +- requirements.lock.txt: use the latest cython 0.29.30 - fix compilation warnings: ‘PyUnicode_AsUnicode’ is deprecated - docs: @@ -350,6 +353,7 @@ Other changes: - misc. fixes and updates, new python versions - macOS on github: re-enable fuse2 testing by downgrading to older macOS, #6099 - fix OpenBSD symlink mode test failure, #2055 + - use the generic/openbsd6 box - strengthen the test: we can read data w/o nonces - add tests for path/to/repo/nonce deletion - darwin64: backport some tunings from master diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index e2ceca444..4f1820eb7 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK-CRUD 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-BENCHMARK-CRUD" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. .SH SYNOPSIS .sp borg [common options] benchmark crud [options] REPOSITORY PATH diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index 43bbb6250..6e1e52a28 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-benchmark \- benchmark command . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-BENCHMARK" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-benchmark \- benchmark command .SH SYNOPSIS .nf borg [common options] benchmark crud ... diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index 6a85e8111..76161d7f5 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BREAK-LOCK 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-BREAK-LOCK" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. .SH SYNOPSIS .sp borg [common options] break\-lock [options] [REPOSITORY] diff --git a/docs/man/borg-change-passphrase.1 b/docs/man/borg-change-passphrase.1 index a02f0858b..afebc9f2e 100644 --- a/docs/man/borg-change-passphrase.1 +++ b/docs/man/borg-change-passphrase.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CHANGE-PASSPHRASE 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-change-passphrase \- Change repository key file passphrase . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-CHANGE-PASSPHRASE" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS .sp borg [common options] change\-passphrase [options] [REPOSITORY] diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 6ea4d7175..969a012aa 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CHECK 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-check \- Check repository consistency . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-CHECK" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-check \- Check repository consistency .SH SYNOPSIS .sp borg [common options] check [options] [REPOSITORY_OR_ARCHIVE] @@ -116,19 +116,19 @@ repository or archive to check consistency of .SS optional arguments .INDENT 0.0 .TP -.B \-\-repository\-only +.B \-\-repository\-only only perform repository checks .TP -.B \-\-archives\-only +.B \-\-archives\-only only perform archives checks .TP -.B \-\-verify\-data +.B \-\-verify\-data perform cryptographic archive data integrity verification (conflicts with \fB\-\-repository\-only\fP) .TP -.B \-\-repair +.B \-\-repair attempt to repair any inconsistencies found .TP -.B \-\-save\-space +.B \-\-save\-space work slower, but using less space .UNINDENT .SS Archive filters diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 150e3f5a1..a31343269 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMMON 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-common \- Common options of Borg commands . .nr rst2man-indent-level 0 . @@ -30,46 +27,49 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-COMMON" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-common \- Common options of Borg commands .SH SYNOPSIS .INDENT 0.0 .TP -.B \-h\fP,\fB \-\-help +.B \-h\fP,\fB \-\-help show this help message and exit .TP -.B \-\-critical +.B \-\-critical work on log level CRITICAL .TP -.B \-\-error +.B \-\-error work on log level ERROR .TP -.B \-\-warning +.B \-\-warning work on log level WARNING (default) .TP -.B \-\-info\fP,\fB \-v\fP,\fB \-\-verbose +.B \-\-info\fP,\fB \-v\fP,\fB \-\-verbose work on log level INFO .TP -.B \-\-debug +.B \-\-debug enable debug output, work on log level DEBUG .TP .BI \-\-debug\-topic \ TOPIC enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug. if TOPIC is not fully qualified. .TP -.B \-p\fP,\fB \-\-progress +.B \-p\fP,\fB \-\-progress show progress information .TP -.B \-\-log\-json +.B \-\-log\-json Output one JSON object per log line instead of formatted text. .TP .BI \-\-lock\-wait \ SECONDS wait at most SECONDS for acquiring a repository/cache lock (default: 1). .TP -.B \-\-bypass\-lock +.B \-\-bypass\-lock Bypass locking mechanism .TP -.B \-\-show\-version +.B \-\-show\-version show/log the borg version .TP -.B \-\-show\-rc +.B \-\-show\-rc show/log the return code (rc) .TP .BI \-\-umask \ M @@ -81,7 +81,7 @@ use PATH as borg executable on the remote (default: "borg") .BI \-\-remote\-ratelimit \ RATE set remote network upload rate limit in kiByte/s (default: 0=unlimited) .TP -.B \-\-consider\-part\-files +.B \-\-consider\-part\-files treat part files like normal files (e.g. to list/extract them) .TP .BI \-\-debug\-profile \ FILE diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index 3eb3ce73d..fc3dd9e5b 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMPRESSION 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-compression \- Details regarding compression . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-COMPRESSION" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-compression \- Details regarding compression .SH DESCRIPTION .sp It is no problem to mix different compression methods in one repo, diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index 06bf50e13..6c0fa3506 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CONFIG 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-config \- get, set, and delete values in a repository or cache config file . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-CONFIG" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-config \- get, set, and delete values in a repository or cache config file .SH SYNOPSIS .sp borg [common options] config [options] [REPOSITORY] [NAME] [VALUE] @@ -65,13 +65,13 @@ new value for key .SS optional arguments .INDENT 0.0 .TP -.B \-c\fP,\fB \-\-cache +.B \-c\fP,\fB \-\-cache get and set values from the repo cache .TP -.B \-d\fP,\fB \-\-delete +.B \-d\fP,\fB \-\-delete delete the key from the config file .TP -.B \-l\fP,\fB \-\-list +.B \-l\fP,\fB \-\-list list the configuration of the repo .UNINDENT .SH EXAMPLES diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 32213ed9d..950ec158d 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CREATE 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-create \- Create new archive . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-CREATE" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-create \- Create new archive .SH SYNOPSIS .sp borg [common options] create [options] ARCHIVE [PATH...] @@ -116,9 +116,9 @@ how much your repository will grow. Please note that the "All archives" stats re the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP options are mutually 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. +For more help on include/exclude patterns, see the \fIborg_patterns\fP command output. .sp -See the output of the "borg help placeholders" command for more help on placeholders. +For more help on placeholders, see the \fIborg_placeholders\fP command output. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. @@ -134,25 +134,25 @@ paths to archive .SS optional arguments .INDENT 0.0 .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not create a backup archive .TP -.B \-s\fP,\fB \-\-stats +.B \-s\fP,\fB \-\-stats print statistics for the created archive .TP -.B \-\-list +.B \-\-list output verbose list of items (files, dirs, ...) .TP .BI \-\-filter \ STATUSCHARS only display items with the given status characters (see description) .TP -.B \-\-json +.B \-\-json output stats as JSON. Implies \fB\-\-stats\fP\&. .TP -.B \-\-no\-cache\-sync +.B \-\-no\-cache\-sync experimental: do not synchronize the cache. Implies not using the files cache. .TP -.B \-\-no\-files\-cache +.B \-\-no\-files\-cache do not load/update the file metadata cache used to detect unchanged files .TP .BI \-\-stdin\-name \ NAME @@ -162,7 +162,7 @@ use NAME in archive for stdin data (default: "stdin") set user USER in archive for stdin data (default: \(aqroot\(aq) .TP .BI \-\-stdin\-group \ GROUP -set group GROUP in archive for stdin data (default: \(aqroot\(aq) +set group GROUP in archive for stdin data (default: \(aqwheel\(aq) .TP .BI \-\-stdin\-mode \ M set mode to M in archive for stdin data (default: 0660) @@ -177,57 +177,57 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP -.B \-\-exclude\-caches +.B \-\-exclude\-caches exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP) .TP .BI \-\-exclude\-if\-present \ NAME exclude directories that are tagged by containing a filesystem object with the given NAME .TP -.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files +.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive .TP -.B \-\-exclude\-nodump +.B \-\-exclude\-nodump exclude files flagged NODUMP .UNINDENT .SS Filesystem options .INDENT 0.0 .TP -.B \-x\fP,\fB \-\-one\-file\-system +.B \-x\fP,\fB \-\-one\-file\-system stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs. .TP -.B \-\-numeric\-owner +.B \-\-numeric\-owner only store numeric user and group identifiers .TP -.B \-\-noatime +.B \-\-noatime do not store atime into archive .TP -.B \-\-noctime +.B \-\-noctime do not store ctime into archive .TP -.B \-\-nobirthtime +.B \-\-nobirthtime do not store birthtime (creation date) into archive .TP -.B \-\-nobsdflags +.B \-\-nobsdflags do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive .TP -.B \-\-noacls +.B \-\-noacls do not read and store ACLs into archive .TP -.B \-\-noxattrs +.B \-\-noxattrs do not read and store xattrs into archive .TP -.B \-\-ignore\-inode +.B \-\-ignore\-inode ignore inode data in the file metadata cache used to detect unchanged files. .TP .BI \-\-files\-cache \ MODE operate files cache in MODE. default: ctime,size,inode .TP -.B \-\-read\-special +.B \-\-read\-special open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files. .UNINDENT .SS Archive options @@ -325,8 +325,7 @@ $ borg create /path/to/repo::daily\-projectA\-{now:%Y\-%m\-%d} projectA .sp The \fB\-\-exclude\fP patterns are not like tar. In tar \fB\-\-exclude\fP .bundler/gems will exclude foo/.bundler/gems. In borg it will not, you need to use \fB\-\-exclude\fP -\(aq*/.bundler/gems\(aq to get the same effect. See \fBborg help patterns\fP for -more information. +\(aq*/.bundler/gems\(aq to get the same effect. .sp In addition to using \fB\-\-exclude\fP patterns, it is possible to use \fB\-\-exclude\-if\-present\fP to specify the name of a filesystem object (e.g. a file diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index dba9a7840..30ad5f3eb 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DELETE 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-delete \- Delete an existing repository or archives . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-DELETE" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-delete \- Delete an existing repository or archives .SH SYNOPSIS .sp borg [common options] delete [options] [REPOSITORY_OR_ARCHIVE] [ARCHIVE...] @@ -58,19 +58,19 @@ archives to delete .SS optional arguments .INDENT 0.0 .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not change repository .TP -.B \-s\fP,\fB \-\-stats +.B \-s\fP,\fB \-\-stats print statistics for the deleted archive .TP -.B \-\-cache\-only +.B \-\-cache\-only delete only the local cache for the given repository .TP -.B \-\-force +.B \-\-force force deletion of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work. .TP -.B \-\-save\-space +.B \-\-save\-space work slower, but using less space .UNINDENT .SS Archive filters diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index b2d5f8f3a..424ad07a6 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DIFF 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-diff \- Diff contents of two archives . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-DIFF" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-diff \- Diff contents of two archives .SH SYNOPSIS .sp borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...] @@ -50,7 +50,7 @@ If you did not create the archives with different chunker params, pass \fB\-\-same\-chunker\-params\fP\&. Note that the chunker params changed from Borg 0.xx to 1.0. .sp -See the output of the "borg help patterns" command for more help on exclude patterns. +For more help on include/exclude patterns, see the \fIborg_patterns\fP command output. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. @@ -69,16 +69,16 @@ paths of items inside the archives to compare; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-numeric\-owner +.B \-\-numeric\-owner only consider numeric user and group identifiers .TP -.B \-\-same\-chunker\-params +.B \-\-same\-chunker\-params Override check of chunker parameters. .TP -.B \-\-sort +.B \-\-sort Sort the output lines by file path. .TP -.B \-\-json\-lines +.B \-\-json\-lines Format output as JSON Lines. .UNINDENT .SS Exclusion options @@ -91,10 +91,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index e4ff99fa4..059594955 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXPORT-TAR 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-export-tar \- Export archive contents as a tarball . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-EXPORT-TAR" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-export-tar \- Export archive contents as a tarball .SH SYNOPSIS .sp borg [common options] export\-tar [options] ARCHIVE FILE [PATH...] @@ -68,7 +68,7 @@ By default the entire archive is extracted but a subset of files and directories can be selected by passing a list of \fBPATHs\fP as arguments. The file selection can further be restricted by using the \fB\-\-exclude\fP option. .sp -See the output of the "borg help patterns" command for more help on exclude patterns. +For more help on include/exclude patterns, see the \fIborg_patterns\fP command output. .sp \fB\-\-progress\fP can be slower than no progress display, since it makes one additional pass over the archive metadata. @@ -90,10 +90,10 @@ paths to extract; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-tar\-filter +.B \-\-tar\-filter filter program to pipe data through .TP -.B \-\-list +.B \-\-list output verbose list of items (files, dirs, ...) .UNINDENT .SS Exclusion options @@ -106,10 +106,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index 158bcbf14..85699a1dd 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXTRACT 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-extract \- Extract archive contents . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-EXTRACT" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-extract \- Extract archive contents .SH SYNOPSIS .sp borg [common options] extract [options] ARCHIVE [PATH...] @@ -40,7 +40,7 @@ archive is extracted but a subset of files and directories can be selected by passing a list of \fBPATHs\fP as arguments. The file selection can further be restricted by using the \fB\-\-exclude\fP option. .sp -See the output of the "borg help patterns" command for more help on exclude patterns. +For more help on include/exclude patterns, see the \fIborg_patterns\fP command output. .sp 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, @@ -54,6 +54,10 @@ pass over the archive metadata. .INDENT 3.5 Currently, extract always writes into the current working directory ("."), so make sure you \fBcd\fP to the right place before calling \fBborg extract\fP\&. +.sp +When parent directories are not extracted (because of using file/directory selection +or any other reason), borg can not restore parent directories\(aq metadata, e.g. owner, +group, permission, etc. .UNINDENT .UNINDENT .SH OPTIONS @@ -71,28 +75,28 @@ paths to extract; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-list +.B \-\-list output verbose list of items (files, dirs, ...) .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not actually change any files .TP -.B \-\-numeric\-owner +.B \-\-numeric\-owner only obey numeric user and group identifiers .TP -.B \-\-nobsdflags +.B \-\-nobsdflags do not extract/set bsdflags (e.g. NODUMP, IMMUTABLE) .TP -.B \-\-noacls +.B \-\-noacls do not extract/set ACLs .TP -.B \-\-noxattrs +.B \-\-noxattrs do not extract/set xattrs .TP -.B \-\-stdout +.B \-\-stdout write all extracted data to stdout .TP -.B \-\-sparse +.B \-\-sparse create holes in output sparse file from all\-zero chunks .UNINDENT .SS Exclusion options @@ -105,10 +109,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index a810318d1..92dca61d7 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INFO 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-info \- Show archive details such as disk space used . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-INFO" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-info \- Show archive details such as disk space used .SH SYNOPSIS .sp borg [common options] info [options] [REPOSITORY_OR_ARCHIVE] @@ -62,7 +62,7 @@ repository or archive to display information about .SS optional arguments .INDENT 0.0 .TP -.B \-\-json +.B \-\-json format output as JSON .UNINDENT .SS Archive filters diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index ab7706cb8..ab840767a 100644 --- a/docs/man/borg-init.1 +++ b/docs/man/borg-init.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INIT 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-init \- Initialize an empty repository . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-INIT" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-init \- Initialize an empty repository .SH SYNOPSIS .sp borg [common options] init [options] [REPOSITORY] @@ -37,32 +37,61 @@ borg [common options] init [options] [REPOSITORY] .sp This command initializes an empty repository. A repository is a filesystem directory containing the deduplicated data from zero or more archives. +.SS Encryption mode TLDR .sp -Encryption can be enabled at repository init time. It cannot be changed later. +The encryption mode can only be configured when creating a new repository \- +you can neither configure it on a per\-archive basis nor change the +encryption mode of an existing repository. .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. +Use \fBrepokey\fP: +.INDENT 0.0 +.INDENT 3.5 .sp -Borg relies on randomly generated key material and uses that for chunking, id -generation, encryption and authentication. The key material is encrypted using -the passphrase you give before it is stored on\-disk. +.nf +.ft C +borg init \-\-encryption repokey /path/to/repo +.ft P +.fi +.UNINDENT +.UNINDENT .sp -You need to be careful with the key / the passphrase: +Or \fBrepokey\-blake2\fP depending on which is faster on your client machines (see below): +.INDENT 0.0 +.INDENT 3.5 .sp -If you want "passphrase\-only" security, use one of the repokey modes. The -key will be stored inside the repository (in its "config" file). In above -mentioned attack scenario, the attacker will have the key (but not the -passphrase). +.nf +.ft C +borg init \-\-encryption repokey\-blake2 /path/to/repo +.ft P +.fi +.UNINDENT +.UNINDENT .sp -If you want "passphrase and having\-the\-key" security, use one of the keyfile -modes. The key will be stored in your home directory (in .config/borg/keys). -In the attack scenario, the attacker who has just access to your repo won\(aqt -have the key (and also not the passphrase). -.sp -Make a backup copy of the key file (keyfile mode) or repo config file -(repokey mode) and keep it at a safe place, so you still have the key in -case it gets corrupted or lost. Also keep the passphrase at a safe place. -The backup that is encrypted with that key won\(aqt help you with that, of course. +Borg will: +.INDENT 0.0 +.IP 1. 3 +Ask you to come up with a passphrase. +.IP 2. 3 +Create a borg key (which contains 3 random secrets. See \fIkey_files\fP). +.IP 3. 3 +Encrypt the key with your passphrase. +.IP 4. 3 +Store the encrypted borg key inside the repository directory (in the repo config). +This is why it is essential to use a secure passphrase. +.IP 5. 3 +Encrypt and sign your backups to prevent anyone from reading or forging them unless they +have the key and know the passphrase. Make sure to keep a backup of +your key \fBoutside\fP the repository \- do not lock yourself out by +"leaving your keys inside your car" (see \fIborg_key_export\fP). +For remote backups the encryption is done locally \- the remote machine +never sees your passphrase, your unencrypted key or your unencrypted files. +Chunking and id generation are also based on your key to improve +your privacy. +.IP 6. 3 +Use the key when extracting files to decrypt them and to verify that the contents of +the backups have not been accidentally or maliciously altered. +.UNINDENT +.SS Picking a passphrase .sp Make sure you use a good passphrase. Not too short, not too simple. The real encryption / decryption key is encrypted with / locked by your passphrase. @@ -84,13 +113,21 @@ a different keyboard layout. .sp You can change your passphrase for existing repos at any time, it won\(aqt affect the encryption/decryption key or other secrets. -.SS Encryption modes +.SS More encryption modes .sp -You can choose from the encryption modes seen in the table below on a per\-repo -basis. The mode determines encryption algorithm, hash/MAC algorithm and also the -key storage location. +Only use \fB\-\-encryption none\fP if you are OK with anyone who has access to +your repository being able to read your backups and tamper with their +contents without you noticing. .sp -Example: \fIborg init \-\-encryption repokey ...\fP +If you want "passphrase and having\-the\-key" security, use \fB\-\-encryption keyfile\fP\&. +The key will be stored in your home directory (in \fB~/.config/borg/keys\fP). +.sp +If you do \fBnot\fP want to encrypt the contents of your backups, but still +want to detect malicious tampering use \fB\-\-encryption authenticated\fP\&. +.sp +If \fBBLAKE2b\fP is faster than \fBSHA\-256\fP on your hardware, use \fB\-\-encryption authenticated\-blake2\fP, +\fB\-\-encryption repokey\-blake2\fP or \fB\-\-encryption keyfile\-blake2\fP\&. Note: for remote backups +the hashing is done on your local machine. .\" nanorst: inline-fill . .TS @@ -192,13 +229,13 @@ repository to create .BI \-e \ MODE\fR,\fB \ \-\-encryption \ MODE select encryption key mode \fB(required)\fP .TP -.B \-\-append\-only +.B \-\-append\-only create an append\-only mode repository .TP .BI \-\-storage\-quota \ QUOTA Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. .TP -.B \-\-make\-parent\-dirs +.B \-\-make\-parent\-dirs create the parent directories of the repository directory, if they are missing. .UNINDENT .SH EXAMPLES diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index 6d2806243..84b446c1b 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-key-change-passphrase \- Change repository key file passphrase . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-CHANGE-PASSPHRASE" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-key-change-passphrase \- Change repository key file passphrase .SH SYNOPSIS .sp borg [common options] key change\-passphrase [options] [REPOSITORY] diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 94ddb828b..ac2ae1d61 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-EXPORT 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-key-export \- Export the repository key for backup . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-EXPORT" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-key-export \- Export the repository key for backup .SH SYNOPSIS .sp borg [common options] key export [options] [REPOSITORY] [PATH] @@ -55,6 +55,24 @@ For repositories using the repokey encryption the key is saved in the repository in the config file. A backup is thus not strictly needed, but guards against the repository becoming inaccessible if the file is damaged for some reason. +.sp +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +borg key export /path/to/repo > encrypted\-key\-backup +borg key export \-\-paper /path/to/repo > encrypted\-key\-backup.txt +borg key export \-\-qr\-html /path/to/repo > encrypted\-key\-backup.html +# Or pass the output file as an argument instead of redirecting stdout: +borg key export /path/to/repo encrypted\-key\-backup +borg key export \-\-paper /path/to/repo encrypted\-key\-backup.txt +borg key export \-\-qr\-html /path/to/repo encrypted\-key\-backup.html +.ft P +.fi +.UNINDENT +.UNINDENT .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. @@ -69,10 +87,10 @@ where to store the backup .SS optional arguments .INDENT 0.0 .TP -.B \-\-paper +.B \-\-paper Create an export suitable for printing and later type\-in .TP -.B \-\-qr\-html +.B \-\-qr\-html Create an html file suitable for printing and later type\-in or qr scan .UNINDENT .SH SEE ALSO diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index 069bb16c4..116157f2e 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-IMPORT 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-key-import \- Import the repository key from backup . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-IMPORT" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-key-import \- Import the repository key from backup .SH SYNOPSIS .sp borg [common options] key import [options] [REPOSITORY] [PATH] @@ -55,7 +55,7 @@ path to the backup (\(aq\-\(aq to read from stdin) .SS optional arguments .INDENT 0.0 .TP -.B \-\-paper +.B \-\-paper interactively import from a backup done with \fB\-\-paper\fP .UNINDENT .SH SEE ALSO diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index 03de5571e..91ff32c79 100644 --- a/docs/man/borg-key-migrate-to-repokey.1 +++ b/docs/man/borg-key-migrate-to-repokey.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-key-migrate-to-repokey \- Migrate passphrase -> repokey . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY-MIGRATE-TO-REPOKEY" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-key-migrate-to-repokey \- Migrate passphrase -> repokey .SH SYNOPSIS .sp borg [common options] key migrate\-to\-repokey [options] [REPOSITORY] diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 7f678b7ce..e737b4f82 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-key \- Manage a keyfile or repokey of a repository . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-KEY" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-key \- Manage a keyfile or repokey of a repository .SH SYNOPSIS .nf borg [common options] key export ... diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index f75309dd2..67e5b377e 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-LIST 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-list \- List archive or repository contents . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-LIST" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-list \- List archive or repository contents .SH SYNOPSIS .sp borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...] @@ -37,7 +37,7 @@ borg [common options] list [options] [REPOSITORY_OR_ARCHIVE] [PATH...] .sp This command lists the contents of a repository or an archive. .sp -See the "borg help patterns" command for more help on exclude patterns. +For more help on include/exclude patterns, see the \fIborg_patterns\fP command output. .SH OPTIONS .sp See \fIborg\-common(1)\fP for common options of Borg commands. @@ -53,16 +53,16 @@ paths to list; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-short +.B \-\-short only print file/directory names, nothing else .TP .BI \-\-format \ FORMAT\fR,\fB \ \-\-list\-format \ FORMAT -specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}") +specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}") .TP -.B \-\-json +.B \-\-json Only valid for listing repository contents. Format output as JSON. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. .TP -.B \-\-json\-lines +.B \-\-json\-lines Only valid for listing archive contents. Format output as JSON Lines. The form of \fB\-\-format\fP is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. .UNINDENT .SS Archive filters @@ -93,10 +93,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .UNINDENT .SH EXAMPLES .INDENT 0.0 @@ -131,21 +131,64 @@ drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 . drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code/myproject \-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext +\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text +\&... + +$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:\e.ext$\(aq +\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext +\&... + +$ borg list /path/to/repo/::archiveA \-\-pattern \(aqre:.ext$\(aq +\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.ext +\-rw\-rw\-r\-\- user user 1416192 Sun, 2015\-02\-01 11:00:00 code/myproject/file.text \&... .ft P .fi .UNINDENT .UNINDENT .SH NOTES +.SS The FORMAT specifier syntax .sp -The following keys are available for \fB\-\-format\fP: +The \fB\-\-format\fP option uses python\(aqs \fI\%format string syntax\fP\&. +.sp +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ borg list \-\-format \(aq{archive}{NL}\(aq /path/to/repo +ArchiveFoo +ArchiveBar +\&... + +# {VAR:NUMBER} \- pad to NUMBER columns. +# Strings are left\-aligned, numbers are right\-aligned. +# Note: time columns except \(ga\(gaisomtime\(ga\(ga, \(ga\(gaisoctime\(ga\(ga and \(ga\(gaisoatime\(ga\(ga cannot be padded. +$ borg list \-\-format \(aq{archive:36} {time} [{id}]{NL}\(aq /path/to/repo +ArchiveFoo Thu, 2021\-12\-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274] +$ borg list \-\-format \(aq{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo +\-rw\-rw\-r\-\- user user 1024 Thu, 2021\-12\-09 10:22:17 file\-foo +\&... + +# {VAR:NUMBER} \- pad to NUMBER columns right\-aligned. +$ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}\(aq /path/to/repo::ArchiveFoo +\-rw\-rw\-r\-\- user user 1024 Thu, 2021\-12\-09 10:22:17 file\-foo +\&... +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The following keys are always available: .INDENT 0.0 .IP \(bu 2 NEWLINE: OS dependent line separator .IP \(bu 2 NL: alias of NEWLINE .IP \(bu 2 -NUL: NUL character for creating print0 / xargs \-0 like output, see barchive/bpath +NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below .IP \(bu 2 SPACE .IP \(bu 2 @@ -156,7 +199,7 @@ CR LF .UNINDENT .sp -Keys for listing repository archives: +Keys available only when listing archives in a repository: .INDENT 0.0 .IP \(bu 2 archive: archive name interpreted as text (might be missing non\-text characters, see barchive) @@ -177,12 +220,14 @@ time: alias of "start" .IP \(bu 2 end: time (end) of creation of the archive .IP \(bu 2 +command_line: command line which was used to create the archive +.IP \(bu 2 hostname: hostname of host on which this archive was created .IP \(bu 2 username: username of user who created this archive .UNINDENT .sp -Keys for listing archive files: +Keys available only when listing files in an archive: .INDENT 0.0 .IP \(bu 2 type @@ -255,10 +300,6 @@ sha3_512 .IP \(bu 2 sha512 .IP \(bu 2 -shake_128 -.IP \(bu 2 -shake_256 -.IP \(bu 2 archiveid .IP \(bu 2 archivename diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 7bfbc4963..2471a09eb 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-MOUNT 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-mount \- Mount archive or an entire repository as a FUSE filesystem . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-MOUNT" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-mount \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS .sp borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...] @@ -49,6 +49,23 @@ To allow a regular user to use fstab entries, add the \fBuser\fP option: .sp For FUSE configuration and mount options, see the mount.fuse(8) manual page. .sp +Borg\(aqs default behavior is to use the archived user and group names of each +file and map them to the system\(aqs respective user and group ids. +Alternatively, using \fBnumeric\-ids\fP will instead use the archived user and +group ids without any mapping. +.sp +The \fBuid\fP and \fBgid\fP mount options (implemented by Borg) can be used to +override the user and group ids of all files (i.e., \fBborg mount \-o +uid=1000,gid=1000\fP). +.sp +The man page references \fBuser_id\fP and \fBgroup_id\fP mount options +(implemented by fuse) which specify the user and group id of the mount owner +(aka, the user who does the mounting). It is set automatically by libfuse (or +the filesystem if libfuse is not used). However, you should not specify these +manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all files, +\fBuser_id\fP and \fBgroup_id\fP affect the user and group id of the mounted +(base) directory. +.sp Additional mount options supported by borg: .INDENT 0.0 .IP \(bu 2 @@ -93,10 +110,10 @@ paths to extract; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-f\fP,\fB \-\-foreground +.B \-f\fP,\fB \-\-foreground stay in foreground, do not daemonize .TP -.B \-o +.B \-o Extra mount options .UNINDENT .SS Archive filters @@ -127,10 +144,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 6c9c41329..b8e6dd01d 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PATTERNS 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-patterns \- Details regarding patterns . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-PATTERNS" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-patterns \- Details regarding patterns .SH DESCRIPTION .sp The path/filenames used as input for the pattern matching start from the @@ -50,10 +50,14 @@ patterns when matching archive content in commands like \fBextract\fP or \fBmount\fP\&. Starting with Borg 1.2 this behaviour will be changed to accept both absolute and relative paths. .sp +A directory exclusion pattern can end either with or without a slash (\(aq/\(aq). +If it ends with a slash, such as \fIsome/path/\fP, the directory will be +included but not its content. If it does not end with a slash, such as +\fIsome/path\fP, both the directory and content will be excluded. +.sp File patterns support these styles: fnmatch, shell, regular expressions, path prefixes and path full\-matches. By default, fnmatch is used for -\fB\-\-exclude\fP patterns and shell\-style is used for the experimental -\fB\-\-pattern\fP option. +\fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP option. .sp If followed by a colon (\(aq:\(aq) the first two characters of a pattern are used as a style selector. Explicit style selection is necessary when a @@ -178,9 +182,10 @@ $ borg create \-\-exclude\-from exclude.txt backup / .fi .UNINDENT .UNINDENT +.sp A more general and easier to use way to define filename matching patterns exists -with the experimental \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you -may specify the backup roots (starting points) and patterns for inclusion/exclusion. +with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you may +specify the backup roots (starting points) and patterns for inclusion/exclusion. A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a file pattern). An include rule starts with the prefix +, an exclude rule starts with the prefix \-, an exclude\-norecurse rule starts with !, all followed by a pattern. @@ -200,6 +205,15 @@ an exclude pattern, the file is backed up. If an exclude\-norecurse pattern matc a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for include rules below that directory. .sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +It\(aqs possible that a sub\-directory/file is matched while parent directories are not. +In that case, parent directories are not backed up thus their user, group, permission, +etc. can not be restored. +.UNINDENT +.UNINDENT +.sp Note that the default pattern style for \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP is shell style (\fIsh:\fP), so those patterns behave similar to rsync include/exclude patterns. The pattern style can be set via the \fIP\fP prefix. @@ -241,6 +255,8 @@ R / # susan is a nice person # include susans home + /home/susan +# also back up this exact file ++ pf:/home/bobby/specialfile.txt # don\(aqt backup the other home directories \- /home/* # don\(aqt even look in /proc @@ -249,6 +265,41 @@ R / .fi .UNINDENT .UNINDENT +.sp +You can specify recursion roots either on the command line or in a patternfile: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# these two commands do the same thing +borg create \-\-exclude /home/bobby/junk repo::arch /home/bobby /home/susan +borg create \-\-patterns\-from patternfile.lst repo::arch +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The patternfile: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# note that excludes use fm: by default and patternfiles use sh: by default. +# therefore, we need to specify fm: to have the same exact behavior. +P fm +R /home/bobby +R /home/susan + +\- /home/bobby/junk +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +This allows you to share the same patterns between multiple repositories +without needing to specify them on the command line. .SH AUTHOR The Borg Collective .\" Generated by docutils manpage writer. diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index de97fcc77..c95c9357b 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PLACEHOLDERS 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-placeholders \- Details regarding placeholders . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-PLACEHOLDERS" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-placeholders \- Details regarding placeholders .SH DESCRIPTION .sp Repository (or Archive) URLs, \fB\-\-prefix\fP, \fB\-\-glob\-archives\fP, \fB\-\-comment\fP diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index 827eb70ba..c57d37335 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PRUNE 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-prune \- Prune repository archives according to specified rules . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-PRUNE" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-prune \- Prune repository archives according to specified rules .SH SYNOPSIS .sp borg [common options] prune [options] [REPOSITORY] @@ -38,6 +38,9 @@ borg [common options] prune [options] [REPOSITORY] The prune command prunes a repository by deleting all archives not matching any of the specified retention options. This command is normally used by automated backup scripts wanting to keep a certain number of historic backups. +This retention policy is commonly referred to as +\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 @@ -90,43 +93,43 @@ repository to prune .SS optional arguments .INDENT 0.0 .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not change repository .TP -.B \-\-force +.B \-\-force force pruning of corrupted archives, use \fB\-\-force \-\-force\fP in case \fB\-\-force\fP does not work. .TP -.B \-s\fP,\fB \-\-stats +.B \-s\fP,\fB \-\-stats print statistics for the deleted archive .TP -.B \-\-list +.B \-\-list output verbose list of archives it keeps/prunes .TP .BI \-\-keep\-within \ INTERVAL keep all archives within this time interval .TP -.B \-\-keep\-last\fP,\fB \-\-keep\-secondly +.B \-\-keep\-last\fP,\fB \-\-keep\-secondly number of secondly archives to keep .TP -.B \-\-keep\-minutely +.B \-\-keep\-minutely number of minutely archives to keep .TP -.B \-H\fP,\fB \-\-keep\-hourly +.B \-H\fP,\fB \-\-keep\-hourly number of hourly archives to keep .TP -.B \-d\fP,\fB \-\-keep\-daily +.B \-d\fP,\fB \-\-keep\-daily number of daily archives to keep .TP -.B \-w\fP,\fB \-\-keep\-weekly +.B \-w\fP,\fB \-\-keep\-weekly number of weekly archives to keep .TP -.B \-m\fP,\fB \-\-keep\-monthly +.B \-m\fP,\fB \-\-keep\-monthly number of monthly archives to keep .TP -.B \-y\fP,\fB \-\-keep\-yearly +.B \-y\fP,\fB \-\-keep\-yearly number of yearly archives to keep .TP -.B \-\-save\-space +.B \-\-save\-space work slower, but using less space .UNINDENT .SS Archive filters diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index ddc109112..4fc154b94 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-RECREATE 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-recreate \- Re-create archives . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-RECREATE" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-recreate \- Re-create archives .SH SYNOPSIS .sp borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...] @@ -99,16 +99,16 @@ paths to recreate; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-\-list +.B \-\-list output verbose list of items (files, dirs, ...) .TP .BI \-\-filter \ STATUSCHARS only display items with the given status characters (listed in borg create \-\-help) .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not change anything .TP -.B \-s\fP,\fB \-\-stats +.B \-s\fP,\fB \-\-stats print statistics at end .UNINDENT .SS Exclusion options @@ -121,18 +121,18 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP -.B \-\-exclude\-caches +.B \-\-exclude\-caches exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP) .TP .BI \-\-exclude\-if\-present \ NAME exclude directories that are tagged by containing a filesystem object with the given NAME .TP -.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files +.B \-\-keep\-exclude\-tags\fP,\fB \-\-keep\-tag\-files if tag objects are specified with \fB\-\-exclude\-if\-present\fP, don\(aqt omit the tag objects themselves from the backup archive .UNINDENT .SS Archive options diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index ed7fe0fb6..7aad272a5 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-RENAME 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-rename \- Rename an existing archive . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-RENAME" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-rename \- Rename an existing archive .SH SYNOPSIS .sp borg [common options] rename [options] ARCHIVE NEWNAME diff --git a/docs/man/borg-serve.1 b/docs/man/borg-serve.1 index 361fba792..3cce92a25 100644 --- a/docs/man/borg-serve.1 +++ b/docs/man/borg-serve.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-SERVE 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-serve \- Start in server mode. This command is usually not used manually. . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-SERVE" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-serve \- Start in server mode. This command is usually not used manually. .SH SYNOPSIS .sp borg [common options] serve [options] @@ -48,7 +48,7 @@ restrict repository access to PATH. Can be specified multiple times to allow the .BI \-\-restrict\-to\-repository \ PATH restrict repository access. Only the repository located at PATH (no sub\-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike \fB\-\-restrict\-to\-path\fP sub\-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there. .TP -.B \-\-append\-only +.B \-\-append\-only only allow appending to repository segment files .TP .BI \-\-storage\-quota \ QUOTA @@ -56,14 +56,19 @@ Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository .UNINDENT .SH EXAMPLES .sp -borg serve has special support for ssh forced commands (see \fBauthorized_keys\fP -example below): it will detect that you use such a forced command and extract -the value of the \fB\-\-restrict\-to\-path\fP option(s). -.sp -It will then parse the original command that came from the client, makes sure -that it is also \fBborg serve\fP and enforce path restriction(s) as given by the -forced command. That way, other options given by the client (like \fB\-\-info\fP or -\fB\-\-umask\fP) are preserved (and are not fixed by the forced command). +\fBborg serve\fP has special support for ssh forced commands (see \fBauthorized_keys\fP +example below): if the environment variable SSH_ORIGINAL_COMMAND is set it will +ignore some options given on the command line and use the values from the +variable instead. This only applies to a carefully controlled allowlist of safe +options. This list currently contains: +.INDENT 0.0 +.IP \(bu 2 +Options that control the log level and debug topics printed +such as \fB\-\-verbose\fP, \fB\-\-info\fP, \fB\-\-debug\fP, \fB\-\-debug\-topic\fP, etc. +.IP \(bu 2 +\fB\-\-lock\-wait\fP to allow the client to control how long to wait before +giving up and aborting the operation when another process is holding a lock. +.UNINDENT .sp Environment variables (such as BORG_HOSTNAME_IS_UNIQUE) contained in the original command sent by the client are \fInot\fP interpreted, but ignored. If BORG_XXX environment @@ -102,6 +107,8 @@ has been introduced in v7.2. We recommend to use in this case. .UNINDENT .UNINDENT +.sp +Details about sshd usage: \fI\%sshd(8)\fP .SS SSH Configuration .sp \fBborg serve\fP\(aqs pipes (\fBstdin\fP/\fBstdout\fP/\fBstderr\fP) are connected to the \fBsshd\fP process on the server side. In the event that the SSH connection between \fBborg serve\fP and the client is disconnected or stuck abnormally (for example, due to a network outage), it can take a long time for \fBsshd\fP to notice the client is disconnected. In the meantime, \fBsshd\fP continues running, and as a result so does the \fBborg serve\fP process holding the lock on the repository. This can cause subsequent \fBborg\fP operations on the remote repository to fail with the error: \fBFailed to create/acquire the lock\fP\&. diff --git a/docs/man/borg-umount.1 b/docs/man/borg-umount.1 index 218909881..2c51a56d0 100644 --- a/docs/man/borg-umount.1 +++ b/docs/man/borg-umount.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-UMOUNT 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-umount \- un-mount the FUSE filesystem . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-UMOUNT" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-umount \- un-mount the FUSE filesystem .SH SYNOPSIS .sp borg [common options] umount [options] MOUNTPOINT @@ -69,7 +69,7 @@ bin boot etc home lib lib64 lost+found media mnt opt root sbin srv tmp usr var $ borg umount /tmp/mymountpoint -# The experimental "versions view" merges all archives in the repository +# The "versions view" merges all archives in the repository # and provides a versioned view on files. $ borg mount \-o versions /path/to/repo /tmp/mymountpoint $ ls \-l /tmp/mymountpoint/home/user/doc.txt/ diff --git a/docs/man/borg-upgrade.1 b/docs/man/borg-upgrade.1 index 35866e25c..cac410d24 100644 --- a/docs/man/borg-upgrade.1 +++ b/docs/man/borg-upgrade.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-UPGRADE 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-upgrade \- upgrade a repository from a previous version . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-UPGRADE" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-upgrade \- upgrade a repository from a previous version .SH SYNOPSIS .sp borg [common options] upgrade [options] [REPOSITORY] @@ -134,19 +134,19 @@ path to the repository to be upgraded .SS optional arguments .INDENT 0.0 .TP -.B \-n\fP,\fB \-\-dry\-run +.B \-n\fP,\fB \-\-dry\-run do not change repository .TP -.B \-\-inplace +.B \-\-inplace rewrite repository in place, with no chance of going back to older versions of the repository. .TP -.B \-\-force +.B \-\-force Force upgrade .TP -.B \-\-tam +.B \-\-tam Enable manifest authentication (in key and cache) (Borg 1.0.9 and later). .TP -.B \-\-disable\-tam +.B \-\-disable\-tam Disable manifest authentication (in key and cache). .UNINDENT .SH EXAMPLES diff --git a/docs/man/borg-with-lock.1 b/docs/man/borg-with-lock.1 index b33387bbf..e71032403 100644 --- a/docs/man/borg-with-lock.1 +++ b/docs/man/borg-with-lock.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG-WITH-LOCK 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borg-with-lock \- run a user specified command with the repository lock held . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORG-WITH-LOCK" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borg-with-lock \- run a user specified command with the repository lock held .SH SYNOPSIS .sp borg [common options] with\-lock [options] REPOSITORY COMMAND [ARGS...] diff --git a/docs/man/borg.1 b/docs/man/borg.1 index 062c9823f..25d593be3 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORG 1 "2017-02-05" "" "borg backup tool" -.SH NAME -borg \- deduplicating and encrypting backup tool . .nr rst2man-indent-level 0 . @@ -30,10 +27,29 @@ 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 .. -.SH SYNOPSIS +.TH "" "" "" "" +.SH NAME + \- +.SH BORG +.SS deduplicating and encrypting backup tool +.INDENT 0.0 +.TP +.B Author +The Borg Collective +.TP +.B Date +2017\-02\-05 +.TP +.B Manual section +1 +.TP +.B Manual group +borg backup tool +.UNINDENT +.SS SYNOPSIS .sp borg [common options] [options] [arguments] -.SH DESCRIPTION +.SS DESCRIPTION .\" we don't include the README.rst here since we want to keep this terse. . .sp @@ -50,7 +66,7 @@ Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collec of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not distinguish archives from each other in any way other than their name, it does not matter when or where archives were created (e.g. different hosts). -.SH EXAMPLES +.SS EXAMPLES .SS A step\-by\-step example .INDENT 0.0 .IP 1. 3 @@ -185,7 +201,7 @@ reports during command execution. You can also add the \fB\-v\fP (or get other informational messages. .UNINDENT .UNINDENT -.SH NOTES +.SS NOTES .SS Positional Arguments and Options: Order matters .sp Borg only supports taking options (\fB\-s\fP and \fB\-\-progress\fP in the example) @@ -484,6 +500,11 @@ You might need this to run borg on WSL (Windows Subsystem for Linux) or in systemd.nspawn containers on some architectures (e.g. ARM). Using this does not affect data safety, but might result in a more bursty write to disk behaviour (not continuously streaming to disk). +.TP +.B retry_erofs +Retry opening a file without O_NOATIME if opening a file with O_NOATIME +caused EROFS. You will need this to make archives from volume shadow copies +in WSL1 (Windows Subsystem for Linux 1). .UNINDENT .UNINDENT .TP @@ -591,7 +612,8 @@ know a list of affected hardware. If you are suspicious whether your Borg repository is still consistent and readable after one of the failures mentioned above occurred, run \fBborg check \-\-verify\-data\fP to make sure it is consistent. -Requirements for Borg repository file systems.INDENT 0.0 +Requirements for Borg repository file systems +.INDENT 0.0 .IP \(bu 2 Long file names .IP \(bu 2 @@ -877,7 +899,7 @@ This includes resource forks on Mac OS X. .IP [7] 5 aka \fIBSD flags\fP\&. The Linux set of flags [1] is portable across platforms. The BSDs define additional flags. -.SH SEE ALSO +.SS SEE ALSO .sp \fIborg\-common(1)\fP for common command line options .sp @@ -900,7 +922,7 @@ GitHub \fI\%https://github.com/borgbackup/borg\fP .IP \(bu 2 Security contact \fI\%https://borgbackup.readthedocs.io/en/latest/support.html#security\-contact\fP .UNINDENT -.SH AUTHOR -The Borg Collective + +orphan: .\" Generated by docutils manpage writer. . diff --git a/docs/man/borgfs.1 b/docs/man/borgfs.1 index bd8e7210e..75ffacf2f 100644 --- a/docs/man/borgfs.1 +++ b/docs/man/borgfs.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH BORGFS 1 "2021-07-12" "" "borg backup tool" -.SH NAME -borgfs \- Mount archive or an entire repository as a FUSE filesystem . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "BORGFS" 1 "2022-06-04" "" "borg backup tool" +.SH NAME +borgfs \- Mount archive or an entire repository as a FUSE filesystem .SH SYNOPSIS .sp borgfs [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT [PATH...] @@ -49,6 +49,23 @@ To allow a regular user to use fstab entries, add the \fBuser\fP option: .sp For FUSE configuration and mount options, see the mount.fuse(8) manual page. .sp +Borg\(aqs default behavior is to use the archived user and group names of each +file and map them to the system\(aqs respective user and group ids. +Alternatively, using \fBnumeric\-ids\fP will instead use the archived user and +group ids without any mapping. +.sp +The \fBuid\fP and \fBgid\fP mount options (implemented by Borg) can be used to +override the user and group ids of all files (i.e., \fBborg mount \-o +uid=1000,gid=1000\fP). +.sp +The man page references \fBuser_id\fP and \fBgroup_id\fP mount options +(implemented by fuse) which specify the user and group id of the mount owner +(aka, the user who does the mounting). It is set automatically by libfuse (or +the filesystem if libfuse is not used). However, you should not specify these +manually. Unlike the \fBuid\fP and \fBgid\fP mount options which affect all files, +\fBuser_id\fP and \fBgroup_id\fP affect the user and group id of the mounted +(base) directory. +.sp Additional mount options supported by borg: .INDENT 0.0 .IP \(bu 2 @@ -93,13 +110,13 @@ paths to extract; patterns are supported .SS optional arguments .INDENT 0.0 .TP -.B \-V\fP,\fB \-\-version +.B \-V\fP,\fB \-\-version show version number and exit .TP -.B \-f\fP,\fB \-\-foreground +.B \-f\fP,\fB \-\-foreground stay in foreground, do not daemonize .TP -.B \-o +.B \-o Extra mount options .UNINDENT .SS Archive filters @@ -130,10 +147,10 @@ exclude paths matching PATTERN read exclude patterns from EXCLUDEFILE, one per line .TP .BI \-\-pattern \ PATTERN -experimental: include/exclude paths matching PATTERN +include/exclude paths matching PATTERN .TP .BI \-\-patterns\-from \ PATTERNFILE -experimental: read include/exclude patterns from PATTERNFILE, one per line +read include/exclude patterns from PATTERNFILE, one per line .TP .BI \-\-strip\-components \ NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index afce6c24d..7fbeb71bd 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -39,7 +39,7 @@ borg create +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--stdin-user USER`` | set user USER in archive for stdin data (default: 'root') | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'root') | + | | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'wheel') | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -53,9 +53,9 @@ borg create +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) | +-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -128,7 +128,7 @@ borg create --no-files-cache do not load/update the file metadata cache used to detect unchanged files --stdin-name NAME use NAME in archive for stdin data (default: "stdin") --stdin-user USER set user USER in archive for stdin data (default: 'root') - --stdin-group GROUP set group GROUP in archive for stdin data (default: 'root') + --stdin-group GROUP set group GROUP in archive for stdin data (default: 'wheel') --stdin-mode M set mode to M in archive for stdin data (default: 0660) @@ -138,8 +138,8 @@ borg create Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --exclude-caches exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) --exclude-if-present NAME exclude directories that are tagged by containing a filesystem object with the given NAME --keep-exclude-tags, --keep-tag-files if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive @@ -241,16 +241,15 @@ how much your repository will grow. Please note that the "All archives" stats re the state after creation. Also, the ``--stats`` and ``--dry-run`` options are mutually exclusive because the data is not actually compressed and deduplicated during a dry run. -See the output of the "borg help patterns" command for more help on exclude patterns. +For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. -See the output of the "borg help placeholders" command for more help on placeholders. +For more help on placeholders, see the :ref:`borg_placeholders` command output. .. man NOTES The ``--exclude`` patterns are not like tar. In tar ``--exclude`` .bundler/gems will exclude foo/.bundler/gems. In borg it will not, you need to use ``--exclude`` -'\*/.bundler/gems' to get the same effect. See ``borg help patterns`` for -more information. +'\*/.bundler/gems' to get the same effect. In addition to using ``--exclude`` patterns, it is possible to use ``--exclude-if-present`` to specify the name of a filesystem object (e.g. a file diff --git a/docs/usage/diff.rst.inc b/docs/usage/diff.rst.inc index c04887443..7ad3b210f 100644 --- a/docs/usage/diff.rst.inc +++ b/docs/usage/diff.rst.inc @@ -12,39 +12,39 @@ borg diff .. class:: borg-options-table - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | **positional arguments** | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``REPO::ARCHIVE1`` | repository location and ARCHIVE1 name | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``ARCHIVE2`` | ARCHIVE2 name (no repository location allowed) | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``PATH`` | paths of items inside the archives to compare; patterns are supported | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | **optional arguments** | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--numeric-owner`` | only consider numeric user and group identifiers | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--same-chunker-params`` | Override check of chunker parameters. | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--sort`` | Sort the output lines by file path. | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--json-lines`` | Format output as JSON Lines. | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | .. class:: borg-common-opt-ref | - | | - | :ref:`common_options` | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | **Exclusion options** | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | - +-------------------------------------------------------+---------------------------------------+----------------------------------------------------------------------------+ + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | **positional arguments** | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``REPO::ARCHIVE1`` | repository location and ARCHIVE1 name | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``ARCHIVE2`` | ARCHIVE2 name (no repository location allowed) | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``PATH`` | paths of items inside the archives to compare; patterns are supported | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | **optional arguments** | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--numeric-owner`` | only consider numeric user and group identifiers | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--same-chunker-params`` | Override check of chunker parameters. | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--sort`` | Sort the output lines by file path. | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--json-lines`` | Format output as JSON Lines. | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | .. class:: borg-common-opt-ref | + | | + | :ref:`common_options` | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | **Exclusion options** | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``-e PATTERN``, ``--exclude PATTERN`` | exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | + +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------+ .. raw:: html @@ -77,8 +77,8 @@ borg diff Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line Description @@ -99,4 +99,4 @@ If you did not create the archives with different chunker params, pass ``--same-chunker-params``. Note that the chunker params changed from Borg 0.xx to 1.0. -See the output of the "borg help patterns" command for more help on exclude patterns. \ No newline at end of file +For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. \ No newline at end of file diff --git a/docs/usage/export-tar.rst.inc b/docs/usage/export-tar.rst.inc index 9fa16e40b..4dd4c93a5 100644 --- a/docs/usage/export-tar.rst.inc +++ b/docs/usage/export-tar.rst.inc @@ -37,9 +37,9 @@ borg export-tar +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -73,8 +73,8 @@ borg export-tar Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --strip-components NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. @@ -110,7 +110,7 @@ By default the entire archive is extracted but a subset of files and directories can be selected by passing a list of ``PATHs`` as arguments. The file selection can further be restricted by using the ``--exclude`` option. -See the output of the "borg help patterns" command for more help on exclude patterns. +For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. ``--progress`` can be slower than no progress display, since it makes one additional pass over the archive metadata. \ No newline at end of file diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc index 141f68d08..082028e2d 100644 --- a/docs/usage/extract.rst.inc +++ b/docs/usage/extract.rst.inc @@ -47,9 +47,9 @@ borg extract +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ | | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. | +-------------------------------------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------------+ @@ -87,8 +87,8 @@ borg extract Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --strip-components NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. @@ -100,7 +100,7 @@ archive is extracted but a subset of files and directories can be selected by passing a list of ``PATHs`` as arguments. The file selection can further be restricted by using the ``--exclude`` option. -See the output of the "borg help patterns" command for more help on exclude patterns. +For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. 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, @@ -112,4 +112,8 @@ pass over the archive metadata. .. note:: Currently, extract always writes into the current working directory ("."), - so make sure you ``cd`` to the right place before calling ``borg extract``. \ No newline at end of file + so make sure you ``cd`` to the right place before calling ``borg extract``. + + When parent directories are not extracted (because of using file/directory selection + or any other reason), borg can not restore parent directories' metadata, e.g. owner, + group, permission, etc. \ No newline at end of file diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index 6dea4cbea..f8fd0a69d 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -24,10 +24,14 @@ patterns when matching archive content in commands like ``extract`` or ``mount``. Starting with Borg 1.2 this behaviour will be changed to accept both absolute and relative paths. +A directory exclusion pattern can end either with or without a slash ('/'). +If it ends with a slash, such as `some/path/`, the directory will be +included but not its content. If it does not end with a slash, such as +`some/path`, both the directory and content will be excluded. + File patterns support these styles: fnmatch, shell, regular expressions, path prefixes and path full-matches. By default, fnmatch is used for -``--exclude`` patterns and shell-style is used for the experimental -``--pattern`` option. +``--exclude`` patterns and shell-style is used for the ``--pattern`` option. If followed by a colon (':') the first two characters of a pattern are used as a style selector. Explicit style selection is necessary when a @@ -140,60 +144,85 @@ Examples:: EOF $ borg create --exclude-from exclude.txt backup / -.. container:: experimental +A more general and easier to use way to define filename matching patterns exists +with the ``--pattern`` and ``--patterns-from`` options. Using these, you may +specify the backup roots (starting points) and patterns for inclusion/exclusion. +A root path starts with the prefix `R`, followed by a path (a plain path, not a +file pattern). An include rule starts with the prefix +, an exclude rule starts +with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern. - A more general and easier to use way to define filename matching patterns exists - with the experimental ``--pattern`` and ``--patterns-from`` options. Using these, you - may specify the backup roots (starting points) and patterns for inclusion/exclusion. - A root path starts with the prefix `R`, followed by a path (a plain path, not a - file pattern). An include rule starts with the prefix +, an exclude rule starts - with the prefix -, an exclude-norecurse rule starts with !, all followed by a pattern. +.. note:: - .. note:: + Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion + of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and + ``--exclude-from`` ONLY excludes are defined. - Via ``--pattern`` or ``--patterns-from`` you can define BOTH inclusion and exclusion - of files using pattern prefixes ``+`` and ``-``. With ``--exclude`` and - ``--exclude-from`` ONLY excludes are defined. +Inclusion patterns are useful to include paths that are contained in an excluded +path. The first matching pattern is used so if an include pattern matches before +an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches +a directory, it won't recurse into it and won't discover any potential matches for +include rules below that directory. - Inclusion patterns are useful to include paths that are contained in an excluded - path. The first matching pattern is used so if an include pattern matches before - an exclude pattern, the file is backed up. If an exclude-norecurse pattern matches - a directory, it won't recurse into it and won't discover any potential matches for - include rules below that directory. +.. note:: - Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is - shell style (`sh:`), so those patterns behave similar to rsync include/exclude - patterns. The pattern style can be set via the `P` prefix. + It's possible that a sub-directory/file is matched while parent directories are not. + In that case, parent directories are not backed up thus their user, group, permission, + etc. can not be restored. - Patterns (``--pattern``) and excludes (``--exclude``) from the command line are - considered first (in the order of appearance). Then patterns from ``--patterns-from`` - are added. Exclusion patterns from ``--exclude-from`` files are appended last. +Note that the default pattern style for ``--pattern`` and ``--patterns-from`` is +shell style (`sh:`), so those patterns behave similar to rsync include/exclude +patterns. The pattern style can be set via the `P` prefix. - Examples:: +Patterns (``--pattern``) and excludes (``--exclude``) from the command line are +considered first (in the order of appearance). Then patterns from ``--patterns-from`` +are added. Exclusion patterns from ``--exclude-from`` files are appended last. - # backup pics, but not the ones from 2018, except the good ones: - # note: using = is essential to avoid cmdline argument parsing issues. - borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics +Examples:: - # use a file with patterns: - borg create --patterns-from patterns.lst repo::arch + # backup pics, but not the ones from 2018, except the good ones: + # note: using = is essential to avoid cmdline argument parsing issues. + borg create --pattern=+pics/2018/good --pattern=-pics/2018 repo::arch pics - The patterns.lst file could look like that:: + # use a file with patterns: + borg create --patterns-from patterns.lst repo::arch - # "sh:" pattern style is the default, so the following line is not needed: - P sh - R / - # can be rebuild - - /home/*/.cache - # they're downloads for a reason - - /home/*/Downloads - # susan is a nice person - # include susans home - + /home/susan - # don't backup the other home directories - - /home/* - # don't even look in /proc - ! /proc +The patterns.lst file could look like that:: + + # "sh:" pattern style is the default, so the following line is not needed: + P sh + R / + # can be rebuild + - /home/*/.cache + # they're downloads for a reason + - /home/*/Downloads + # susan is a nice person + # include susans home + + /home/susan + # also back up this exact file + + pf:/home/bobby/specialfile.txt + # don't backup the other home directories + - /home/* + # don't even look in /proc + ! /proc + +You can specify recursion roots either on the command line or in a patternfile:: + + # these two commands do the same thing + borg create --exclude /home/bobby/junk repo::arch /home/bobby /home/susan + borg create --patterns-from patternfile.lst repo::arch + +The patternfile:: + + # note that excludes use fm: by default and patternfiles use sh: by default. + # therefore, we need to specify fm: to have the same exact behavior. + P fm + R /home/bobby + R /home/susan + + - /home/bobby/junk + +This allows you to share the same patterns between multiple repositories +without needing to specify them on the command line. .. _borg_placeholders: diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc index a3e1e0d73..0e9a7d423 100644 --- a/docs/usage/init.rst.inc +++ b/docs/usage/init.rst.inc @@ -62,31 +62,41 @@ 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. It cannot be changed later. +Encryption mode TLDR +++++++++++++++++++++ -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. +The encryption mode can only be configured when creating a new repository - +you can neither configure it on a per-archive basis nor change the +encryption mode of an existing repository. -Borg relies on randomly generated key material and uses that for chunking, id -generation, encryption and authentication. The key material is encrypted using -the passphrase you give before it is stored on-disk. +Use ``repokey``:: -You need to be careful with the key / the passphrase: + borg init --encryption repokey /path/to/repo -If you want "passphrase-only" security, use one of the repokey modes. The -key will be stored inside the repository (in its "config" file). In above -mentioned attack scenario, the attacker will have the key (but not the -passphrase). +Or ``repokey-blake2`` depending on which is faster on your client machines (see below):: -If you want "passphrase and having-the-key" security, use one of the keyfile -modes. The key will be stored in your home directory (in .config/borg/keys). -In the attack scenario, the attacker who has just access to your repo won't -have the key (and also not the passphrase). + borg init --encryption repokey-blake2 /path/to/repo -Make a backup copy of the key file (keyfile mode) or repo config file -(repokey mode) and keep it at a safe place, so you still have the key in -case it gets corrupted or lost. Also keep the passphrase at a safe place. -The backup that is encrypted with that key won't help you with that, of course. +Borg will: + +1. Ask you to come up with a passphrase. +2. Create a borg key (which contains 3 random secrets. See :ref:`key_files`). +3. Encrypt the key with your passphrase. +4. Store the encrypted borg key inside the repository directory (in the repo config). + This is why it is essential to use a secure passphrase. +5. Encrypt and sign your backups to prevent anyone from reading or forging them unless they + have the key and know the passphrase. Make sure to keep a backup of + your key **outside** the repository - do not lock yourself out by + "leaving your keys inside your car" (see :ref:`borg_key_export`). + For remote backups the encryption is done locally - the remote machine + never sees your passphrase, your unencrypted key or your unencrypted files. + Chunking and id generation are also based on your key to improve + your privacy. +6. Use the key when extracting files to decrypt them and to verify that the contents of + the backups have not been accidentally or maliciously altered. + +Picking a passphrase +++++++++++++++++++++ Make sure you use a good passphrase. Not too short, not too simple. The real encryption / decryption key is encrypted with / locked by your passphrase. @@ -106,14 +116,22 @@ a different keyboard layout. You can change your passphrase for existing repos at any time, it won't affect the encryption/decryption key or other secrets. -Encryption modes -++++++++++++++++ +More encryption modes ++++++++++++++++++++++ -You can choose from the encryption modes seen in the table below on a per-repo -basis. The mode determines encryption algorithm, hash/MAC algorithm and also the -key storage location. +Only use ``--encryption none`` if you are OK with anyone who has access to +your repository being able to read your backups and tamper with their +contents without you noticing. -Example: `borg init --encryption repokey ...` +If you want "passphrase and having-the-key" security, use ``--encryption keyfile``. +The key will be stored in your home directory (in ``~/.config/borg/keys``). + +If you do **not** want to encrypt the contents of your backups, but still +want to detect malicious tampering use ``--encryption authenticated``. + +If ``BLAKE2b`` is faster than ``SHA-256`` on your hardware, use ``--encryption authenticated-blake2``, +``--encryption repokey-blake2`` or ``--encryption keyfile-blake2``. Note: for remote backups +the hashing is done on your local machine. .. nanorst: inline-fill diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc index a295138a1..e91b2dbee 100644 --- a/docs/usage/key_export.rst.inc +++ b/docs/usage/key_export.rst.inc @@ -76,4 +76,15 @@ data backup. For repositories using the repokey encryption the key is saved in the repository in the config file. A backup is thus not strictly needed, but guards against the repository becoming inaccessible if the file -is damaged for some reason. \ No newline at end of file +is damaged for some reason. + +Examples:: + + borg key export /path/to/repo > encrypted-key-backup + borg key export --paper /path/to/repo > encrypted-key-backup.txt + borg key export --qr-html /path/to/repo > encrypted-key-backup.html + # Or pass the output file as an argument instead of redirecting stdout: + borg key export /path/to/repo encrypted-key-backup + borg key export --paper /path/to/repo encrypted-key-backup.txt + borg key export --qr-html /path/to/repo encrypted-key-backup.html + diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc index 02195533b..54736bae0 100644 --- a/docs/usage/list.rst.inc +++ b/docs/usage/list.rst.inc @@ -23,7 +23,7 @@ borg list +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--short`` | only print file/directory names, nothing else | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--format FORMAT``, ``--list-format FORMAT`` | specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}") | + | | ``--format FORMAT``, ``--list-format FORMAT`` | specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}") | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--json`` | Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -51,9 +51,9 @@ borg list +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-----------------------------------------------------------------------------+-----------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. raw:: html @@ -74,7 +74,7 @@ borg list optional arguments --short only print file/directory names, nothing else - --format FORMAT, --list-format FORMAT specify format for file listing (default: "{mode} {user:6} {group:6} {size:8d} {mtime} {path}{extra}{NL}") + --format FORMAT, --list-format FORMAT specify format for file or archive listing (default for files: "{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}"; for archives: "{archive:<36} {time} [{id}]{NL}") --json Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available. --json-lines Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available. @@ -93,8 +93,8 @@ borg list Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line Description @@ -102,21 +102,50 @@ Description This command lists the contents of a repository or an archive. -See the "borg help patterns" command for more help on exclude patterns. +For more help on include/exclude patterns, see the :ref:`borg_patterns` command output. .. man NOTES -The following keys are available for ``--format``: +The FORMAT specifier syntax ++++++++++++++++++++++++++++ + +The ``--format`` option uses python's `format string syntax +`_. + +Examples: +:: + + $ borg list --format '{archive}{NL}' /path/to/repo + ArchiveFoo + ArchiveBar + ... + + # {VAR:NUMBER} - pad to NUMBER columns. + # Strings are left-aligned, numbers are right-aligned. + # Note: time columns except ``isomtime``, ``isoctime`` and ``isoatime`` cannot be padded. + $ borg list --format '{archive:36} {time} [{id}]{NL}' /path/to/repo + ArchiveFoo Thu, 2021-12-09 10:22:28 [0b8e9a312bef3f2f6e2d0fc110c196827786c15eba0188738e81697a7fa3b274] + $ borg list --format '{mode} {user:6} {group:6} {size:8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo + -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo + ... + + # {VAR:NUMBER} - pad to NUMBER columns right-aligned. + $ borg list --format '{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{extra}{NL}' /path/to/repo::ArchiveFoo + -rw-rw-r-- user user 1024 Thu, 2021-12-09 10:22:17 file-foo + ... + +The following keys are always available: - NEWLINE: OS dependent line separator - NL: alias of NEWLINE -- NUL: NUL character for creating print0 / xargs -0 like output, see barchive/bpath +- NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below - SPACE - TAB - CR - LF -Keys for listing repository archives: +Keys available only when listing archives in a repository: - archive: archive name interpreted as text (might be missing non-text characters, see barchive) - name: alias of "archive" @@ -128,12 +157,13 @@ Keys for listing repository archives: - start: time (start) of creation of the archive - time: alias of "start" - end: time (end) of creation of the archive +- command_line: command line which was used to create the archive - hostname: hostname of host on which this archive was created - username: username of user who created this archive -Keys for listing archive files: +Keys available only when listing files in an archive: - type - mode @@ -173,8 +203,6 @@ Keys for listing archive files: - sha3_384 - sha3_512 - sha512 -- shake_128 -- shake_256 - archiveid - archivename diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc index f813f5583..d1334ad8f 100644 --- a/docs/usage/mount.rst.inc +++ b/docs/usage/mount.rst.inc @@ -49,9 +49,9 @@ borg mount +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--strip-components NUMBER`` | Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. | +-----------------------------------------------------------------------------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -93,8 +93,8 @@ borg mount Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --strip-components NUMBER Remove the specified number of leading path elements. Paths with fewer elements will be silently skipped. @@ -115,6 +115,23 @@ To allow a regular user to use fstab entries, add the ``user`` option: For FUSE configuration and mount options, see the mount.fuse(8) manual page. +Borg's default behavior is to use the archived user and group names of each +file and map them to the system's respective user and group ids. +Alternatively, using ``numeric-ids`` will instead use the archived user and +group ids without any mapping. + +The ``uid`` and ``gid`` mount options (implemented by Borg) can be used to +override the user and group ids of all files (i.e., ``borg mount -o +uid=1000,gid=1000``). + +The man page references ``user_id`` and ``group_id`` mount options +(implemented by fuse) which specify the user and group id of the mount owner +(aka, the user who does the mounting). It is set automatically by libfuse (or +the filesystem if libfuse is not used). However, you should not specify these +manually. Unlike the ``uid`` and ``gid`` mount options which affect all files, +``user_id`` and ``group_id`` affect the user and group id of the mounted +(base) directory. + Additional mount options supported by borg: - versions: when used with a repository mount, this gives a merged, versioned diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index dc42e18a3..a1312da6d 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -100,6 +100,9 @@ Description The prune command prunes a repository by deleting all archives not matching any of the specified retention options. This command is normally used by automated backup scripts wanting to keep a certain number of historic backups. +This retention policy is commonly referred to as +`GFS `_ +(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 diff --git a/docs/usage/recreate.rst.inc b/docs/usage/recreate.rst.inc index 05dab0e2a..9e345d26a 100644 --- a/docs/usage/recreate.rst.inc +++ b/docs/usage/recreate.rst.inc @@ -39,9 +39,9 @@ borg recreate +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-from EXCLUDEFILE`` | read exclude patterns from EXCLUDEFILE, one per line | +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN | + | | ``--pattern PATTERN`` | include/exclude paths matching PATTERN | +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line | + | | ``--patterns-from PATTERNFILE`` | read include/exclude patterns from PATTERNFILE, one per line | +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) | +-------------------------------------------------------+---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -95,8 +95,8 @@ borg recreate Exclusion options -e PATTERN, --exclude PATTERN exclude paths matching PATTERN --exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line - --pattern PATTERN experimental: include/exclude paths matching PATTERN - --patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line + --pattern PATTERN include/exclude paths matching PATTERN + --patterns-from PATTERNFILE read include/exclude patterns from PATTERNFILE, one per line --exclude-caches exclude directories that contain a CACHEDIR.TAG file (http://www.bford.info/cachedir/spec.html) --exclude-if-present NAME exclude directories that are tagged by containing a filesystem object with the given NAME --keep-exclude-tags, --keep-tag-files if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive diff --git a/requirements.d/development.lock.txt b/requirements.d/development.lock.txt index 462afa577..1a2dd1185 100644 --- a/requirements.d/development.lock.txt +++ b/requirements.d/development.lock.txt @@ -7,5 +7,5 @@ pytest==6.1.2; python_version < '3.10' pytest-xdist==2.2.1 pytest-cov==2.12.1 pytest-benchmark==3.4.1 -Cython==0.29.27 +Cython==0.29.30 twine==1.15.0 diff --git a/src/borg/algorithms/xxh64/xxhash.h b/src/borg/algorithms/xxh64/xxhash.h index 08ab79457..511c4d12b 100644 --- a/src/borg/algorithms/xxh64/xxhash.h +++ b/src/borg/algorithms/xxh64/xxhash.h @@ -1546,8 +1546,7 @@ static void* XXH_memcpy(void* dest, const void* src, size_t size) /* note: use after variable declarations */ #ifndef XXH_STATIC_ASSERT # if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201112L) /* C11 */ -# include -# define XXH_STATIC_ASSERT_WITH_MESSAGE(c,m) do { static_assert((c),m); } while(0) +# define XXH_STATIC_ASSERT_WITH_MESSAGE(c,m) do { _Static_assert((c),m); } while(0) # elif defined(__cplusplus) && (__cplusplus >= 201103L) /* C++11 */ # define XXH_STATIC_ASSERT_WITH_MESSAGE(c,m) do { static_assert((c),m); } while(0) # else