diff options
| -rw-r--r-- | .gitignore | 2 | ||||
| -rw-r--r-- | docs/api.rst | 87 | ||||
| -rw-r--r-- | docs/usage/change-passphrase.rst.inc | 29 | ||||
| -rw-r--r-- | docs/usage/check.rst.inc | 67 | ||||
| -rw-r--r-- | docs/usage/create.rst.inc | 73 | ||||
| -rw-r--r-- | docs/usage/debug-delete-obj.rst.inc | 29 | ||||
| -rw-r--r-- | docs/usage/debug-dump-archive-items.rst.inc | 28 | ||||
| -rw-r--r-- | docs/usage/debug-get-obj.rst.inc | 30 | ||||
| -rw-r--r-- | docs/usage/debug-put-obj.rst.inc | 29 | ||||
| -rw-r--r-- | docs/usage/delete.rst.inc | 32 | ||||
| -rw-r--r-- | docs/usage/extract.rst.inc | 49 | ||||
| -rw-r--r-- | docs/usage/help.rst.inc | 34 | ||||
| -rw-r--r-- | docs/usage/info.rst.inc | 28 | ||||
| -rw-r--r-- | docs/usage/init.rst.inc | 34 | ||||
| -rw-r--r-- | docs/usage/list.rst.inc | 32 | ||||
| -rw-r--r-- | docs/usage/mount.rst.inc | 35 | ||||
| -rw-r--r-- | docs/usage/prune.rst.inc | 66 | ||||
| -rw-r--r-- | docs/usage/rename.rst.inc | 29 | ||||
| -rw-r--r-- | docs/usage/serve.rst.inc | 27 | ||||
| -rw-r--r-- | docs/usage/upgrade.rst.inc | 65 |
20 files changed, 803 insertions, 2 deletions
diff --git a/.gitignore b/.gitignore index 73d508fe8..2d77951bd 100644 --- a/.gitignore +++ b/.gitignore @@ -15,8 +15,6 @@ platform_linux.c *.pyc *.pyo *.so -docs/usage/*.inc -docs/api.rst .idea/ .cache/ borg/_version.py diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 000000000..e16b9f181 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,87 @@ + +API Documentation +================= + +.. automodule:: borg.key + :members: + :undoc-members: + +.. automodule:: borg.cache + :members: + :undoc-members: + +.. automodule:: borg.locking + :members: + :undoc-members: + +.. automodule:: borg.platform + :members: + :undoc-members: + +.. automodule:: borg.xattr + :members: + :undoc-members: + +.. automodule:: borg.fuse + :members: + :undoc-members: + +.. automodule:: borg.logger + :members: + :undoc-members: + +.. automodule:: borg.repository + :members: + :undoc-members: + +.. automodule:: borg.archiver + :members: + :undoc-members: + +.. automodule:: borg.archive + :members: + :undoc-members: + +.. automodule:: borg.lrucache + :members: + :undoc-members: + +.. automodule:: borg.remote + :members: + :undoc-members: + +.. automodule:: borg.upgrader + :members: + :undoc-members: + +.. automodule:: borg.helpers + :members: + :undoc-members: + +.. automodule:: borg.platform_freebsd + :members: + :undoc-members: + +.. automodule:: borg.hashindex + :members: + :undoc-members: + +.. automodule:: borg.chunker + :members: + :undoc-members: + +.. automodule:: borg.platform_darwin + :members: + :undoc-members: + +.. automodule:: borg.platform_linux + :members: + :undoc-members: + +.. automodule:: borg.compress + :members: + :undoc-members: + +.. automodule:: borg.crypto + :members: + :undoc-members: diff --git a/docs/usage/change-passphrase.rst.inc b/docs/usage/change-passphrase.rst.inc new file mode 100644 index 000000000..9d0926d1d --- /dev/null +++ b/docs/usage/change-passphrase.rst.inc @@ -0,0 +1,29 @@ +.. _borg_change-passphrase: + +borg change-passphrase +---------------------- +:: + + usage: borg change-passphrase [-h] [-v] [--show-rc] [--no-files-cache] + [--umask M] [--remote-path PATH] + [REPOSITORY] + + Change repository key file passphrase + + positional arguments: + REPOSITORY + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + +Description +~~~~~~~~~~~ + +The key files used for repository encryption are optionally passphrase +protected. This command can be used to change this passphrase. diff --git a/docs/usage/check.rst.inc b/docs/usage/check.rst.inc new file mode 100644 index 000000000..f2a05956b --- /dev/null +++ b/docs/usage/check.rst.inc @@ -0,0 +1,67 @@ +.. _borg_check: + +borg check +---------- +:: + + usage: borg check [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [--repository-only] [--archives-only] + [--repair] [--last N] + [REPOSITORY_OR_ARCHIVE] + + Check repository consistency + + positional arguments: + REPOSITORY_OR_ARCHIVE + repository or archive to check consistency of + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + --repository-only only perform repository checks + --archives-only only perform archives checks + --repair attempt to repair any inconsistencies found + --last N only check last N archives (Default: all) + +Description +~~~~~~~~~~~ + +The check command verifies the consistency of a repository and the corresponding archives. + +First, the underlying repository data files are checked: + +- For all segments the segment magic (header) is checked +- For all objects stored in the segments, all metadata (e.g. crc and size) and + all data is read. The read data is checked by size and CRC. Bit rot and other + types of accidental damage can be detected this way. +- If we are in repair mode and a integrity error is detected for a segment, + we try to recover as many objects from the segment as possible. +- In repair mode, it makes sure that the index is consistent with the data + stored in the segments. +- If you use a remote repo server via ssh:, the repo check is executed on the + repo server without causing significant network traffic. +- The repository check can be skipped using the --archives-only option. + +Second, the consistency and correctness of the archive metadata is verified: + +- Is the repo manifest present? If not, it is rebuilt from archive metadata + chunks (this requires reading and decrypting of all metadata and data). +- Check if archive metadata chunk is present. if not, remove archive from + manifest. +- For all files (items) in the archive, for all chunks referenced by these + files, check if chunk is present (if not and we are in repair mode, replace + it with a same-size chunk of zeros). This requires reading of archive and + file metadata, but not data. +- If we are in repair mode and we checked all the archives: delete orphaned + chunks from the repo. +- if you use a remote repo server via ssh:, the archive check is executed on + the client machine (because if encryption is enabled, the checks will require + decryption and this is always done client-side, because key access will be + required). +- The archive checks can be time consuming, they can be skipped using the + --repository-only option. diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc new file mode 100644 index 000000000..c52108cbe --- /dev/null +++ b/docs/usage/create.rst.inc @@ -0,0 +1,73 @@ +.. _borg_create: + +borg create +----------- +:: + + usage: borg create [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [-s] [-p] [-e PATTERN] + [--exclude-from EXCLUDEFILE] [--exclude-caches] + [--exclude-if-present FILENAME] [--keep-tag-files] + [-c SECONDS] [-x] [--numeric-owner] + [--timestamp yyyy-mm-ddThh:mm:ss] + [--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE] + [-C COMPRESSION] [--read-special] [-n] + ARCHIVE PATH [PATH ...] + + Create new archive + + positional arguments: + ARCHIVE name of archive to create (must be also a valid + directory name) + PATH paths to archive + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + -s, --stats print statistics for the created archive + -p, --progress toggle progress display while creating the archive, + showing Original, Compressed and Deduplicated sizes, + followed by the Number of files seen and the path + being processed, default: True + -e PATTERN, --exclude PATTERN + exclude paths matching PATTERN + --exclude-from EXCLUDEFILE + read exclude patterns from EXCLUDEFILE, one per line + --exclude-caches exclude directories that contain a CACHEDIR.TAG file + (http://www.brynosaurus.com/cachedir/spec.html) + --exclude-if-present FILENAME + exclude directories that contain the specified file + --keep-tag-files keep tag files of excluded caches/directories + -c SECONDS, --checkpoint-interval SECONDS + write checkpoint every SECONDS seconds (Default: 300) + -x, --one-file-system + stay in same file system, do not cross mount points + --numeric-owner only store numeric user and group identifiers + --timestamp yyyy-mm-ddThh:mm:ss + manually specify the archive creation date/time (UTC). + alternatively, give a reference file/directory. + --chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE + specify the chunker parameters. default: 10,23,16,4095 + -C COMPRESSION, --compression COMPRESSION + select compression algorithm (and level): none == no + compression (default), lz4 == lz4, zlib == zlib + (default level 6), zlib,0 .. zlib,9 == zlib (with + level 0..9), lzma == lzma (default level 6), lzma,0 .. + lzma,9 == lzma (with level 0..9). + --read-special open and read special files as if they were regular + files + -n, --dry-run do not create a backup archive + +Description +~~~~~~~~~~~ + +This command creates a backup archive containing all files found while recursively +traversing all paths specified. The archive will consume almost no disk space for +files or parts of files that have already been stored in other archives. + +See the output of the "borg help patterns" command for more help on exclude patterns. diff --git a/docs/usage/debug-delete-obj.rst.inc b/docs/usage/debug-delete-obj.rst.inc new file mode 100644 index 000000000..3cdea3214 --- /dev/null +++ b/docs/usage/debug-delete-obj.rst.inc @@ -0,0 +1,29 @@ +.. _borg_debug-delete-obj: + +borg debug-delete-obj +--------------------- +:: + + usage: borg debug-delete-obj [-h] [-v] [--show-rc] [--no-files-cache] + [--umask M] [--remote-path PATH] + [REPOSITORY] IDs [IDs ...] + + delete the objects with the given IDs from the repo + + positional arguments: + REPOSITORY repository to use + IDs hex object ID(s) to delete from the repo + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + +Description +~~~~~~~~~~~ + +This command deletes objects from the repository. diff --git a/docs/usage/debug-dump-archive-items.rst.inc b/docs/usage/debug-dump-archive-items.rst.inc new file mode 100644 index 000000000..cb68493d2 --- /dev/null +++ b/docs/usage/debug-dump-archive-items.rst.inc @@ -0,0 +1,28 @@ +.. _borg_debug-dump-archive-items: + +borg debug-dump-archive-items +----------------------------- +:: + + usage: borg debug-dump-archive-items [-h] [-v] [--show-rc] [--no-files-cache] + [--umask M] [--remote-path PATH] + ARCHIVE + + dump (decrypted, decompressed) archive items metadata (not: data) + + positional arguments: + ARCHIVE archive to dump + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + +Description +~~~~~~~~~~~ + +This command dumps raw (but decrypted and decompressed) archive items (only metadata) to files. diff --git a/docs/usage/debug-get-obj.rst.inc b/docs/usage/debug-get-obj.rst.inc new file mode 100644 index 000000000..8343d8669 --- /dev/null +++ b/docs/usage/debug-get-obj.rst.inc @@ -0,0 +1,30 @@ +.. _borg_debug-get-obj: + +borg debug-get-obj +------------------ +:: + + usage: borg debug-get-obj [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] + [REPOSITORY] ID PATH + + get object contents from the repository and write it into file + + positional arguments: + REPOSITORY repository to use + ID hex object ID to get from the repo + PATH file to write object data into + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + +Description +~~~~~~~~~~~ + +This command gets an object from the repository. diff --git a/docs/usage/debug-put-obj.rst.inc b/docs/usage/debug-put-obj.rst.inc new file mode 100644 index 000000000..cb14b5dee --- /dev/null +++ b/docs/usage/debug-put-obj.rst.inc @@ -0,0 +1,29 @@ +.. _borg_debug-put-obj: + +borg debug-put-obj +------------------ +:: + + usage: borg debug-put-obj [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] + [REPOSITORY] PATH [PATH ...] + + put file(s) contents into the repository + + positional arguments: + REPOSITORY repository to use + PATH file(s) to read and create object(s) from + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + +Description +~~~~~~~~~~~ + +This command puts objects into the repository. diff --git a/docs/usage/delete.rst.inc b/docs/usage/delete.rst.inc new file mode 100644 index 000000000..afdbd9db1 --- /dev/null +++ b/docs/usage/delete.rst.inc @@ -0,0 +1,32 @@ +.. _borg_delete: + +borg delete +----------- +:: + + usage: borg delete [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [-s] [-c] + [TARGET] + + Delete an existing repository or archive + + positional arguments: + TARGET archive or repository to delete + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + -s, --stats print statistics for the deleted archive + -c, --cache-only delete only the local cache for the given repository + +Description +~~~~~~~~~~~ + +This command deletes an archive from the repository or the complete repository. +Disk space is reclaimed accordingly. If you delete the complete repository, the +local cache for it (if any) is also deleted. diff --git a/docs/usage/extract.rst.inc b/docs/usage/extract.rst.inc new file mode 100644 index 000000000..cbacd7033 --- /dev/null +++ b/docs/usage/extract.rst.inc @@ -0,0 +1,49 @@ +.. _borg_extract: + +borg extract +------------ +:: + + usage: borg extract [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [-n] [-e PATTERN] + [--exclude-from EXCLUDEFILE] [--numeric-owner] + [--strip-components NUMBER] [--stdout] [--sparse] + ARCHIVE [PATH [PATH ...]] + + Extract archive contents + + positional arguments: + ARCHIVE archive to extract + PATH paths to extract + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + -n, --dry-run do not actually change any files + -e PATTERN, --exclude PATTERN + exclude paths matching PATTERN + --exclude-from EXCLUDEFILE + read exclude patterns from EXCLUDEFILE, one per line + --numeric-owner only obey numeric user and group identifiers + --strip-components NUMBER + Remove the specified number of leading path elements. + Pathnames with fewer elements will be silently + skipped. + --stdout write all extracted data to stdout + --sparse create holes in output sparse file from all-zero + chunks + +Description +~~~~~~~~~~~ + +This command extracts the contents of an archive. By default the entire +archive is extracted but a subset of files and directories can be selected +by passing a list of ``PATHs`` as arguments. The file selection can further +be restricted by using the ``--exclude`` option. + +See the output of the "borg help patterns" command for more help on exclude patterns. diff --git a/docs/usage/help.rst.inc b/docs/usage/help.rst.inc new file mode 100644 index 000000000..0379cd498 --- /dev/null +++ b/docs/usage/help.rst.inc @@ -0,0 +1,34 @@ +.. _borg_patterns: + +borg help patterns +~~~~~~~~~~~~~~~~~~ +:: + + + Exclude patterns use a variant of shell pattern syntax, with '*' matching any + number of characters, '?' matching any single character, '[...]' matching any + single character specified, including ranges, and '[!...]' matching any + character not specified. For the purpose of these patterns, the path + separator ('\' for Windows and '/' on other systems) is not treated + specially. For a path to match a pattern, it must completely match from + start to end, or must match from the start to just before a path separator. + Except for the root path, paths will never end in the path separator when + matching is attempted. Thus, if a given pattern ends in a path separator, a + '*' is appended before matching is attempted. Patterns with wildcards should + be quoted to protect them from shell expansion. + + Examples: + + # Exclude '/home/user/file.o' but not '/home/user/file.odt': + $ borg create -e '*.o' backup / + + # Exclude '/home/user/junk' and '/home/user/subdir/junk' but + # not '/home/user/importantjunk' or '/etc/junk': + $ borg create -e '/home/*/junk' backup / + + # Exclude the contents of '/home/user/cache' but not the directory itself: + $ borg create -e /home/user/cache/ backup / + + # The file '/home/user/cache/important' is *not* backed up: + $ borg create -e /home/user/cache/ backup / /home/user/cache/important +
\ No newline at end of file diff --git a/docs/usage/info.rst.inc b/docs/usage/info.rst.inc new file mode 100644 index 000000000..2ddb651e2 --- /dev/null +++ b/docs/usage/info.rst.inc @@ -0,0 +1,28 @@ +.. _borg_info: + +borg info +--------- +:: + + usage: borg info [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] + ARCHIVE + + Show archive details such as disk space used + + positional arguments: + ARCHIVE archive to display information about + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + +Description +~~~~~~~~~~~ + +This command displays some detailed information about the specified archive. diff --git a/docs/usage/init.rst.inc b/docs/usage/init.rst.inc new file mode 100644 index 000000000..4e0f47b0b --- /dev/null +++ b/docs/usage/init.rst.inc @@ -0,0 +1,34 @@ +.. _borg_init: + +borg init +--------- +:: + + usage: borg init [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [-e {none,keyfile,repokey,passphrase}] + [REPOSITORY] + + Initialize an empty repository + + positional arguments: + REPOSITORY repository to create + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + -e {none,keyfile,repokey,passphrase}, --encryption {none,keyfile,repokey,passphrase} + select encryption key mode + +Description +~~~~~~~~~~~ + +This command initializes an empty repository. A repository is a filesystem +directory containing the deduplicated data from zero or more archives. +Encryption can be enabled at repository init time. +Please note that the 'passphrase' encryption mode is DEPRECATED (instead of it, +consider using 'repokey'). diff --git a/docs/usage/list.rst.inc b/docs/usage/list.rst.inc new file mode 100644 index 000000000..882fff25f --- /dev/null +++ b/docs/usage/list.rst.inc @@ -0,0 +1,32 @@ +.. _borg_list: + +borg list +--------- +:: + + usage: borg list [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [--short] [-p PREFIX] + [REPOSITORY_OR_ARCHIVE] + + List archive or repository contents + + positional arguments: + REPOSITORY_OR_ARCHIVE + repository/archive to list contents of + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + --short only print file/directory names, nothing else + -p PREFIX, --prefix PREFIX + only consider archive names starting with this prefix + +Description +~~~~~~~~~~~ + +This command lists the contents of a repository or an archive. diff --git a/docs/usage/mount.rst.inc b/docs/usage/mount.rst.inc new file mode 100644 index 000000000..0407a095c --- /dev/null +++ b/docs/usage/mount.rst.inc @@ -0,0 +1,35 @@ +.. _borg_mount: + +borg mount +---------- +:: + + usage: borg mount [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [-f] [-o OPTIONS] + REPOSITORY_OR_ARCHIVE MOUNTPOINT + + Mount archive or an entire repository as a FUSE fileystem + + positional arguments: + REPOSITORY_OR_ARCHIVE + repository/archive to mount + MOUNTPOINT where to mount filesystem + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + -f, --foreground stay in foreground, do not daemonize + -o OPTIONS Extra mount options + +Description +~~~~~~~~~~~ + +This command mounts an archive as a FUSE filesystem. This can be useful for +browsing an archive or restoring individual files. Unless the ``--foreground`` +option is given the command will run in the background until the filesystem +is ``umounted``. diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc new file mode 100644 index 000000000..c2133736e --- /dev/null +++ b/docs/usage/prune.rst.inc @@ -0,0 +1,66 @@ +.. _borg_prune: + +borg prune +---------- +:: + + usage: borg prune [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [-n] [-s] [--keep-within WITHIN] + [-H HOURLY] [-d DAILY] [-w WEEKLY] [-m MONTHLY] [-y YEARLY] + [-p PREFIX] + [REPOSITORY] + + Prune repository archives according to specified rules + + positional arguments: + REPOSITORY repository to prune + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + -n, --dry-run do not change repository + -s, --stats print statistics for the deleted archive + --keep-within WITHIN keep all archives within this time interval + -H HOURLY, --keep-hourly HOURLY + number of hourly archives to keep + -d DAILY, --keep-daily DAILY + number of daily archives to keep + -w WEEKLY, --keep-weekly WEEKLY + number of weekly archives to keep + -m MONTHLY, --keep-monthly MONTHLY + number of monthly archives to keep + -y YEARLY, --keep-yearly YEARLY + number of yearly archives to keep + -p PREFIX, --prefix PREFIX + only consider archive names starting with this prefix + +Description +~~~~~~~~~~~ + +The prune command prunes a repository by deleting archives not matching +any of the specified retention options. This command is normally used by +automated backup scripts wanting to keep a certain number of historic backups. + +As an example, "-d 7" means to keep the latest backup on each day for 7 days. +Days without backups do not count towards the total. +The rules are applied from hourly to yearly, and backups selected by previous +rules do not count towards those of later rules. The time that each backup +completes is used for pruning purposes. Dates and times are interpreted in +the local timezone, and weeks go from Monday to Sunday. Specifying a +negative number of archives to keep means that there is no limit. + +The "--keep-within" option takes an argument of the form "<int><char>", +where char is "H", "d", "w", "m", "y". For example, "--keep-within 2d" means +to keep all archives that were created within the past 48 hours. +"1m" is taken to mean "31d". The archives kept with this option do not +count towards the totals specified by any other options. + +If a prefix is set with -p, then only archives that start with the prefix are +considered for deletion and only those archives count towards the totals +specified by the rules. +Otherwise, *all* archives in the repository are candidates for deletion! diff --git a/docs/usage/rename.rst.inc b/docs/usage/rename.rst.inc new file mode 100644 index 000000000..23cb338ee --- /dev/null +++ b/docs/usage/rename.rst.inc @@ -0,0 +1,29 @@ +.. _borg_rename: + +borg rename +----------- +:: + + usage: borg rename [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] + ARCHIVE NEWNAME + + Rename an existing archive + + positional arguments: + ARCHIVE archive to rename + NEWNAME the new archive name to use + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + +Description +~~~~~~~~~~~ + +This command renames an archive in the repository. diff --git a/docs/usage/serve.rst.inc b/docs/usage/serve.rst.inc new file mode 100644 index 000000000..8c4052264 --- /dev/null +++ b/docs/usage/serve.rst.inc @@ -0,0 +1,27 @@ +.. _borg_serve: + +borg serve +---------- +:: + + usage: borg serve [-h] [-v] [--show-rc] [--no-files-cache] [--umask M] + [--remote-path PATH] [--restrict-to-path PATH] + + Start in server mode. This command is usually not used manually. + + + optional arguments: + -h, --help show this help message and exit + -v, --verbose verbose output + --show-rc show/log the return code (rc) + --no-files-cache do not load/update the file metadata cache used to + detect unchanged files + --umask M set umask to M (local and remote, default: 63) + --remote-path PATH set remote path to executable (default: "borg") + --restrict-to-path PATH + restrict repository access to PATH + +Description +~~~~~~~~~~~ + +This command starts a repository server process. This command is usually not used manually. diff --git a/docs/usage/upgrade.rst.inc b/docs/usage/upgrade.rst.inc new file mode 100644 index 000000000..7b9660b54 --- /dev/null +++ b/docs/usage/upgrade.rst.inc @@ -0,0 +1,65 @@ |