mirror
/
borg
mirror of https://github.com/borgbackup/borg.git
1
0
Fork 0
Code Issues Releases Wiki Activity
borg/docs/usage/recreate.rst.inc

99 lines
3.7 KiB
PHP
Raw Normal View History

borg recreate: Re-create existing archives. Use with caution: permanent data loss by specifying incorrect patterns is easily possible. Make a dry run to make sure you got everything right. borg recreate has many uses: - Can selectively remove files/dirs from old archives, e.g. to free space or purging picturarum biggus dickus from history - Recompress data - Rechunkify data, to have upgraded Attic / Borg 0.xx archives deduplicate with Borg 1.x archives. (Or to experiment with chunker-params for specific use cases It is interrupt- and resumable. Chunks are not freed on-the-fly. Rationale: Makes only sense when rechunkifying, but logic on which new chunks to free what input chunks is complicated and *very* delicate. Future TODOs: - Refactor tests using py.test fixtures -- would require porting ArchiverTestCase to py.test: many changes, this changeset is already borderline too large. - Possibly add a --target option to not replace the source archive -- with the target possibly in another Repo (better than "cp" due to full integrity checking, and deduplication at the target) - Detect and skip (unless --always-recompress) already recompressed chunks Fixes #787 #686 #630 #70 (and probably some I overlooked) Also see #757 and #770
2016-04-07 09:29:52 +00:00
.. _borg_recreate:
borg recreate
-------------
::
Assimilate "borg comment" into "borg recreate"
2016-04-10 12:09:05 +00:00
borg recreate <options> REPOSITORY_OR_ARCHIVE PATH
positional arguments
REPOSITORY_OR_ARCHIVE
repository/archive to recreate
PATH
paths to recreate; patterns are supported
optional arguments
``--list``
| output verbose list of items (files, dirs, ...)
``--filter STATUSCHARS``
| only display items with the given status characters
``-p``, ``--progress``
recreate: improve tests, docs, check chunk availability[1] [1] So if e.g. delete/prune/check are run these can delete the recreate_partial_chunks. This is now caught and handled correctly.
2016-04-10 13:59:10 +00:00
| show progress display while recreating archives
Assimilate "borg comment" into "borg recreate"
2016-04-10 12:09:05 +00:00
``-n``, ``--dry-run``
| do not change anything
``-s``, ``--stats``
| print statistics at end
`Common options`_
|
Exclusion options
``-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
Archive options
``--comment COMMENT``
| add a comment text to the archive
``--timestamp yyyy-mm-ddThh:mm:ss``
| manually specify the archive creation date/time (UTC). alternatively, give a reference file/directory.
``-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).
``--chunker-params CHUNK_MIN_EXP,CHUNK_MAX_EXP,HASH_MASK_BITS,HASH_WINDOW_SIZE``
| specify the chunker parameters (or "default").
borg recreate: Re-create existing archives. Use with caution: permanent data loss by specifying incorrect patterns is easily possible. Make a dry run to make sure you got everything right. borg recreate has many uses: - Can selectively remove files/dirs from old archives, e.g. to free space or purging picturarum biggus dickus from history - Recompress data - Rechunkify data, to have upgraded Attic / Borg 0.xx archives deduplicate with Borg 1.x archives. (Or to experiment with chunker-params for specific use cases It is interrupt- and resumable. Chunks are not freed on-the-fly. Rationale: Makes only sense when rechunkifying, but logic on which new chunks to free what input chunks is complicated and *very* delicate. Future TODOs: - Refactor tests using py.test fixtures -- would require porting ArchiverTestCase to py.test: many changes, this changeset is already borderline too large. - Possibly add a --target option to not replace the source archive -- with the target possibly in another Repo (better than "cp" due to full integrity checking, and deduplication at the target) - Detect and skip (unless --always-recompress) already recompressed chunks Fixes #787 #686 #630 #70 (and probably some I overlooked) Also see #757 and #770
2016-04-07 09:29:52 +00:00
Description
~~~~~~~~~~~
Recreate the contents of existing archives.
--exclude, --exclude-from and PATH have the exact same semantics
recreate: improve tests, docs, check chunk availability[1] [1] So if e.g. delete/prune/check are run these can delete the recreate_partial_chunks. This is now caught and handled correctly.
2016-04-10 13:59:10 +00:00
as in "borg create". If PATHs are specified the resulting archive
will only contain files from these PATHs.
borg recreate: Re-create existing archives. Use with caution: permanent data loss by specifying incorrect patterns is easily possible. Make a dry run to make sure you got everything right. borg recreate has many uses: - Can selectively remove files/dirs from old archives, e.g. to free space or purging picturarum biggus dickus from history - Recompress data - Rechunkify data, to have upgraded Attic / Borg 0.xx archives deduplicate with Borg 1.x archives. (Or to experiment with chunker-params for specific use cases It is interrupt- and resumable. Chunks are not freed on-the-fly. Rationale: Makes only sense when rechunkifying, but logic on which new chunks to free what input chunks is complicated and *very* delicate. Future TODOs: - Refactor tests using py.test fixtures -- would require porting ArchiverTestCase to py.test: many changes, this changeset is already borderline too large. - Possibly add a --target option to not replace the source archive -- with the target possibly in another Repo (better than "cp" due to full integrity checking, and deduplication at the target) - Detect and skip (unless --always-recompress) already recompressed chunks Fixes #787 #686 #630 #70 (and probably some I overlooked) Also see #757 and #770
2016-04-07 09:29:52 +00:00
--compression: all chunks seen will be stored using the given method.
Due to how Borg stores compressed size information this might display
recreate: improve tests, docs, check chunk availability[1] [1] So if e.g. delete/prune/check are run these can delete the recreate_partial_chunks. This is now caught and handled correctly.
2016-04-10 13:59:10 +00:00
incorrect information for archives that were not recreated at the same time.
borg recreate: Re-create existing archives. Use with caution: permanent data loss by specifying incorrect patterns is easily possible. Make a dry run to make sure you got everything right. borg recreate has many uses: - Can selectively remove files/dirs from old archives, e.g. to free space or purging picturarum biggus dickus from history - Recompress data - Rechunkify data, to have upgraded Attic / Borg 0.xx archives deduplicate with Borg 1.x archives. (Or to experiment with chunker-params for specific use cases It is interrupt- and resumable. Chunks are not freed on-the-fly. Rationale: Makes only sense when rechunkifying, but logic on which new chunks to free what input chunks is complicated and *very* delicate. Future TODOs: - Refactor tests using py.test fixtures -- would require porting ArchiverTestCase to py.test: many changes, this changeset is already borderline too large. - Possibly add a --target option to not replace the source archive -- with the target possibly in another Repo (better than "cp" due to full integrity checking, and deduplication at the target) - Detect and skip (unless --always-recompress) already recompressed chunks Fixes #787 #686 #630 #70 (and probably some I overlooked) Also see #757 and #770
2016-04-07 09:29:52 +00:00
There is no risk of data loss by this.
--chunker-params will re-chunk all files in the archive, this can be
used to have upgraded Borg 0.xx or Attic archives deduplicate with
Borg 1.x archives.
borg recreate is signal safe. Send either SIGINT (Ctrl-C on most terminals) or
SIGTERM to request termination.
Use the *exact same* command line to resume the operation later - changing excludes
or paths will lead to inconsistencies (changed excludes will only apply to newly
processed files/dirs). Changing compression leads to incorrect size information
(which does not cause any data loss, but can be misleading).
Changing chunker params between invocations might lead to data loss.
USE WITH CAUTION.
recreate: improve tests, docs, check chunk availability[1] [1] So if e.g. delete/prune/check are run these can delete the recreate_partial_chunks. This is now caught and handled correctly.
2016-04-10 13:59:10 +00:00
Depending on the PATHs and patterns given, recreate can be used to permanently
delete files from archives.
borg recreate: Re-create existing archives. Use with caution: permanent data loss by specifying incorrect patterns is easily possible. Make a dry run to make sure you got everything right. borg recreate has many uses: - Can selectively remove files/dirs from old archives, e.g. to free space or purging picturarum biggus dickus from history - Recompress data - Rechunkify data, to have upgraded Attic / Borg 0.xx archives deduplicate with Borg 1.x archives. (Or to experiment with chunker-params for specific use cases It is interrupt- and resumable. Chunks are not freed on-the-fly. Rationale: Makes only sense when rechunkifying, but logic on which new chunks to free what input chunks is complicated and *very* delicate. Future TODOs: - Refactor tests using py.test fixtures -- would require porting ArchiverTestCase to py.test: many changes, this changeset is already borderline too large. - Possibly add a --target option to not replace the source archive -- with the target possibly in another Repo (better than "cp" due to full integrity checking, and deduplication at the target) - Detect and skip (unless --always-recompress) already recompressed chunks Fixes #787 #686 #630 #70 (and probably some I overlooked) Also see #757 and #770
2016-04-07 09:29:52 +00:00
When in doubt, use "--dry-run --verbose --list" to see how patterns/PATHS are
interpreted.
The archive being recreated is only removed after the operation completes. The
archive that is built during the operation exists at the same time at
"<ARCHIVE>.recreate". The new archive will have a different archive ID.
When rechunking space usage can be substantial, expect at least the entire
recreate: improve tests, docs, check chunk availability[1] [1] So if e.g. delete/prune/check are run these can delete the recreate_partial_chunks. This is now caught and handled correctly.
2016-04-10 13:59:10 +00:00
deduplicated size of the archives using the previous chunker params.
borg recreate: Re-create existing archives. Use with caution: permanent data loss by specifying incorrect patterns is easily possible. Make a dry run to make sure you got everything right. borg recreate has many uses: - Can selectively remove files/dirs from old archives, e.g. to free space or purging picturarum biggus dickus from history - Recompress data - Rechunkify data, to have upgraded Attic / Borg 0.xx archives deduplicate with Borg 1.x archives. (Or to experiment with chunker-params for specific use cases It is interrupt- and resumable. Chunks are not freed on-the-fly. Rationale: Makes only sense when rechunkifying, but logic on which new chunks to free what input chunks is complicated and *very* delicate. Future TODOs: - Refactor tests using py.test fixtures -- would require porting ArchiverTestCase to py.test: many changes, this changeset is already borderline too large. - Possibly add a --target option to not replace the source archive -- with the target possibly in another Repo (better than "cp" due to full integrity checking, and deduplication at the target) - Detect and skip (unless --always-recompress) already recompressed chunks Fixes #787 #686 #630 #70 (and probably some I overlooked) Also see #757 and #770
2016-04-07 09:29:52 +00:00
When recompressing approximately 1 % of the repository size or 512 MB
(whichever is greater) of additional space is used.