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

Merge pull request #5555 from ThomasWaldmann/rel120b1

Browse source 
Release 1.2.0b1
This commit is contained in:
TW 2020-12-07 00:54:50 +01:00 committed by GitHub
commit c2118f16f1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
36 changed files with 276 additions and 121 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
docs/changes.rst
View file

@ -217,8 +217,8 @@ The best check that everything is ok is to run a dry-run extraction::
Changelog
=========
Version 1.2.0b1 (not released yet)
----------------------------------
Version 1.2.0b1 (2020-12-06)
----------------------------
Please note:
@ -277,11 +277,11 @@ Fixes:
New features:
- create: implement --paths-from-stdin and --paths-from-command, see #5492
- create: implement --paths-from-stdin and --paths-from-command, see #5492.
These switches read paths to archive from stdin. Delimiter can specified
by --paths-delimiter=DELIM. Paths read will be added honoring every
option but exclusion options and --one-file-system. Directories aren't
recursed into.
option but exclusion options and --one-file-system. borg won't recurse
into directories.
- 'obfuscate' pseudo compressor obfuscates compressed chunk size in repo
- add pyfuse3 (successor of llfuse) as an alternative lowlevel fuse
implementation to llfuse (deprecated), #5407.
@ -294,6 +294,7 @@ Other changes:
- split recursive directory walking/processing into directory walking and
item processing.
- fix warning by importing setuptools before distutils.
- debug info: include infos about FUSE implementation, #5546
- testing:
- add a test for the hashindex corruption bug, #5531 #4829

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BENCHMARK-CRUD 1 "2020-10-04" "" "borg backup tool"
.TH BORG-BENCHMARK-CRUD 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BENCHMARK 1 "2020-10-04" "" "borg backup tool"
.TH BORG-BENCHMARK 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-benchmark \- benchmark command
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-BREAK-LOCK 1 "2020-10-04" "" "borg backup tool"
.TH BORG-BREAK-LOCK 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CHECK 1 "2020-10-04" "" "borg backup tool"
.TH BORG-CHECK 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-check \- Check repository consistency
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMMON 1 "2020-10-04" "" "borg backup tool"
.TH BORG-COMMON 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-common \- Common options of Borg commands
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMPACT 1 "2020-10-04" "" "borg backup tool"
.TH BORG-COMPACT 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-compact \- compact segment files in the repository
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-COMPRESSION 1 "2020-10-04" "" "borg backup tool"
.TH BORG-COMPRESSION 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-compression \- Details regarding compression
.
@ -79,6 +79,32 @@ The heuristic tries with lz4 whether the data is compressible.
For incompressible data, it will not use compression (uses "none").
For compressible data, it uses the given C[,L] compression \- with C[,L]
being any valid compression specifier.
.TP
.B obfuscate,SPEC,C[,L]
Use compressed\-size obfuscation to make fingerprinting attacks based on
the observable stored chunk size more difficult.
Note:
\- you must combine this with encryption or it won\(aqt make any sense.
\- your repo size will be bigger, of course.
.sp
The SPEC value will determine how the size obfuscation will work:
.sp
Relative random reciprocal size variation:
Size will increase by a factor, relative to the compressed data size.
Smaller factors are often used, larger factors rarely.
1: factor 0.01 .. 100.0
2: factor 0.1 .. 1000.0
3: factor 1.0 .. 10000.0
4: factor 10.0 .. 100000.0
5: factor 100.0 .. 1000000.0
6: factor 1000.0 .. 10000000.0
.sp
Add a randomly sized padding up to the given size:
110: 1kiB
\&...
120: 1MiB
\&...
123: 8MiB (max.)
.UNINDENT
.sp
Examples:
@ -94,6 +120,9 @@ borg create \-\-compression zlib REPO::ARCHIVE data
borg create \-\-compression zlib,1 REPO::ARCHIVE data
borg create \-\-compression auto,lzma,6 REPO::ARCHIVE data
borg create \-\-compression auto,lzma ...
borg create \-\-compression obfuscate,3,none ...
borg create \-\-compression obfuscate,3,auto,zstd,10 ...
borg create \-\-compression obfuscate,2,zstd,6 ...
.ft P
.fi
.UNINDENT

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CONFIG 1 "2020-10-04" "" "borg backup tool"
.TH BORG-CONFIG 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-config \- get, set, and delete values in a repository or cache config file
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-CREATE 1 "2020-10-04" "" "borg backup tool"
.TH BORG-CREATE 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-create \- Create new archive
.
@ -94,6 +94,7 @@ ctime is a rather safe way to detect changes to a file (metadata and contents)
as it can not be set from userspace. But, a metadata\-only change will already
update the ctime, so there might be some unnecessary chunking/hashing even
without content changes. Some filesystems do not support ctime (change time).
E.g. doing a chown or chmod to a file will change its ctime.
.IP \(bu 2
mtime usually works and only updates if file contents were changed. But mtime
can be arbitrarily set from userspace, e.g. to set mtime back to the same value
@ -117,6 +118,7 @@ the state after creation. Also, the \fB\-\-stats\fP and \fB\-\-dry\-run\fP optio
exclusive because the data is not actually compressed and deduplicated during a dry run.
.sp
See the output of the "borg help patterns" command for more help on exclude patterns.
.sp
See the output of the "borg help placeholders" command for more help on placeholders.
.SH OPTIONS
.sp
@ -154,8 +156,26 @@ experimental: do not synchronize the cache. Implies not using the files cache.
.BI \-\-stdin\-name \ NAME
use NAME in archive for stdin data (default: \(aqstdin\(aq)
.TP
.BI \-\-stdin\-user \ USER
set user USER in archive for stdin data (default: \(aqroot\(aq)
.TP
.BI \-\-stdin\-group \ GROUP
set group GROUP in archive for stdin data (default: \(aqroot\(aq)
.TP
.BI \-\-stdin\-mode \ M
set mode to M in archive for stdin data (default: 0660)
.TP
.B \-\-content\-from\-command
interpret PATH as command and store its stdout. See also section Reading from stdin below.
.TP
.B \-\-paths\-from\-stdin
read DELIM\-separated list of paths to backup from stdin. Will not recurse into directories.
.TP
.B \-\-paths\-from\-command
interpret PATH as command and treat its output as \fB\-\-paths\-from\-stdin\fP
.TP
.BI \-\-paths\-delimiter \ DELIM
set path delimiter for \fB\-\-paths\-from\-stdin\fP and \fB\-\-paths\-from\-command\fP (default: n)
.UNINDENT
.SS Exclusion options
.INDENT 0.0
@ -188,7 +208,7 @@ exclude files flagged NODUMP
.INDENT 0.0
.TP
.B \-x\fP,\fB \-\-one\-file\-system
stay in the same file system and do not store mount points of other file systems
stay in the same file system and do not store mount points of other file systems. This might behave different from your expectations, see the docs.
.TP
.B \-\-numeric\-owner
only store numeric user and group identifiers
@ -327,6 +347,17 @@ all of its contents will be omitted from the backup. If, however, you wish to
only include the objects specified by \fB\-\-exclude\-if\-present\fP in your backup,
and not include any other contents of the containing folder, this can be enabled
through using the \fB\-\-keep\-exclude\-tags\fP option.
.sp
The \fB\-x\fP or \fB\-\-one\-file\-system\fP option excludes directories, that are mountpoints (and everything in them).
It detects mountpoints by comparing the device number from the output of \fBstat()\fP of the directory and its
parent directory. Specifically, it excludes directories for which \fBstat()\fP reports a device number different
from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
with device number different from their parent, which the kernel does not consider a mountpoint and also the
other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
using \fB\-\-one\-file\-system\fP, one should make doubly sure that the backup works as intended especially when using
btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
installer.
.SS Item flags
.sp
\fB\-\-list\fP outputs a list of all files, directories and other

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DELETE 1 "2020-10-04" "" "borg backup tool"
.TH BORG-DELETE 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-delete \- Delete an existing repository or archives
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-DIFF 1 "2020-10-04" "" "borg backup tool"
.TH BORG-DIFF 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-diff \- Diff contents of two archives
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXPORT-TAR 1 "2020-10-04" "" "borg backup tool"
.TH BORG-EXPORT-TAR 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-export-tar \- Export archive contents as a tarball
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-EXTRACT 1 "2020-10-04" "" "borg backup tool"
.TH BORG-EXTRACT 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-extract \- Extract archive contents
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INFO 1 "2020-10-04" "" "borg backup tool"
.TH BORG-INFO 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-info \- Show archive details such as disk space used
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-INIT 1 "2020-10-04" "" "borg backup tool"
.TH BORG-INIT 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-init \- Initialize an empty repository
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-10-04" "" "borg backup tool"
.TH BORG-KEY-CHANGE-PASSPHRASE 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-key-change-passphrase \- Change repository key file passphrase
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-EXPORT 1 "2020-10-04" "" "borg backup tool"
.TH BORG-KEY-EXPORT 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-key-export \- Export the repository key for backup
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-IMPORT 1 "2020-10-04" "" "borg backup tool"
.TH BORG-KEY-IMPORT 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-key-import \- Import the repository key from backup
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-10-04" "" "borg backup tool"
.TH BORG-KEY-MIGRATE-TO-REPOKEY 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-key-migrate-to-repokey \- Migrate passphrase -> repokey
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-KEY 1 "2020-10-04" "" "borg backup tool"
.TH BORG-KEY 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-key \- Manage a keyfile or repokey of a repository
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-LIST 1 "2020-10-04" "" "borg backup tool"
.TH BORG-LIST 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-list \- List archive or repository contents
.
@ -122,6 +122,13 @@ lrwxrwxrwx root root 0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdif
\-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
\&...
$ borg list /path/to/repo::root\-2016\-02\-15 \-\-pattern "\- bin/ba*"
drwxr\-xr\-x root root 0 Mon, 2016\-02\-15 17:44:27 .
drwxrwxr\-x root root 0 Mon, 2016\-02\-15 19:04:49 bin
lrwxrwxrwx root root 0 Fri, 2015\-03\-27 20:24:26 bin/bzcmp \-> bzdiff
\-rwxr\-xr\-x root root 2140 Fri, 2015\-03\-27 20:24:22 bin/bzdiff
\&...
$ borg list /path/to/repo::archiveA \-\-format="{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NEWLINE}"
drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 .
drwxrwxr\-x user user 0 Sun, 2015\-02\-01 11:00:00 code

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-MOUNT 1 "2020-10-04" "" "borg backup tool"
.TH BORG-MOUNT 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-mount \- Mount archive or an entire repository as a FUSE filesystem
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PATTERNS 1 "2020-10-04" "" "borg backup tool"
.TH BORG-PATTERNS 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-patterns \- Details regarding patterns
.
@ -173,6 +173,8 @@ $ cat >exclude.txt <<EOF
fm:aa:something/*
re:^home/[^/]\e.tmp/
sh:home/*/.thumbnails
# Example with spaces, no need to escape as it is processed by borg
some file with spaces.txt
EOF
$ borg create \-\-exclude\-from exclude.txt backup /
.ft P

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PLACEHOLDERS 1 "2020-10-04" "" "borg backup tool"
.TH BORG-PLACEHOLDERS 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-placeholders \- Details regarding placeholders
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-PRUNE 1 "2020-10-04" "" "borg backup tool"
.TH BORG-PRUNE 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-prune \- Prune repository archives according to specified rules
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RECREATE 1 "2020-10-04" "" "borg backup tool"
.TH BORG-RECREATE 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-recreate \- Re-create archives
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-RENAME 1 "2020-10-04" "" "borg backup tool"
.TH BORG-RENAME 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-rename \- Rename an existing archive
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-SERVE 1 "2020-10-04" "" "borg backup tool"
.TH BORG-SERVE 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-serve \- Start in server mode. This command is usually not used manually.
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UMOUNT 1 "2020-10-04" "" "borg backup tool"
.TH BORG-UMOUNT 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-umount \- un-mount the FUSE filesystem
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-UPGRADE 1 "2020-10-04" "" "borg backup tool"
.TH BORG-UPGRADE 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-upgrade \- upgrade a repository from a previous version
.

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

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG-WITH-LOCK 1 "2020-10-04" "" "borg backup tool"
.TH BORG-WITH-LOCK 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg-with-lock \- run a user specified command with the repository lock held
.

24
docs/man/borg.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORG 1 "2020-10-04" "" "borg backup tool"
.TH BORG 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borg \- deduplicating and encrypting backup tool
.
@ -441,6 +441,11 @@ the \fB\-\-rsh CMD\fP commandline option overrides the environment variable.
When set, use the given path as borg executable on the remote (defaults to "borg" if unset).
Using \fB\-\-remote\-path PATH\fP commandline option overrides the environment variable.
.TP
.B BORG_FILES_CACHE_SUFFIX
When set to a value at least one character long, instructs borg to use a specifically named
(based on the suffix) alternative files cache. This can be used to avoid loading and saving
cache entries for backup sources other than the current sources.
.TP
.B BORG_FILES_CACHE_TTL
When set to a numeric value, this determines the maximum "time to live" for the files cache
entries (default: 20). The files cache is used to quickly determine whether a file is unchanged.
@ -451,6 +456,23 @@ When set to no (default: yes), system information (like OS, Python version, ...)
exceptions is not shown.
Please only use for good reasons as it makes issues harder to analyze.
.TP
.B BORG_FUSE_IMPL
Choose the lowlevel FUSE implementation borg shall use for \fBborg mount\fP\&.
This is a comma\-separated list of implementation names, they are tried in the
given order, e.g.:
.INDENT 7.0
.IP \(bu 2
\fBpyfuse3,llfuse\fP: default, first try to load pyfuse3, then try to load llfuse.
.IP \(bu 2
\fBllfuse,pyfuse3\fP: first try to load llfuse, then try to load pyfuse3.
.IP \(bu 2
\fBpyfuse3\fP: only try to load pyfuse3
.IP \(bu 2
\fBllfuse\fP: only try to load llfuse
.IP \(bu 2
\fBnone\fP: do not try to load an implementation
.UNINDENT
.TP
.B BORG_WORKAROUNDS
A list of comma separated strings that trigger workarounds in borg,
e.g. to work around bugs in other software.

2
docs/man/borgfs.1
View file

@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH BORGFS 1 "2020-10-04" "" "borg backup tool"
.TH BORGFS 1 "2020-12-06" "" "borg backup tool"
.SH NAME
borgfs \- Mount archive or an entire repository as a FUSE filesystem
.

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

@ -12,87 +12,99 @@ borg create
.. class:: borg-options-table
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not create a backup archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the created archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters (see description) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | output stats as JSON. Implies ``--stats``. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--no-cache-sync`` | experimental: do not synchronize the cache. Implies not using the files cache. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| .. 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 |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-nodump`` | exclude files flagged NODUMP |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| **Filesystem options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-x``, ``--one-file-system`` | stay in the same file system and do not store mount points of other file systems |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--numeric-owner`` | only store numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noatime`` | do not store atime into archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--atime`` | do store atime into archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noctime`` | do not store ctime into archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--nobirthtime`` | do not store birthtime (creation date) into archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--nobsdflags`` | deprecated, use ``--noflags`` instead |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| **positional arguments** |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``ARCHIVE`` | name of archive to create (must be also a valid directory name) |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``PATH`` | paths to archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| **optional arguments** |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not create a backup archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics for the created archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--list`` | output verbose list of items (files, dirs, ...) |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--filter STATUSCHARS`` | only display items with the given status characters (see description) |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--json`` | output stats as JSON. Implies ``--stats``. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--no-cache-sync`` | experimental: do not synchronize the cache. Implies not using the files cache. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdin-name NAME`` | use NAME in archive for stdin data (default: 'stdin') |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdin-user USER`` | set user USER in archive for stdin data (default: 'root') |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdin-group GROUP`` | set group GROUP in archive for stdin data (default: 'root') |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--stdin-mode M`` | set mode to M in archive for stdin data (default: 0660) |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--content-from-command`` | interpret PATH as command and store its stdout. See also section Reading from stdin below. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-from-stdin`` | read DELIM-separated list of paths to backup from stdin. Will not recurse into directories. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--paths-delimiter DELIM`` | set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n) |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. 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 |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-nodump`` | exclude files flagged NODUMP |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Filesystem options** |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-x``, ``--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. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--numeric-owner`` | only store numeric user and group identifiers |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noatime`` | do not store atime into archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--atime`` | do store atime into archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noctime`` | do not store ctime into archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--nobirthtime`` | do not store birthtime (creation date) into archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--nobsdflags`` | deprecated, use ``--noflags`` instead |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--noflags`` | do not read and store flags (e.g. NODUMP, IMMUTABLE) into archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--files-cache MODE`` | operate files cache in MODE. default: ctime,size,inode |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive options** |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--comment COMMENT`` | add a comment text to the archive |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--timestamp TIMESTAMP`` | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). Alternatively, give a reference file/directory. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: buzhash,19,23,21,4095 |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-C COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-------------------------------------------------------+---------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
@ -118,7 +130,13 @@ borg create
--json output stats as JSON. Implies ``--stats``.
--no-cache-sync experimental: do not synchronize the cache. Implies not using the files cache.
--stdin-name NAME use NAME in archive for stdin data (default: 'stdin')
--stdin-user USER set user USER in archive for stdin data (default: 'root')
--stdin-group GROUP set group GROUP in archive for stdin data (default: 'root')
--stdin-mode M set mode to M in archive for stdin data (default: 0660)
--content-from-command interpret PATH as command and store its stdout. See also section Reading from stdin below.
--paths-from-stdin read DELIM-separated list of paths to backup from stdin. Will not recurse into directories.
--paths-from-command interpret PATH as command and treat its output as ``--paths-from-stdin``
--paths-delimiter DELIM set path delimiter for ``--paths-from-stdin`` and ``--paths-from-command`` (default: \n)
:ref:`common_options`
@ -136,7 +154,7 @@ borg create
Filesystem options
-x, --one-file-system stay in the same file system and do not store mount points of other file systems
-x, --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.
--numeric-owner only store numeric user and group identifiers
--noatime do not store atime into archive
--atime do store atime into archive
@ -209,6 +227,7 @@ ctime vs. mtime: safety vs. speed
as it can not be set from userspace. But, a metadata-only change will already
update the ctime, so there might be some unnecessary chunking/hashing even
without content changes. Some filesystems do not support ctime (change time).
E.g. doing a chown or chmod to a file will change its ctime.
- mtime usually works and only updates if file contents were changed. But mtime
can be arbitrarily set from userspace, e.g. to set mtime back to the same value
it had before a content change happened. This can be used maliciously as well as
@ -230,6 +249,7 @@ the state after creation. Also, the ``--stats`` and ``--dry-run`` options are mu
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.
See the output of the "borg help placeholders" command for more help on placeholders.
.. man NOTES
@ -248,6 +268,18 @@ only include the objects specified by ``--exclude-if-present`` in your backup,
and not include any other contents of the containing folder, this can be enabled
through using the ``--keep-exclude-tags`` option.
The ``-x`` or ``--one-file-system`` option excludes directories, that are mountpoints (and everything in them).
It detects mountpoints by comparing the device number from the output of ``stat()`` of the directory and its
parent directory. Specifically, it excludes directories for which ``stat()`` reports a device number different
from the device number of their parent. Be aware that in Linux (and possibly elsewhere) there are directories
with device number different from their parent, which the kernel does not consider a mountpoint and also the
other way around. Examples are bind mounts (possibly same device number, but always a mountpoint) and ALL
subvolumes of a btrfs (different device number from parent but not necessarily a mountpoint). Therefore when
using ``--one-file-system``, one should make doubly sure that the backup works as intended especially when using
btrfs. This is even more important, if the btrfs layout was created by someone else, e.g. a distribution
installer.
.. _list_item_flags:
Item flags

31
docs/usage/help.rst.inc
View file

@ -138,6 +138,8 @@ Examples::
fm:aa:something/*
re:^home/[^/]\.tmp/
sh:home/*/.thumbnails
# Example with spaces, no need to escape as it is processed by borg
some file with spaces.txt
EOF
$ borg create --exclude-from exclude.txt backup /
@ -313,6 +315,32 @@ auto,C[,L]
For compressible data, it uses the given C[,L] compression - with C[,L]
being any valid compression specifier.
obfuscate,SPEC,C[,L]
Use compressed-size obfuscation to make fingerprinting attacks based on
the observable stored chunk size more difficult.
Note:
- you must combine this with encryption or it won't make any sense.
- your repo size will be bigger, of course.
The SPEC value will determine how the size obfuscation will work:
Relative random reciprocal size variation:
Size will increase by a factor, relative to the compressed data size.
Smaller factors are often used, larger factors rarely.
1: factor 0.01 .. 100.0
2: factor 0.1 .. 1000.0
3: factor 1.0 .. 10000.0
4: factor 10.0 .. 100000.0
5: factor 100.0 .. 1000000.0
6: factor 1000.0 .. 10000000.0
Add a randomly sized padding up to the given size:
110: 1kiB
...
120: 1MiB
...
123: 8MiB (max.)
Examples::
borg create --compression lz4 REPO::ARCHIVE data
@ -322,4 +350,7 @@ Examples::
borg create --compression zlib,1 REPO::ARCHIVE data
borg create --compression auto,lzma,6 REPO::ARCHIVE data
borg create --compression auto,lzma ...
borg create --compression obfuscate,3,none ...
borg create --compression obfuscate,3,auto,zstd,10 ...
borg create --compression obfuscate,2,zstd,6 ...