diff options
33 files changed, 250 insertions, 109 deletions
diff --git a/docs/man/borg-benchmark-crud.1 b/docs/man/borg-benchmark-crud.1 index 06c1b21a0..58f4ab91b 100644 --- a/docs/man/borg-benchmark-crud.1 +++ b/docs/man/borg-benchmark-crud.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK-CRUD 1 "2017-11-25" "" "borg backup tool" +.TH BORG-BENCHMARK-CRUD 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives. . @@ -39,7 +39,7 @@ This command benchmarks borg CRUD (create, read, update, delete) operations. .sp It creates input data below the given PATH and backups this data into the given REPO. The REPO must already exist (it could be a fresh empty repo or an existing repo, the -command will create / read / update / delete some archives named borg\-test\-data* there. +command will create / read / update / delete some archives named borg\-benchmark\-crud* there. .sp Make sure you have free space there, you\(aqll need about 1GB each (+ overhead). .sp @@ -60,13 +60,7 @@ C\-R\- == random files. no dedup, measuring throughput through all processing st .B R\- == borg extract (extract archive, dry\-run, do everything, but do not write files to disk) R\-Z\- == all zero files. Measuring heavily duplicated files. R\-R\- == random files. No duplication here, measuring throughput through all processing -.IP "System Message: ERROR/3 (docs/virtmanpage.rst:, line 56)" -Unexpected indentation. -.INDENT 7.0 -.INDENT 3.5 stages, except writing to disk. -.UNINDENT -.UNINDENT .TP .B U\- == borg create (2nd archive creation of unchanged input files, measure files cache speed) The throughput value is kind of virtual here, it does not actually read the file. diff --git a/docs/man/borg-benchmark.1 b/docs/man/borg-benchmark.1 index c6d44204f..a0fb657dc 100644 --- a/docs/man/borg-benchmark.1 +++ b/docs/man/borg-benchmark.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BENCHMARK 1 "2017-11-25" "" "borg backup tool" +.TH BORG-BENCHMARK 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-benchmark \- benchmark command . diff --git a/docs/man/borg-break-lock.1 b/docs/man/borg-break-lock.1 index a6c93a2ca..64fffe06d 100644 --- a/docs/man/borg-break-lock.1 +++ b/docs/man/borg-break-lock.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-BREAK-LOCK 1 "2017-11-25" "" "borg backup tool" +.TH BORG-BREAK-LOCK 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg. . diff --git a/docs/man/borg-check.1 b/docs/man/borg-check.1 index 5a8660a27..176b6c176 100644 --- a/docs/man/borg-check.1 +++ b/docs/man/borg-check.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CHECK 1 "2017-11-25" "" "borg backup tool" +.TH BORG-CHECK 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-check \- Check repository consistency . diff --git a/docs/man/borg-common.1 b/docs/man/borg-common.1 index 229901608..4b8a22cc3 100644 --- a/docs/man/borg-common.1 +++ b/docs/man/borg-common.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMMON 1 "2017-11-25" "" "borg backup tool" +.TH BORG-COMMON 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-common \- Common options of Borg commands . @@ -83,6 +83,9 @@ treat part files like normal files (e.g. to list/extract them) .TP .BI \-\-debug\-profile \ FILE Write execution profile in Borg format into FILE. For local use a Python\-compatible file can be generated by suffixing FILE with ".pyprof". +.TP +.BI \-\-rsh \ RSH +Use this command to connect to the \(aqborg serve\(aq process (default: \(aqssh\(aq) .UNINDENT .SH SEE ALSO .sp diff --git a/docs/man/borg-compact.1 b/docs/man/borg-compact.1 index 5ecabf54c..46dde4d06 100644 --- a/docs/man/borg-compact.1 +++ b/docs/man/borg-compact.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMPACT 1 "2018-07-14" "" "borg backup tool" +.TH BORG-COMPACT 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-compact \- compact segment files in the repository . diff --git a/docs/man/borg-compression.1 b/docs/man/borg-compression.1 index c942a71a8..eb71d3734 100644 --- a/docs/man/borg-compression.1 +++ b/docs/man/borg-compression.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-COMPRESSION 1 "2017-11-25" "" "borg backup tool" +.TH BORG-COMPRESSION 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-compression \- Details regarding compression . @@ -50,7 +50,13 @@ Valid compression specifiers are: Do not compress. .TP .B lz4 -Use lz4 compression. High speed, low compression. (default) +Use lz4 compression. Very high speed, very low compression. (default) +.TP +.B zstd[,L] +Use zstd ("zstandard") compression, a modern wide\-range algorithm. +If you do not explicitly give the compression level L (ranging from 1 +to 22), it will use level 3. +Archives compressed with zstd are not compatible with borg < 1.1.4. .TP .B zlib[,L] Use zlib ("gz") compression. Medium speed, medium compression. @@ -82,6 +88,8 @@ Examples: .nf .ft C borg create \-\-compression lz4 REPO::ARCHIVE data +borg create \-\-compression zstd REPO::ARCHIVE data +borg create \-\-compression zstd,10 REPO::ARCHIVE data borg create \-\-compression zlib REPO::ARCHIVE data borg create \-\-compression zlib,1 REPO::ARCHIVE data borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data diff --git a/docs/man/borg-config.1 b/docs/man/borg-config.1 index 6019949e6..b1e9b73d6 100644 --- a/docs/man/borg-config.1 +++ b/docs/man/borg-config.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CONFIG 1 "2017-12-13" "" "borg backup tool" +.TH BORG-CONFIG 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-config \- get, set, and delete values in a repository or cache config file . @@ -32,16 +32,18 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg [common options] config [options] REPOSITORY NAME [VALUE] +borg [common options] config [options] REPOSITORY [NAME] [VALUE] .SH DESCRIPTION .sp This command gets and sets options in a local repository or cache config file. For security reasons, this command only works on local repositories. .sp -To delete a config value entirely, use \fB\-\-delete\fP\&. To get an existing key, pass -only the key name. To set a key, pass both the key name and the new value. Keys -can be specified in the format "section.name" or simply "name"; the section will -default to "repository" and "cache" for the repo and cache configs, respectively. +To delete a config value entirely, use \fB\-\-delete\fP\&. To list the values +of the configuration file or the default values, use \fB\-\-list\fP\&. To get and existing +key, pass only the key name. To set a key, pass both the key name and +the new value. Keys can be specified in the format "section.name" or +simply "name"; the section will default to "repository" and "cache" for +the repo and cache configs, respectively. .sp By default, borg config manipulates the repository config file. Using \fB\-\-cache\fP edits the repository cache\(aqs config file instead. @@ -68,6 +70,9 @@ get and set values from the repo cache .TP .B \-d\fP,\fB \-\-delete delete the key from the config file +.TP +.B \-l\fP,\fB \-\-list +list the configuration of the repo .UNINDENT .SH EXAMPLES .sp diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 71b766aed..b90a7d6f3 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-CREATE 1 "2017-11-25" "" "borg backup tool" +.TH BORG-CREATE 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-create \- Create new archive . @@ -149,8 +149,8 @@ output stats as JSON. Implies \fB\-\-stats\fP\&. .B \-\-no\-cache\-sync experimental: do not synchronize the cache. Implies not using the files cache. .TP -.B \-\-no\-files\-cache -do not load/update the file metadata cache used to detect unchanged files +.BI \-\-stdin\-name \ NAME +use NAME in archive for stdin data (default: "stdin") .UNINDENT .SS Exclusion options .INDENT 0.0 @@ -168,12 +168,12 @@ experimental: include/exclude paths matching PATTERN experimental: read include/exclude patterns from PATTERNFILE, one per line .TP .B \-\-exclude\-caches -exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP) +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 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 @@ -200,9 +200,6 @@ do not store birthtime (creation date) into archive .B \-\-nobsdflags do not read and store bsdflags (e.g. NODUMP, IMMUTABLE) into archive .TP -.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 @@ -222,7 +219,7 @@ manually specify the archive creation date/time (UTC, yyyy\-mm\-ddThh:mm:ss form write checkpoint every SECONDS seconds (Default: 1800) .TP .BI \-\-chunker\-params \ PARAMS -specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095 +specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 .TP .BI \-C \ COMPRESSION\fP,\fB \ \-\-compression \ COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details. @@ -252,7 +249,7 @@ $ borg create /path/to/repo::my\-files /home \e # Backup the root filesystem into an archive named "root\-YYYY\-MM\-DD" # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio) -$ borg create \-C zlib,6 /path/to/repo::root\-{now:%Y\-%m\-%d} / \-\-one\-file\-system +$ borg create \-C zlib,6 \-\-one\-file\-system /path/to/repo::root\-{now:%Y\-%m\-%d} / # Backup a remote host locally ("pull" style) using sshfs $ mkdir sshfs\-mount @@ -265,10 +262,10 @@ $ fusermount \-u sshfs\-mount # Make a big effort in fine granular deduplication (big chunk management # overhead, needs a lot of RAM and disk space, see formula in internals # docs \- same parameters as borg < 1.0 or attic): -$ borg create \-\-chunker\-params 10,23,16,4095 /path/to/repo::small /smallstuff +$ borg create \-\-chunker\-params buzhash,10,23,16,4095 /path/to/repo::small /smallstuff # Backup a raw device (must not be active/in use/mounted at that time) -$ dd if=/dev/sdx bs=10M | borg create /path/to/repo::my\-sdx \- +$ dd if=/dev/sdx bs=4M | borg create \-\-chunker\-params fixed,4194304 /path/to/repo::my\-sdx \- # No compression (none) $ borg create \-\-compression none /path/to/repo::arch ~ diff --git a/docs/man/borg-delete.1 b/docs/man/borg-delete.1 index 65c3a4e5e..13f7fc3d9 100644 --- a/docs/man/borg-delete.1 +++ b/docs/man/borg-delete.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DELETE 1 "2018-07-14" "" "borg backup tool" +.TH BORG-DELETE 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-delete \- Delete an existing repository or archives . diff --git a/docs/man/borg-diff.1 b/docs/man/borg-diff.1 index 77697f190..3e61c5584 100644 --- a/docs/man/borg-diff.1 +++ b/docs/man/borg-diff.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-DIFF 1 "2017-11-25" "" "borg backup tool" +.TH BORG-DIFF 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-diff \- Diff contents of two archives . @@ -32,12 +32,12 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH SYNOPSIS .sp -borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 [PATH...] +borg [common options] diff [options] REPO::ARCHIVE1 ARCHIVE2 [PATH...] .SH DESCRIPTION .sp This command finds differences (file contents, user/group/mode) between archives. .sp -A repository location and an archive name must be specified for REPO_ARCHIVE1. +A repository location and an archive name must be specified for REPO::ARCHIVE1. ARCHIVE2 is just another archive name in same repository (no repository location allowed). .sp @@ -57,7 +57,7 @@ See \fIborg\-common(1)\fP for common options of Borg commands. .SS arguments .INDENT 0.0 .TP -.B REPO_ARCHIVE1 +.B REPO::ARCHIVE1 repository location and ARCHIVE1 name .TP .B ARCHIVE2 diff --git a/docs/man/borg-export-tar.1 b/docs/man/borg-export-tar.1 index 770d2bafe..291b12f8c 100644 --- a/docs/man/borg-export-tar.1 +++ b/docs/man/borg-export-tar.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXPORT-TAR 1 "2017-11-25" "" "borg backup tool" +.TH BORG-EXPORT-TAR 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-export-tar \- Export archive contents as a tarball . @@ -127,11 +127,11 @@ $ borg export\-tar /path/to/repo::Monday Monday.tar $ borg export\-tar /path/to/repo::Monday Monday.tar.gz \-\-exclude \(aq*.so\(aq # use higher compression level with gzip -$ borg export\-tar testrepo::linux \-\-tar\-filter="gzip \-9" Monday.tar.gz +$ borg export\-tar \-\-tar\-filter="gzip \-9" testrepo::linux Monday.tar.gz -# export a gzipped tar, but instead of storing it on disk, +# export a tar, but instead of storing it on disk, # upload it to a remote site using curl. -$ borg export\-tar ... \-\-tar\-filter="gzip" \- | curl \-\-data\-binary @\- https://somewhere/to/POST +$ borg export\-tar /path/to/repo::Monday \- | curl \-\-data\-binary @\- https://somewhere/to/POST # remote extraction via "tarpipe" $ borg export\-tar /path/to/repo::Monday \- | ssh somewhere "cd extracted; tar x" diff --git a/docs/man/borg-extract.1 b/docs/man/borg-extract.1 index b11d737b3..5ac5fe251 100644 --- a/docs/man/borg-extract.1 +++ b/docs/man/borg-extract.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-EXTRACT 1 "2017-11-25" "" "borg backup tool" +.TH BORG-EXTRACT 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-extract \- Extract archive contents . diff --git a/docs/man/borg-info.1 b/docs/man/borg-info.1 index 726fed826..e2f098721 100644 --- a/docs/man/borg-info.1 +++ b/docs/man/borg-info.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INFO 1 "2017-11-25" "" "borg backup tool" +.TH BORG-INFO 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-info \- Show archive details such as disk space used . diff --git a/docs/man/borg-init.1 b/docs/man/borg-init.1 index 9c9c2e62d..f31e43a72 100644 --- a/docs/man/borg-init.1 +++ b/docs/man/borg-init.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-INIT 1 "2017-11-25" "" "borg backup tool" +.TH BORG-INIT 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-init \- Initialize an empty repository . @@ -182,10 +182,13 @@ repository to create select encryption key mode \fB(required)\fP .TP .B \-\-append\-only -create an append\-only mode repository +create an append\-only mode repository. Note that this only affects the low level structure of the repository, and running \fIdelete\fP or \fIprune\fP will still be allowed. See \fIappend_only_mode\fP in Additional Notes for more details. .TP .BI \-\-storage\-quota \ QUOTA Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota. +.TP +.B \-\-make\-parent\-dirs +create the parent directories of the repository directory, if they are missing. .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-key-change-passphrase.1 b/docs/man/borg-key-change-passphrase.1 index a94a06727..7fb9f05be 100644 --- a/docs/man/borg-key-change-passphrase.1 +++ b/docs/man/borg-key-change-passphrase.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2017-11-25" "" "borg backup tool" +.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-key-change-passphrase \- Change repository key file passphrase . diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index 0f5ec78a2..ea3df6c7c 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-EXPORT 1 "2017-11-25" "" "borg backup tool" +.TH BORG-KEY-EXPORT 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-key-export \- Export the repository key for backup . diff --git a/docs/man/borg-key-import.1 b/docs/man/borg-key-import.1 index 1bd11cf40..755b87fe1 100644 --- a/docs/man/borg-key-import.1 +++ b/docs/man/borg-key-import.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-IMPORT 1 "2017-11-25" "" "borg backup tool" +.TH BORG-KEY-IMPORT 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-key-import \- Import the repository key from backup . diff --git a/docs/man/borg-key-migrate-to-repokey.1 b/docs/man/borg-key-migrate-to-repokey.1 index 03f54d0bd..b38e13f4d 100644 --- a/docs/man/borg-key-migrate-to-repokey.1 +++ b/docs/man/borg-key-migrate-to-repokey.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2017-11-25" "" "borg backup tool" +.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-key-migrate-to-repokey \- Migrate passphrase -> repokey . diff --git a/docs/man/borg-key.1 b/docs/man/borg-key.1 index 88f54f178..96abba861 100644 --- a/docs/man/borg-key.1 +++ b/docs/man/borg-key.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-KEY 1 "2017-11-25" "" "borg backup tool" +.TH BORG-KEY 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-key \- Manage a keyfile or repokey of a repository . diff --git a/docs/man/borg-list.1 b/docs/man/borg-list.1 index c47e436f9..2ba06194b 100644 --- a/docs/man/borg-list.1 +++ b/docs/man/borg-list.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-LIST 1 "2017-11-25" "" "borg backup tool" +.TH BORG-LIST 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-list \- List archive or repository contents . @@ -169,6 +169,10 @@ start: time (start) of creation of the archive time: alias of "start" .IP \(bu 2 end: time (end) of creation of 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: diff --git a/docs/man/borg-mount.1 b/docs/man/borg-mount.1 index 6c4ac5954..cc36bed0d 100644 --- a/docs/man/borg-mount.1 +++ b/docs/man/borg-mount.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-MOUNT 1 "2017-11-25" "" "borg backup tool" +.TH BORG-MOUNT 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-mount \- Mount archive or an entire repository as a FUSE filesystem . @@ -47,8 +47,9 @@ used in fstab entries: To allow a regular user to use fstab entries, add the \fBuser\fP option: \fB/path/to/repo /mnt/point fuse.borgfs defaults,noauto,user 0 0\fP .sp -For mount options, see the fuse(8) manual page. Additional mount options -supported by borg: +For FUSE configuration and mount options, see the mount.fuse(8) manual page. +.sp +Additional mount options supported by borg: .INDENT 0.0 .IP \(bu 2 versions: when used with a repository mount, this gives a merged, versioned @@ -57,6 +58,10 @@ view of the files in the archives. EXPERIMENTAL, layout may change in future. allow_damaged_files: by default damaged files (where missing chunks were replaced with runs of zeros by borg check \fB\-\-repair\fP) are not readable and return EIO (I/O error). Set this option to read such files. +.IP \(bu 2 +ignore_permissions: for security reasons the "default_permissions" mount +option is internally enforced by borg. "ignore_permissions" can be given to +not enforce "default_permissions". .UNINDENT .sp The BORG_MOUNT_DATA_CACHE_ENTRIES environment variable is meant for advanced users diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1 index 82b347d05..02502516e 100644 --- a/docs/man/borg-patterns.1 +++ b/docs/man/borg-patterns.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PATTERNS 1 "2017-11-25" "" "borg backup tool" +.TH BORG-PATTERNS 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-patterns \- Details regarding patterns . @@ -32,6 +32,15 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .. .SH DESCRIPTION .sp +The path/filenames used as input for the pattern matching start from the +currently active recursion root. You usually give the recursion root(s) +when invoking borg and these can be either relative or absolute paths. +.sp +So, when you give \fIrelative/\fP as root, the paths going into the matcher +will look like \fIrelative/.../file.ext\fP\&. When you give \fI/absolute/\fP as root, +they will look like \fI/absolute/.../file.ext\fP\&. This is meant when we talk +about "full path" below. +.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 @@ -49,11 +58,11 @@ These patterns use a variant of shell pattern syntax, with \(aq*\(aq matching any number of characters, \(aq?\(aq matching any single character, \(aq[...]\(aq matching any single character specified, including ranges, and \(aq[!...]\(aq matching any character not specified. For the purpose of these patterns, -the path separator (\(aq\(aq for Windows and \(aq/\(aq on other systems) is not +the path separator (backslash for Windows and \(aq/\(aq on other systems) is not treated specially. Wrap meta\-characters in brackets for a literal match (i.e. \fI[?]\fP to match the literal character \fI?\fP). For a path -to match a pattern, it must completely match from start to end, or -must match from the start to just before a path separator. Except +to match a pattern, the full path must match, or it must match +from the start of the full path to just before a path separator. Except for the root path, paths will never end in the path separator when matching is attempted. Thus, if a given pattern ends in a path separator, a \(aq*\(aq is appended before matching is attempted. @@ -67,23 +76,23 @@ exception of any path separator. .TP .B Regular expressions, selector \fIre:\fP Regular expressions similar to those found in Perl are supported. Unlike -shell patterns regular expressions are not required to match the complete +shell patterns regular expressions are not required to match the full path and any substring match is sufficient. It is strongly recommended to anchor patterns to the start (\(aq^\(aq), to the end (\(aq$\(aq) or both. Path -separators (\(aq\(aq for Windows and \(aq/\(aq on other systems) in paths are +separators (backslash for Windows and \(aq/\(aq on other systems) in paths are always normalized to a forward slash (\(aq/\(aq) before applying a pattern. The regular expression syntax is described in the \fI\%Python documentation for the re module\fP\&. .TP .B Path prefix, selector \fIpp:\fP This pattern style is useful to match whole sub\-directories. The pattern -\fIpp:/data/bar\fP matches \fI/data/bar\fP and everything therein. +\fIpp:root/somedir\fP matches \fIroot/somedir\fP and everything therein. .TP .B Path full\-match, selector \fIpf:\fP -This pattern style is useful to match whole paths. +This pattern style is (only) useful to match full paths. This is kind of a pseudo pattern as it can not have any variable or -unspecified parts \- the full, precise path must be given. -\fIpf:/data/foo.txt\fP matches \fI/data/foo.txt\fP only. +unspecified parts \- the full path must be given. +\fIpf:root/file.ext\fP matches \fIroot/file.txt\fP only. .sp Implementation note: this is implemented via very time\-efficient O(1) hashtable lookups (this means you can have huge amounts of such patterns @@ -175,7 +184,24 @@ Patterns (\fB\-\-pattern\fP) and excludes (\fB\-\-exclude\fP) from the command l considered first (in the order of appearance). Then patterns from \fB\-\-patterns\-from\fP are added. Exclusion patterns from \fB\-\-exclude\-from\fP files are appended last. .sp -An example \fB\-\-patterns\-from\fP file could look like that: +Examples: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +# backup pics, but not the ones from 2018, except the good ones: +# note: using = is essential to avoid cmdline argument parsing issues. +borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics + +# use a file with patterns: +borg create \-\-patterns\-from patterns.lst repo::arch +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The patterns.lst file could look like that: .INDENT 0.0 .INDENT 3.5 .sp diff --git a/docs/man/borg-placeholders.1 b/docs/man/borg-placeholders.1 index 90a0ff22e..9dd8f1d6c 100644 --- a/docs/man/borg-placeholders.1 +++ b/docs/man/borg-placeholders.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PLACEHOLDERS 1 "2017-11-25" "" "borg backup tool" +.TH BORG-PLACEHOLDERS 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-placeholders \- Details regarding placeholders . @@ -42,7 +42,7 @@ The (short) hostname of the machine. .B {fqdn} The full name of the machine. .TP -.B {reverse-fqdn} +.B {reverse\-fqdn} The full name of the machine in reverse domain name notation. .TP .B {now} diff --git a/docs/man/borg-prune.1 b/docs/man/borg-prune.1 index e245963b2..6737ed8f8 100644 --- a/docs/man/borg-prune.1 +++ b/docs/man/borg-prune.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-PRUNE 1 "2018-07-14" "" "borg backup tool" +.TH BORG-PRUNE 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-prune \- Prune repository archives according to specified rules . diff --git a/docs/man/borg-recreate.1 b/docs/man/borg-recreate.1 index 8c6760598..e729a431a 100644 --- a/docs/man/borg-recreate.1 +++ b/docs/man/borg-recreate.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-RECREATE 1 "2018-07-14" "" "borg backup tool" +.TH BORG-RECREATE 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-recreate \- Re-create archives . @@ -126,12 +126,12 @@ experimental: include/exclude paths matching PATTERN experimental: read include/exclude patterns from PATTERNFILE, one per line .TP .B \-\-exclude\-caches -exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.brynosaurus.com/cachedir/spec.html\fP) +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 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 @@ -156,7 +156,7 @@ select compression algorithm, see the output of the "borg help compression" comm recompress data chunks according to \fB\-\-compression\fP\&. MODE \fIif\-different\fP: recompress if current compression is with a different compression algorithm (the level is not considered). MODE \fIalways\fP: recompress even if current compression is with the same compression algorithm (use this to change the compression level). MODE \fInever\fP (default): do not recompress. .TP .BI \-\-chunker\-params \ PARAMS -specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: 19,23,21,4095 +specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or \fIdefault\fP to use the current defaults. default: buzhash,19,23,21,4095 .UNINDENT .SH EXAMPLES .INDENT 0.0 diff --git a/docs/man/borg-rename.1 b/docs/man/borg-rename.1 index d82942e7f..a4c5d2ffc 100644 --- a/docs/man/borg-rename.1 +++ b/docs/man/borg-rename.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH BORG-RENAME 1 "2017-11-25" "" "borg backup tool" +.TH BORG-RENAME 1 "2019-02-24" "" "borg backup tool" .SH NAME borg-rename \- Rename an existing archive . |