mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-27 10:18:12 +00:00
Code Issues Releases Wiki Activity
borg/docs/usage/recreate.rst.inc

164 lines
25 KiB
PHP
Raw Normal View History

Merge branch '1.0-maint'
2016-07-05 23:33:53 +00:00
.. IMPORTANT: this file is auto-generated from borg's built-in help, do not edit!
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
-------------
docs: usage: avoid bash highlight, [options] instead of <options>
2017-06-06 22:44:53 +00:00
.. code-block:: none
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
python setup.py build_usage
2017-07-23 15:12:01 +00:00
borg [common options] recreate [options] [REPOSITORY_OR_ARCHIVE] [PATH...]
Assimilate "borg comment" into "borg recreate"
2016-04-10 12:09:05 +00:00
ran build_usage
2017-06-20 13:22:24 +00:00
.. only:: html
.. class:: borg-options-table
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **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, ...) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
python setup.py build_usage
2017-07-23 15:12:01 +00:00
| | ``--filter STATUSCHARS`` | only display items with the given status characters (listed in borg create --help) |
ran build_usage
2017-06-20 13:22:24 +00:00
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change anything |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-s``, ``--stats`` | print statistics at end |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| .. 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 |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
python setup.py build_usage
2017-07-23 15:12:01 +00:00
| | ``--pattern PATTERN`` | experimental: include/exclude paths matching PATTERN |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--patterns-from PATTERNFILE`` | experimental: read include/exclude patterns from PATTERNFILE, one per line |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
ran build_usage
2017-06-20 13:22:24 +00:00
| | ``--exclude-caches`` | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--exclude-if-present NAME`` | exclude directories that are tagged by containing a filesystem object with the given NAME |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--keep-exclude-tags``, ``--keep-tag-files`` | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| **Archive options** |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--target TARGET`` | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``-c SECONDS``, ``--checkpoint-interval SECONDS`` | write checkpoint every SECONDS seconds (Default: 1800) |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--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 COMPRESSION``, ``--compression COMPRESSION`` | select compression algorithm, see the output of the "borg help compression" command for details. |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--recompress`` | recompress data chunks according to ``--compression`` if `if-different`. When `always`, chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for `if-different`, not the compression level (if any). |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| | ``--chunker-params PARAMS`` | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: 19,23,21,4095 |
+-------------------------------------------------------+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. raw:: html
<script type='text/javascript'>
docs: use DOM ready event, not document loaded event
2017-06-20 13:48:30 +00:00
$(document).ready(function () {
ran build_usage
2017-06-20 13:22:24 +00:00
$('.borg-options-table colgroup').remove();
})
</script>
.. only:: latex
REPOSITORY_OR_ARCHIVE
repository/archive to recreate
PATH
paths to recreate; patterns are supported
optional arguments
--list output verbose list of items (files, dirs, ...)
python setup.py build_usage
2017-07-23 15:12:01 +00:00
--filter STATUSCHARS only display items with the given status characters (listed in borg create --help)
ran build_usage
2017-06-20 13:22:24 +00:00
-n, --dry-run do not change anything
-s, --stats print statistics at end
:ref:`common_options`
|
Exclusion options
-e PATTERN, --exclude PATTERN exclude paths matching PATTERN
--exclude-from EXCLUDEFILE read exclude patterns from EXCLUDEFILE, one per line
python setup.py build_usage
2017-07-23 15:12:01 +00:00
--pattern PATTERN experimental: include/exclude paths matching PATTERN
--patterns-from PATTERNFILE experimental: read include/exclude patterns from PATTERNFILE, one per line
ran build_usage
2017-06-20 13:22:24 +00:00
--exclude-caches exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
--exclude-if-present NAME exclude directories that are tagged by containing a filesystem object with the given NAME
--keep-exclude-tags, --keep-tag-files if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
Archive options
--target TARGET create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
-c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800)
--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 COMPRESSION, --compression COMPRESSION select compression algorithm, see the output of the "borg help compression" command for details.
--recompress recompress data chunks according to ``--compression`` if `if-different`. When `always`, chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for `if-different`, not the compression level (if any).
--chunker-params PARAMS specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: 19,23,21,4095
ran build_usage
2017-06-20 09:49:26 +00:00
Assimilate "borg comment" into "borg recreate"
2016-04-10 12:09:05 +00:00
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.
run setup.py build_usage
2016-12-14 02:42:38 +00:00
This is an *experimental* feature. Do *not* use this on your only backup.
python setup.py build_usage
2017-06-17 10:28:42 +00:00
``--exclude``, ``--exclude-from``, ``--exclude-if-present``, ``--keep-exclude-tags``, and PATH
ran setup.py build_usage
2017-03-26 23:45:45 +00:00
have the exact same semantics 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
ran build_usage
2016-08-27 22:17:24 +00:00
Note that all paths in an archive are relative, therefore absolute patterns/paths
python setup.py build_usage
2017-06-17 10:28:42 +00:00
will *not* match (``--exclude``, ``--exclude-from``, PATHs).
ran build_usage
2016-08-27 22:17:24 +00:00
python setup.py build_usage
2017-06-17 10:28:42 +00:00
``--recompress`` allows to change the compression of existing data in 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
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.
python setup.py build_usage
2017-06-17 10:28:42 +00:00
``--chunker-params`` will re-chunk all files in the archive, this can be
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
used to have upgraded Borg 0.xx or Attic archives deduplicate with
Borg 1.x archives.
nanorst for "borg help TOPIC"
2017-06-09 17:22:18 +00:00
**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.
python setup.py build_usage
2017-06-17 10:28:42 +00:00
When in doubt, use ``--dry-run --verbose --list`` to see how patterns/PATHS are
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
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.
python setup.py build_usage
2017-06-17 10:28:42 +00:00
With ``--target`` the original archive is not replaced, instead a new archive is created.
ran build_usage
2016-08-27 22:17:24 +00:00
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 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.
run setup.py build_usage
2016-12-14 02:42:38 +00:00
When recompressing expect approx. (throughput / checkpoint-interval) in space usage,
build_usage (master) also: add new borgfs.rst.inc
2017-11-25 13:35:52 +00:00
assuming all chunks are recompressed.
If you recently ran borg check --repair and it had to fix lost chunks with all-zero
replacement chunks, please first run another backup for the same data and re-run
borg check --repair afterwards to heal any archives that had lost chunks which are
still generated from the input data.
Important: running borg recreate to re-chunk will remove the chunks_healthy
metadata of all items with replacement chunks, so healing will not be possible
any more after re-chunking (it is also unlikely it would ever work: due to the
change of chunking parameters, the missing chunk likely will never be seen again
even if you still have the data that produced it).
Reference in a new issue Copy permalink