From a85b64386626a469415171232ec50851a8e46cd3 Mon Sep 17 00:00:00 2001 From: Paul D Date: Thu, 29 Dec 2022 00:01:48 +0000 Subject: [PATCH] Docs grammar fixes. One cannot "to not x", but one can "not to x". Avoiding split infinitives gives the added bonus that machine translation yields better results. setup (n/adj) vs set(v) up. We don't "I setup it" but "I set it up". Likewise for login(n/adj) and log(v) in, backup(n/adj) and back(v) up. --- README.rst | 6 ++-- docs/changes_0.x.rst | 10 +++---- docs/changes_1.x.rst | 16 +++++----- docs/deployment/central-backup-server.rst | 6 ++-- docs/deployment/hosting-repositories.rst | 2 +- docs/deployment/image-backup.rst | 2 +- docs/deployment/pull-backup.rst | 2 +- docs/faq.rst | 36 +++++++++++------------ docs/internals/data-structures.rst | 8 ++--- docs/internals/security.rst | 2 +- docs/man/borg-create.1 | 22 +++++++------- docs/man/borg-key-export.1 | 2 +- docs/man/borg-rcreate.1 | 2 +- docs/man/borg.1 | 8 ++--- docs/man_intro.rst | 6 ++-- docs/quickstart.rst | 6 ++-- docs/quickstart_example.rst.inc | 2 +- docs/usage/create.rst | 20 ++++++------- docs/usage/create.rst.inc | 4 +-- docs/usage/general/resources.rst.inc | 2 +- docs/usage/help.rst.inc | 8 ++--- docs/usage/key_export.rst.inc | 2 +- docs/usage/notes.rst | 8 ++--- docs/usage/rcreate.rst.inc | 2 +- src/borg/archive.py | 2 +- src/borg/archiver/create_cmd.py | 2 +- src/borg/archiver/help_cmd.py | 8 ++--- src/borg/archiver/key_cmds.py | 2 +- src/borg/archiver/rcreate_cmd.py | 2 +- src/borg/archiver/rdelete_cmd.py | 2 +- src/borg/repository.py | 2 +- src/borg/testsuite/hashindex.py | 6 ++-- src/borg/testsuite/repository.py | 2 +- 33 files changed, 106 insertions(+), 106 deletions(-) diff --git a/README.rst b/README.rst index 229ef990..c814b58d 100644 --- a/README.rst +++ b/README.rst @@ -22,11 +22,11 @@ What is BorgBackup? BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption. -The main goal of Borg is to provide an efficient and secure way to backup data. +The main goal of Borg is to provide an efficient and secure way to back up data. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. -The authenticated encryption technique makes it suitable for backups to not -fully trusted targets. +The authenticated encryption technique makes it suitable for backups to targets not +fully trusted. See the `installation manual`_ or, if you have already downloaded Borg, ``docs/installation.rst`` to get started with Borg. diff --git a/docs/changes_0.x.rst b/docs/changes_0.x.rst index 52c0b035..9c36ed08 100644 --- a/docs/changes_0.x.rst +++ b/docs/changes_0.x.rst @@ -164,7 +164,7 @@ New features: - borg create --exclude-if-present TAGFILE - exclude directories that have the given file from the backup. You can additionally give --keep-tag-files to - preserve just the directory roots and the tag-files (but not backup other + preserve just the directory roots and the tag-files (but not back up other directory contents), #395, attic #128, attic #142 Other changes: @@ -419,7 +419,7 @@ Compatibility notes: Deprecations: - --compression N (with N being a number, as in 0.24) is deprecated. - We keep the --compression 0..9 for now to not break scripts, but it is + We keep the --compression 0..9 for now not to break scripts, but it is deprecated and will be removed later, so better fix your scripts now: --compression 0 (as in 0.24) is the same as --compression zlib,0 (now). BUT: if you do not want compression, you rather want --compression none @@ -434,7 +434,7 @@ New features: - create --compression lz4 (super-fast, but not very high compression) - create --compression zlib,N (slower, higher compression, default for N is 6) - create --compression lzma,N (slowest, highest compression, default N is 6) -- honor the nodump flag (UF_NODUMP) and do not backup such items +- honor the nodump flag (UF_NODUMP) and do not back up such items - list --short just outputs a simple list of the files/directories in an archive Bug fixes: @@ -541,7 +541,7 @@ Other changes: - update internals doc about chunker params, memory usage and compression - added docs about development - add some words about resource usage in general - - document how to backup a raw disk + - document how to back up a raw disk - add note about how to run borg from virtual env - add solutions for (ll)fuse installation problems - document what borg check does, fixes #138 @@ -617,7 +617,7 @@ New features: - FUSE: reflect deduplication in allocated blocks - only allow whitelisted RPC calls in server mode - normalize source/exclude paths before matching -- use posix_fadvise to not spoil the OS cache, fixes attic #252 +- use posix_fadvise not to spoil the OS cache, fixes attic #252 - toplevel error handler: show tracebacks for better error analysis - sigusr1 / sigint handler to print current file infos - attic PR #286 - RPCError: include the exception args we get from remote diff --git a/docs/changes_1.x.rst b/docs/changes_1.x.rst index 16aad68d..94ab1142 100644 --- a/docs/changes_1.x.rst +++ b/docs/changes_1.x.rst @@ -864,7 +864,7 @@ New features: - ability to use a system-provided version of "xxhash" - create: - - changed the default behaviour to not store the atime of fs items. atime is + - changed the default behaviour not to store the atime of fs items. atime is often rather not interesting and fragile - it easily changes even if nothing else has changed and, if stored into the archive, spoils deduplication of the archive metadata stream. @@ -1781,7 +1781,7 @@ Fixes: - security fix: configure FUSE with "default_permissions", #3903 "default_permissions" is now enforced by borg by default to let the kernel check uid/gid/mode based permissions. - "ignore_permissions" can be given to not enforce "default_permissions". + "ignore_permissions" can be given not to enforce "default_permissions". - make "hostname" short, even on misconfigured systems, #4262 - fix free space calculation on macOS (and others?), #4289 - config: quit with error message when no key is provided, #4223 @@ -2235,10 +2235,10 @@ Compatibility notes: - The deprecated --no-files-cache is not a global/common option any more, but only available for borg create (it is not needed for anything else). Use --files-cache=disabled instead of --no-files-cache. -- The nodump flag ("do not backup this file") is not honoured any more by +- The nodump flag ("do not back up this file") is not honoured any more by default because this functionality (esp. if it happened by error or unexpected) was rather confusing and unexplainable at first to users. - If you want that "do not backup NODUMP-flagged files" behaviour, use: + If you want that "do not back up NODUMP-flagged files" behaviour, use: borg create --exclude-nodump ... - If you are on Linux and do not need bsdflags archived, consider using ``--nobsdflags`` with ``borg create`` to avoid additional syscalls and @@ -3175,7 +3175,7 @@ Bug fixes: - security fix: configure FUSE with "default_permissions", #3903. "default_permissions" is now enforced by borg by default to let the kernel check uid/gid/mode based permissions. - "ignore_permissions" can be given to not enforce "default_permissions". + "ignore_permissions" can be given not to enforce "default_permissions". - xattrs: fix borg exception handling on ENOSPC error, #3808. New features: @@ -3478,7 +3478,7 @@ Other changes: - docs: - language clarification - VM backup FAQ - - borg create: document how to backup stdin, #2013 + - borg create: document how to back up stdin, #2013 - borg upgrade: fix incorrect title levels - add CVE numbers for issues fixed in 1.0.9, #2106 - fix typos (taken from Debian package patch) @@ -3674,7 +3674,7 @@ Bug fixes: New features: - add "borg key export" / "borg key import" commands, #1555, so users are able - to backup / restore their encryption keys more easily. + to back up / restore their encryption keys more easily. Supported formats are the keyfile format used by borg internally and a special "paper" format with by line checksums for printed backups. For the @@ -4161,7 +4161,7 @@ Bug fixes: - do not sleep for >60s while waiting for lock, #773 - unpack file stats before passing to FUSE - fix build on illumos -- don't try to backup doors or event ports (Solaris and derivatives) +- don't try to back up doors or event ports (Solaris and derivatives) - remove useless/misleading libc version display, #738 - test suite: reset exit code of persistent archiver, #844 - RemoteRepository: clean up pipe if remote open() fails diff --git a/docs/deployment/central-backup-server.rst b/docs/deployment/central-backup-server.rst index 047ca443..d9502587 100644 --- a/docs/deployment/central-backup-server.rst +++ b/docs/deployment/central-backup-server.rst @@ -4,7 +4,7 @@ Central repository server with Ansible or Salt ============================================== -This section will give an example how to setup a borg repository server for multiple +This section will give an example how to set up a borg repository server for multiple clients. Machines @@ -103,7 +103,7 @@ The server should automatically change the current working directory to the `.checkpoint`` -is saved every checkpoint interval (the default value for this is 30 +During a backup, a special checkpoint archive named ``.checkpoint`` +is saved at every checkpoint interval (the default value for this is 30 minutes) containing all the data backed-up until that point. This checkpoint archive is a valid archive, -but it is only a partial backup (not all files that you wanted to backup are +but it is only a partial backup (not all files that you wanted to back up are contained in it). Having it in the repo until a successful, full backup is completed is useful because it references all the transmitted chunks up to the checkpoint. This means that in case of an interruption, you only need to @@ -163,7 +163,7 @@ really desperate (e.g. if you have no completed backup of that file and you'ld rather get a partial file extracted than nothing). You do **not** want to give that option under any normal circumstances. -How can I backup huge file(s) over a unstable connection? +How can I back up huge file(s) over a unstable connection? --------------------------------------------------------- Yes. For more details, see :ref:`checkpoints_parts`. @@ -334,7 +334,7 @@ Assuming that all your chunks have a size of :math:`2^{21}` bytes (approximately and we have a "perfect" hash algorithm, we can think that the probability of collision would be of :math:`p^2/2^{n+1}` then, using SHA-256 (:math:`n=256`) and for example we have 1000 million chunks (:math:`p=10^9`) (1000 million chunks would be about 2100TB). -The probability would be around to 0.0000000000000000000000000000000000000000000000000000000000043. +The probability would be around 0.0000000000000000000000000000000000000000000000000000000000043. A mass-murderer space rock happens about once every 30 million years on average. This leads to a probability of such an event occurring in the next second to about :math:`10^{-15}`. @@ -342,9 +342,9 @@ That's **45** orders of magnitude more probable than the SHA-256 collision. Brie if you find SHA-256 collisions scary then your priorities are wrong. This example was grabbed from `this SO answer `_, it's great honestly. -Still, the real question is if Borg tries to not make this happen? +Still, the real question is if Borg tries not to make this happen? -Well... it used to not check anything but there was a feature added which saves the size +Well... previously it did not check anything until there was a feature added which saves the size of the chunks too, so the size of the chunks is compared to the size that you got with the hash and if the check says there is a mismatch it will raise an exception instead of corrupting the file. This doesn't save us from everything but reduces the chances of corruption. @@ -364,7 +364,7 @@ How do I configure different prune policies for different directories? ---------------------------------------------------------------------- Say you want to prune ``/var/log`` faster than the rest of -``/``. How do we implement that? The answer is to backup to different +``/``. How do we implement that? The answer is to back up to different archive *names* and then implement different prune policies for different prefixes. For example, you could have a script that does:: @@ -489,7 +489,7 @@ Using keyfile-based encryption with a blank passphrase Using ``BORG_PASSCOMMAND`` with macOS Keychain macOS has a native manager for secrets (such as passphrases) which is safer than just using a file as it is encrypted at rest and unlocked manually - (fortunately, the login keyring automatically unlocks when you login). With + (fortunately, the login keyring automatically unlocks when you log in). With the built-in ``security`` command, you can access it from the command line, making it useful for ``BORG_PASSCOMMAND``. @@ -567,7 +567,7 @@ otherwise make unavailable) all your backups. How can I protect against a hacked backup client? ------------------------------------------------- -Assume you backup your backup client machine C to the backup server S and +Assume you back up your backup client machine C to the backup server S and C gets hacked. In a simple push setup, the attacker could then use borg on C to delete all backups residing on S. @@ -738,13 +738,13 @@ This has some pros and cons, though: The long term plan to improve this is called "borgception", see :issue:`474`. -Can I backup my root partition (/) with Borg? +Can I back up my root partition (/) with Borg? --------------------------------------------- Backing up your entire root partition works just fine, but remember to -exclude directories that make no sense to backup, such as /dev, /proc, +exclude directories that make no sense to back up, such as /dev, /proc, /sys, /tmp and /run, and to use ``--one-file-system`` if you only want to -backup the root partition (and not any mounted devices e.g.). +back up the root partition (and not any mounted devices e.g.). If it crashes with a UnicodeError, what can I do? ------------------------------------------------- @@ -955,7 +955,7 @@ Another possible reason is that files don't always have the same path, for example if you mount a filesystem without stable mount points for each backup or if you are running the backup from a filesystem snapshot whose name is not stable. If the directory where you mount a filesystem is different every time, -Borg assumes they are different files. This is true even if you backup these +Borg assumes they are different files. This is true even if you back up these files with relative pathnames - borg uses full pathnames in files cache regardless. It is possible for some filesystems, such as ``mergerfs`` or network filesystems, @@ -1006,7 +1006,7 @@ How can I avoid unwanted base directories getting stored into archives? Possible use cases: -- Another file system is mounted and you want to backup it with original paths. +- Another file system is mounted and you want to back it up with original paths. - You have created a BTRFS snapshot in a ``/.snapshots`` directory for backup. To achieve this, run ``borg create`` within the mountpoint/snapshot directory: diff --git a/docs/internals/data-structures.rst b/docs/internals/data-structures.rst index fc3ba97c..eb961fcf 100644 --- a/docs/internals/data-structures.rst +++ b/docs/internals/data-structures.rst @@ -161,7 +161,7 @@ This new, more complex repo v2 object format was implemented to be able to effic query the metadata without having to read, transfer and decrypt the (usually much bigger) data part. -The metadata is encrypted to not disclose potentially sensitive information that could be +The metadata is encrypted not to disclose potentially sensitive information that could be used for e.g. fingerprinting attacks. The compression `ctype` and `clevel` is explained in :ref:`data-compression`. @@ -688,7 +688,7 @@ To determine whether a file has not changed, cached values are looked up via the key in the mapping and compared to the current file attribute values. If the file's size, timestamp and inode number is still the same, it is -considered to not have changed. In that case, we check that all file content +considered not to have changed. In that case, we check that all file content chunks are (still) present in the repository (we check that via the chunks cache). @@ -818,7 +818,7 @@ bucket is reached. This particular mode of operation is open addressing with linear probing. When the hash table is filled to 75%, its size is grown. When it's -emptied to 25%, its size is shrinked. Operations on it have a variable +emptied to 25%, its size is shrunken. Operations on it have a variable complexity between constant and linear with low factor, and memory overhead varies between 33% and 300%. @@ -1013,7 +1013,7 @@ while doing no compression at all (none) is a operation that takes no time, it likely will need to store more data to the storage compared to using lz4. The time needed to transfer and store the additional data might be much more than if you had used lz4 (which is super fast, but still might compress your -data about 2:1). This is assuming your data is compressible (if you backup +data about 2:1). This is assuming your data is compressible (if you back up already compressed data, trying to compress them at backup time is usually pointless). diff --git a/docs/internals/security.rst b/docs/internals/security.rst index b719ffba..a3f66d90 100644 --- a/docs/internals/security.rst +++ b/docs/internals/security.rst @@ -60,7 +60,7 @@ In other words, the object ID itself only authenticates the plaintext of the object and not its context or meaning. The latter is established by a different object referring to an object ID, thereby assigning a particular meaning to an object. For example, an archive item contains a list of object IDs that -represent packed file metadata. On their own it's not clear that these objects +represent packed file metadata. On their own, it's not clear that these objects would represent what they do, but by the archive item referring to them in a particular part of its own data structure assigns this meaning. diff --git a/docs/man/borg-create.1 b/docs/man/borg-create.1 index 5bd06bf0..ec213df3 100644 --- a/docs/man/borg-create.1 +++ b/docs/man/borg-create.1 @@ -169,7 +169,7 @@ set mode to M in archive for stdin data (default: 0660) 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. +read DELIM\-separated list of paths to back up 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 @@ -264,30 +264,30 @@ select compression algorithm, see the output of the \(dqborg help compression\(d .sp .nf .ft C -# Backup ~/Documents into an archive named \(dqmy\-documents\(dq +# Back up ~/Documents into an archive named \(dqmy\-documents\(dq $ borg create my\-documents ~/Documents # same, but list all files as we process them $ borg create \-\-list my\-documents ~/Documents -# Backup ~/Documents and ~/src but exclude pyc files +# Back up ~/Documents and ~/src but exclude pyc files $ borg create my\-files \e ~/Documents \e ~/src \e \-\-exclude \(aq*.pyc\(aq -# Backup home directories excluding image thumbnails (i.e. only +# Back up home directories excluding image thumbnails (i.e. only # /home//.thumbnails is excluded, not /home/*/*/.thumbnails etc.) $ borg create my\-files /home \-\-exclude \(aqsh:home/*/.thumbnails\(aq -# Backup the root filesystem into an archive named \(dqroot\-YYYY\-MM\-DD\(dq +# Back up the root filesystem into an archive named \(dqroot\-YYYY\-MM\-DD\(dq # use zlib compression (good, but slow) \- default is lz4 (fast, low compression ratio) $ borg create \-C zlib,6 \-\-one\-file\-system root\-{now:%Y\-%m\-%d} / -# Backup into an archive name like FQDN\-root\-TIMESTAMP +# Back up into an archive name like FQDN\-root\-TIMESTAMP $ borg create \(aq{fqdn}\-root\-{now}\(aq / -# Backup a remote host locally (\(dqpull\(dq style) using sshfs +# Back up a remote host locally (\(dqpull\(dq style) using sshfs $ mkdir sshfs\-mount $ sshfs root@example.com:/ sshfs\-mount $ cd sshfs\-mount @@ -300,10 +300,10 @@ $ fusermount \-u sshfs\-mount # docs \- same parameters as borg < 1.0): $ borg create \-\-chunker\-params buzhash,10,23,16,4095 small /smallstuff -# Backup a raw device (must not be active/in use/mounted at that time) +# Back up a raw device (must not be active/in use/mounted at that time) $ borg create \-\-read\-special \-\-chunker\-params fixed,4194304 my\-sdx /dev/sdX -# Backup a sparse disk image (must not be active/in use/mounted at that time) +# Back up a sparse disk image (must not be active/in use/mounted at that time) $ borg create \-\-sparse \-\-chunker\-params fixed,4194304 my\-disk my\-disk.raw # No compression (none) @@ -334,9 +334,9 @@ $ cd /home/user/Documents $ borg create \(aqdaily\-projectA\-{now:%Y\-%m\-%d}\(aq projectA # Use external command to determine files to archive -# Use \-\-paths\-from\-stdin with find to only backup files less than 1MB in size +# Use \-\-paths\-from\-stdin with find to back up only files less than 1MB in size $ find ~ \-size \-1000k | borg create \-\-paths\-from\-stdin small\-files\-only -# Use \-\-paths\-from\-command with find to only backup files from a given user +# Use \-\-paths\-from\-command with find to back up files only from a given user $ borg create \-\-paths\-from\-command joes\-files \-\- find /srv/samba/shared \-user joe # Use \-\-paths\-from\-stdin with \-\-paths\-delimiter (for example, for filenames with newlines in them) $ find ~ \-size \-1000k \-print0 | borg create \e diff --git a/docs/man/borg-key-export.1 b/docs/man/borg-key-export.1 index c6169013..d16feaa1 100644 --- a/docs/man/borg-key-export.1 +++ b/docs/man/borg-key-export.1 @@ -36,7 +36,7 @@ borg [common options] key export [options] [PATH] .SH DESCRIPTION .sp If repository encryption is used, the repository is inaccessible -without the key. This command allows one to backup this essential key. +without the key. This command allows one to back up this essential key. Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase. diff --git a/docs/man/borg-rcreate.1 b/docs/man/borg-rcreate.1 index 8d89cca6..d982fb93 100644 --- a/docs/man/borg-rcreate.1 +++ b/docs/man/borg-rcreate.1 @@ -205,7 +205,7 @@ _ .\" nanorst: inline-replace . .sp -\fInone\fP mode uses no encryption and no authentication. You\(aqre advised to NOT use this mode +\fInone\fP mode uses no encryption and no authentication. You\(aqre advised NOT to use this mode as it would expose you to all sorts of issues (DoS, confidentiality, tampering, ...) in case of malicious activity in the repository. .sp diff --git a/docs/man/borg.1 b/docs/man/borg.1 index c00a3b03..72008218 100644 --- a/docs/man/borg.1 +++ b/docs/man/borg.1 @@ -40,11 +40,11 @@ borg [common options] [options] [arguments] BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption. .sp -The main goal of Borg is to provide an efficient and secure way to backup data. +The main goal of Borg is to provide an efficient and secure way to back up data. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. -The authenticated encryption technique makes it suitable for backups to not -fully trusted targets. +The authenticated encryption technique makes it suitable for backups to targets not +fully trusted. .sp Borg stores a set of files in an \fIarchive\fP\&. A \fIrepository\fP is a collection of \fIarchives\fP\&. The format of repositories is Borg\-specific. Borg does not @@ -737,7 +737,7 @@ If your repository is remote, all deduplicated (and optionally compressed/ encrypted) data of course has to go over the connection (\fBssh://\fP repo url). If you use a locally mounted network filesystem, additionally some copy operations used for transaction support also go over the connection. If -you backup multiple sources to one target repository, additional traffic +you back up multiple sources to one target repository, additional traffic happens for cache resynchronization. .UNINDENT .SS Support for file metadata diff --git a/docs/man_intro.rst b/docs/man_intro.rst index 0a072f62..38c7dc66 100644 --- a/docs/man_intro.rst +++ b/docs/man_intro.rst @@ -13,11 +13,11 @@ DESCRIPTION BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption. -The main goal of Borg is to provide an efficient and secure way to backup data. +The main goal of Borg is to provide an efficient and secure way to back data up. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. -The authenticated encryption technique makes it suitable for backups to not -fully trusted targets. +The authenticated encryption technique makes it suitable for backups to targets not +fully trusted. Borg stores a set of files in an *archive*. A *repository* is a collection of *archives*. The format of repositories is Borg-specific. Borg does not diff --git a/docs/quickstart.rst b/docs/quickstart.rst index de9d501a..dbfbc6ed 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -74,7 +74,7 @@ Important note about permissions To avoid permissions issues (in your borg repository or borg cache), **always access the repository using the same user account**. -If you want to backup files of other users or the operating system, running +If you want to back up files of other users or the operating system, running borg as root likely will be required (otherwise you'ld get `Permission denied` errors). If you only back up your own files, you neither need nor want to run borg as @@ -123,7 +123,7 @@ works well enough without further care for consistency. Log files and caches might not be in a perfect state, but this is rarely a problem. For databases, virtual machines, and containers, there are specific -techniques for backing them up that do not simply use Borg to backup +techniques for backing them up that do not simply use Borg to back up the underlying filesystem. For databases, check your database documentation for techniques that will save the database state between transactions. For virtual machines, consider running the backup on @@ -171,7 +171,7 @@ backed up and that the ``prune`` command is keeping and deleting the correct bac info "Starting backup" - # Backup the most important directories into an archive named after + # Back up the most important directories into an archive named after # the machine this script is currently running on: borg create \ diff --git a/docs/quickstart_example.rst.inc b/docs/quickstart_example.rst.inc index 2299483a..12aff3d7 100644 --- a/docs/quickstart_example.rst.inc +++ b/docs/quickstart_example.rst.inc @@ -2,7 +2,7 @@ $ borg -r /path/to/repo rcreate --encryption=repokey-aes-ocb -2. Backup the ``~/src`` and ``~/Documents`` directories into an archive called +2. Back up the ``~/src`` and ``~/Documents`` directories into an archive called *Monday*:: $ borg -r /path/to/repo create Monday ~/src ~/Documents diff --git a/docs/usage/create.rst b/docs/usage/create.rst index b4b978a3..b697218a 100644 --- a/docs/usage/create.rst +++ b/docs/usage/create.rst @@ -4,30 +4,30 @@ Examples ~~~~~~~~ :: - # Backup ~/Documents into an archive named "my-documents" + # Back up ~/Documents into an archive named "my-documents" $ borg create my-documents ~/Documents # same, but list all files as we process them $ borg create --list my-documents ~/Documents - # Backup ~/Documents and ~/src but exclude pyc files + # Back up ~/Documents and ~/src but exclude pyc files $ borg create my-files \ ~/Documents \ ~/src \ --exclude '*.pyc' - # Backup home directories excluding image thumbnails (i.e. only + # Back up home directories excluding image thumbnails (i.e. only # /home//.thumbnails is excluded, not /home/*/*/.thumbnails etc.) $ borg create my-files /home --exclude 'sh:home/*/.thumbnails' - # Backup the root filesystem into an archive named "root-YYYY-MM-DD" + # Back up 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 --one-file-system root-{now:%Y-%m-%d} / - # Backup into an archive name like FQDN-root-TIMESTAMP + # Back up into an archive name like FQDN-root-TIMESTAMP $ borg create '{fqdn}-root-{now}' / - # Backup a remote host locally ("pull" style) using sshfs + # Back up a remote host locally ("pull" style) using sshfs $ mkdir sshfs-mount $ sshfs root@example.com:/ sshfs-mount $ cd sshfs-mount @@ -40,10 +40,10 @@ Examples # docs - same parameters as borg < 1.0): $ borg create --chunker-params buzhash,10,23,16,4095 small /smallstuff - # Backup a raw device (must not be active/in use/mounted at that time) + # Back up a raw device (must not be active/in use/mounted at that time) $ borg create --read-special --chunker-params fixed,4194304 my-sdx /dev/sdX - # Backup a sparse disk image (must not be active/in use/mounted at that time) + # Back up a sparse disk image (must not be active/in use/mounted at that time) $ borg create --sparse --chunker-params fixed,4194304 my-disk my-disk.raw # No compression (none) @@ -74,9 +74,9 @@ Examples $ borg create 'daily-projectA-{now:%Y-%m-%d}' projectA # Use external command to determine files to archive - # Use --paths-from-stdin with find to only backup files less than 1MB in size + # Use --paths-from-stdin with find to back up only files less than 1MB in size $ find ~ -size -1000k | borg create --paths-from-stdin small-files-only - # Use --paths-from-command with find to only backup files from a given user + # Use --paths-from-command with find to back up files only from a given user $ borg create --paths-from-command joes-files -- find /srv/samba/shared -user joe # Use --paths-from-stdin with --paths-delimiter (for example, for filenames with newlines in them) $ find ~ -size -1000k -print0 | borg create \ diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index 74b0aef6..41232a8e 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -43,7 +43,7 @@ borg create +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--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-stdin`` | read DELIM-separated list of paths to back up from stdin. Will not recurse into directories. | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | ``--paths-from-command`` | interpret PATH as command and treat its output as ``--paths-from-stdin`` | +-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -136,7 +136,7 @@ borg create --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) --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-stdin read DELIM-separated list of paths to back up 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) diff --git a/docs/usage/general/resources.rst.inc b/docs/usage/general/resources.rst.inc index 4f55a4cd..d8ce1b24 100644 --- a/docs/usage/general/resources.rst.inc +++ b/docs/usage/general/resources.rst.inc @@ -91,5 +91,5 @@ Network (only for client/server operation): encrypted) data of course has to go over the connection (``ssh://`` repo url). If you use a locally mounted network filesystem, additionally some copy operations used for transaction support also go over the connection. If - you backup multiple sources to one target repository, additional traffic + you back up multiple sources to one target repository, additional traffic happens for cache resynchronization. diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc index edf85c20..ef4df476 100644 --- a/docs/usage/help.rst.inc +++ b/docs/usage/help.rst.inc @@ -195,14 +195,14 @@ are added. Exclusion patterns from ``--exclude-from`` files are appended last. Examples:: - # backup pics, but not the ones from 2018, except the good ones: + # back up 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 archive pics - # backup only JPG/JPEG files (case insensitive) in all home directories: + # back up only JPG/JPEG files (case insensitive) in all home directories: borg create --pattern '+ re:\.jpe?g(?i)$' archive /home - # backup homes, but exclude big downloads (like .ISO files) or hidden files: + # back up homes, but exclude big downloads (like .ISO files) or hidden files: borg create --exclude 're:\.iso(?i)$' --exclude 'sh:home/**/.*' archive /home # use a file with patterns (recursion root '/' via command line): @@ -217,7 +217,7 @@ The patterns.lst file could look like that:: + home/susan # also back up this exact file + pf:home/bobby/specialfile.txt - # don't backup the other home directories + # don't back up the other home directories - home/* # don't even look in /dev, /proc, /run, /sys, /tmp (note: would exclude files like /device, too) ! re:^(dev|proc|run|sys|tmp) diff --git a/docs/usage/key_export.rst.inc b/docs/usage/key_export.rst.inc index 871355dc..35975e9a 100644 --- a/docs/usage/key_export.rst.inc +++ b/docs/usage/key_export.rst.inc @@ -54,7 +54,7 @@ Description ~~~~~~~~~~~ If repository encryption is used, the repository is inaccessible -without the key. This command allows one to backup this essential key. +without the key. This command allows one to back up this essential key. Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase. diff --git a/docs/usage/notes.rst b/docs/usage/notes.rst index b4e1637a..7472369d 100644 --- a/docs/usage/notes.rst +++ b/docs/usage/notes.rst @@ -30,7 +30,7 @@ for block devices (like disks, partitions, LVM LVs) or raw disk image files. ``--chunker-params=fixed,4096,512`` results in fixed 4kiB sized blocks, but the first header block will only be 512B long. This might be useful to -dedup files with 1 header + N fixed size data blocks. Be careful to not +dedup files with 1 header + N fixed size data blocks. Be careful not to produce a too big amount of chunks (like using small block size for huge files). @@ -63,7 +63,7 @@ For more details, see :ref:`chunker_details`. ``--noatime / --noctime`` ~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use these ``borg create`` options to not store the respective timestamp +You can use these ``borg create`` options not to store the respective timestamp into the archive, in case you do not really need it. Besides saving a little space for the not archived timestamp, it might also @@ -74,7 +74,7 @@ won't deduplicate just because of that. ``--nobsdflags / --noflags`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can use this to not query and store (or not extract and set) flags - in case +You can use this not to query and store (or not extract and set) flags - in case you don't need them or if they are broken somehow for your fs. On Linux, dealing with the flags needs some additional syscalls. Especially when @@ -132,7 +132,7 @@ scale and perform better if you do not work via the FUSE mount. Example +++++++ -Imagine you have made some snapshots of logical volumes (LVs) you want to backup. +Imagine you have made some snapshots of logical volumes (LVs) you want to back up. .. note:: diff --git a/docs/usage/rcreate.rst.inc b/docs/usage/rcreate.rst.inc index 65d8b0bd..b6e79d53 100644 --- a/docs/usage/rcreate.rst.inc +++ b/docs/usage/rcreate.rst.inc @@ -151,7 +151,7 @@ in the upper part of the table, in the lower part is the old and/or unsafe(r) st .. nanorst: inline-replace -`none` mode uses no encryption and no authentication. You're advised to NOT use this mode +`none` mode uses no encryption and no authentication. You're advised NOT to use this mode as it would expose you to all sorts of issues (DoS, confidentiality, tampering, ...) in case of malicious activity in the repository. diff --git a/src/borg/archive.py b/src/borg/archive.py index c6f3861c..c736df66 100644 --- a/src/borg/archive.py +++ b/src/borg/archive.py @@ -1824,7 +1824,7 @@ class ArchiveChecker: # if we kill the defect chunk here, subsequent actions within this "borg check" # run will find missing chunks and replace them with all-zero replacement # chunks and flag the files as "repaired". - # if another backup is done later and the missing chunks get backupped again, + # if another backup is done later and the missing chunks get backed up again, # a "borg check" afterwards can heal all files where this chunk was missing. logger.warning( "Found defect chunks. They will be deleted now, so affected files can " diff --git a/src/borg/archiver/create_cmd.py b/src/borg/archiver/create_cmd.py index 85535740..c132f861 100644 --- a/src/borg/archiver/create_cmd.py +++ b/src/borg/archiver/create_cmd.py @@ -744,7 +744,7 @@ class CreateMixIn: subparser.add_argument( "--paths-from-stdin", action="store_true", - help="read DELIM-separated list of paths to backup from stdin. Will not " "recurse into directories.", + help="read DELIM-separated list of paths to back up from stdin. Will not " "recurse into directories.", ) subparser.add_argument( "--paths-from-command", diff --git a/src/borg/archiver/help_cmd.py b/src/borg/archiver/help_cmd.py index aace6c20..6ead8daa 100644 --- a/src/borg/archiver/help_cmd.py +++ b/src/borg/archiver/help_cmd.py @@ -199,14 +199,14 @@ class HelpMixIn: Examples:: - # backup pics, but not the ones from 2018, except the good ones: + # back up 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 archive pics - # backup only JPG/JPEG files (case insensitive) in all home directories: + # back up only JPG/JPEG files (case insensitive) in all home directories: borg create --pattern '+ re:\\.jpe?g(?i)$' archive /home - # backup homes, but exclude big downloads (like .ISO files) or hidden files: + # back up homes, but exclude big downloads (like .ISO files) or hidden files: borg create --exclude 're:\\.iso(?i)$' --exclude 'sh:home/**/.*' archive /home # use a file with patterns (recursion root '/' via command line): @@ -221,7 +221,7 @@ class HelpMixIn: + home/susan # also back up this exact file + pf:home/bobby/specialfile.txt - # don't backup the other home directories + # don't back up the other home directories - home/* # don't even look in /dev, /proc, /run, /sys, /tmp (note: would exclude files like /device, too) ! re:^(dev|proc|run|sys|tmp) diff --git a/src/borg/archiver/key_cmds.py b/src/borg/archiver/key_cmds.py index abb9d1ee..96dec5cc 100644 --- a/src/borg/archiver/key_cmds.py +++ b/src/borg/archiver/key_cmds.py @@ -151,7 +151,7 @@ class KeysMixIn: key_export_epilog = process_epilog( """ If repository encryption is used, the repository is inaccessible - without the key. This command allows one to backup this essential key. + without the key. This command allows one to back up this essential key. Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase. diff --git a/src/borg/archiver/rcreate_cmd.py b/src/borg/archiver/rcreate_cmd.py index 00914f5b..ef65bd86 100644 --- a/src/borg/archiver/rcreate_cmd.py +++ b/src/borg/archiver/rcreate_cmd.py @@ -146,7 +146,7 @@ class RCreateMixIn: .. nanorst: inline-replace - `none` mode uses no encryption and no authentication. You're advised to NOT use this mode + `none` mode uses no encryption and no authentication. You're advised NOT to use this mode as it would expose you to all sorts of issues (DoS, confidentiality, tampering, ...) in case of malicious activity in the repository. diff --git a/src/borg/archiver/rdelete_cmd.py b/src/borg/archiver/rdelete_cmd.py index fc1e8691..0284d525 100644 --- a/src/borg/archiver/rdelete_cmd.py +++ b/src/borg/archiver/rdelete_cmd.py @@ -54,7 +54,7 @@ class RDeleteMixIn: for archive_info in manifest.archives.list(sort_by=["ts"]): msg.append(format_archive(archive_info)) else: - msg.append("This repository seems to not have any archives.") + msg.append("This repository seems not to have any archives.") else: msg.append( "This repository seems to have no manifest, so we can't " diff --git a/src/borg/repository.py b/src/borg/repository.py index 19e34808..62498ed6 100644 --- a/src/borg/repository.py +++ b/src/borg/repository.py @@ -129,7 +129,7 @@ class Repository: this is of course way more complex). LoggedIO gracefully handles truncate/unlink splits as long as the truncate resulted in - a zero length file. Zero length segments are considered to not exist, while LoggedIO.cleanup() + a zero length file. Zero length segments are considered not to exist, while LoggedIO.cleanup() will still get rid of them. """ diff --git a/src/borg/testsuite/hashindex.py b/src/borg/testsuite/hashindex.py index 0a761af8..d5b6149c 100644 --- a/src/borg/testsuite/hashindex.py +++ b/src/borg/testsuite/hashindex.py @@ -615,17 +615,17 @@ class IndexCorruptionTestCase(BaseTestCase): idx = NSIndex() # create lots of colliding entries - for y in range(700): # stay below max load to not trigger resize + for y in range(700): # stay below max load not to trigger resize idx[HH(0, y, 0)] = (0, y, 0) assert idx.size() == 1024 + 1031 * 48 # header + 1031 buckets # delete lots of the collisions, creating lots of tombstones - for y in range(400): # stay above min load to not trigger resize + for y in range(400): # stay above min load not to trigger resize del idx[HH(0, y, 0)] # create lots of colliding entries, within the not yet used part of the hashtable - for y in range(330): # stay below max load to not trigger resize + for y in range(330): # stay below max load not to trigger resize # at y == 259 a resize will happen due to going beyond max EFFECTIVE load # if the bug is present, that element will be inserted at the wrong place. # and because it will be at the wrong place, it can not be found again. diff --git a/src/borg/testsuite/repository.py b/src/borg/testsuite/repository.py index 535e6d21..0e180c69 100644 --- a/src/borg/testsuite/repository.py +++ b/src/borg/testsuite/repository.py @@ -463,7 +463,7 @@ class RepositoryCommitTestCase(RepositoryTestCaseBase): put_segment = get_latest_segment() self.repository.commit(compact=False) - # We now delete H(1), and force this segment to not be compacted, which can happen + # We now delete H(1), and force this segment not to be compacted, which can happen # if it's not sparse enough (symbolized by H(2) here). self.repository.delete(H(1)) self.repository.put(H(2), fchunk(b"1"))