borg-transfer(1)

Name
borg-transfer - archives transfer from other repository, optionally upgrade data format

SYNOPSIS

borg [common options] transfer [options]

DESCRIPTION

This command transfers archives from one repository to another repository. Optionally, it can also upgrade the transferred data. Optionally, it can also recompress the transferred data. Optionally, it can also re-chunk the transferred data using different chunker parameters.

It is easiest (and fastest) to give --compression=COMPRESSION --recompress=never using the same COMPRESSION mode as in the SRC_REPO - borg will use that COMPRESSION for metadata (in any case) and keep data compressed "as is" (saves time as no data compression is needed).

If you want to globally change compression while transferring archives to the DST_REPO, give --compress=WANTED_COMPRESSION --recompress=always.

The default is to transfer all archives.

You could use the misc. archive filter options to limit which archives it will transfer, e.g. using the -a option. This is recommended for big repositories with multiple data sets to keep the runtime per invocation lower.

  General purpose archive transfer

Transfer borg2 archives into a related other borg2 repository:

    # create a related DST_REPO (reusing key material from SRC_REPO), so that
    # chunking and chunk id generation will work in the same way as before.
    borg --repo=DST_REPO repo-create --encryption=DST_ENC --other-repo=SRC_REPO
    # transfer archives from SRC_REPO to DST_REPO
    borg --repo=DST_REPO transfer --other-repo=SRC_REPO --dry-run  # check what it would do
    borg --repo=DST_REPO transfer --other-repo=SRC_REPO            # do it!
    borg --repo=DST_REPO transfer --other-repo=SRC_REPO --dry-run  # check! anything left?

  Data migration / upgrade from borg 1.x

To migrate your borg 1.x archives into a related, new borg2 repository, usage is quite similar to the above, but you need the --from-borg1 option:

    borg --repo=DST_REPO repocreate --encryption=DST_ENC --other-repo=SRC_REPO --from-borg1
    # to continue using lz4 compression as you did in SRC_REPO:
    borg --repo=DST_REPO transfer --other-repo=SRC_REPO --from-borg1 \
         --compress=lz4 --recompress=never
    # alternatively, to recompress everything to zstd,3:
    borg --repo=DST_REPO transfer --other-repo=SRC_REPO --from-borg1 \
         --compress=zstd,3 --recompress=always
    # to re-chunk using different chunker parameters:
    borg --repo=DST_REPO transfer --other-repo=SRC_REPO \
         --chunker-params=buzhash,19,23,21,4095

OPTIONS

See borg-common(1) for common options of Borg commands.

  options

-n, --dry-run
    do not change repository, just check

--other-repo SRC_REPOSITORY
    transfer archives from the other repository

--from-borg1
    other repository is borg 1.x

--upgrader UPGRADER
    use the upgrader to convert transferred data (default: no conversion)

-C COMPRESSION, --compression COMPRESSION
    select compression algorithm, see the output of the "borg help compression" command for details.

--recompress MODE
    recompress data chunks according to MODE and --compression. Possible modes are always: recompress unconditionally; and never: do not recompress (faster: re-uses compressed data chunks w/o change).If no MODE is given, always will be used. Not passing --recompress is equivalent to "--recompress never".

--chunker-params PARAMS
    rechunk using given chunker parameters (ALGO, CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or default to use the chunker defaults. default: do not rechunk

  Archive filters

-a PATTERN, --match-archives PATTERN
    only consider archives matching all patterns. See "borg help match-archives".

--sort-by KEYS
    Comma-separated list of sorting keys; valid keys are: timestamp, archive, name, id, tags, host, user; default is: timestamp

--first N
    consider the first N archives after other filters are applied

--last N
    consider the last N archives after other filters are applied

--oldest TIMESPAN
    consider archives between the oldest archive's timestamp and (oldest + TIMESPAN), e.g., 7d or 12m.

--newest TIMESPAN
    consider archives between the newest archive's timestamp and (newest - TIMESPAN), e.g., 7d or 12m.

--older TIMESPAN
    consider archives older than (now - TIMESPAN), e.g., 7d or 12m.

--newer TIMESPAN
    consider archives newer than (now - TIMESPAN), e.g., 7d or 12m.

EXAMPLES

    # 0. Have Borg 2.0 installed on the client AND server; have a b12 repository copy for testing.
    # 1. Create a new "related" repository:
    # Here, the existing Borg 1.2 repository used repokey-blake2 (and AES-CTR mode),
    # thus we use repokey-blake2-aes-ocb for the new Borg 2.0 repository.
    # Staying with the same chunk ID algorithm (BLAKE2) and with the same
    # key material (via --other-repo <oldrepo>) will make deduplication work
    # between old archives (copied with borg transfer) and future ones.
    # The AEAD cipher does not matter (everything must be re-encrypted and
    # re-authenticated anyway); you could also choose repokey-blake2-chacha20-poly1305.
    # In case your old Borg repository did not use BLAKE2, just remove the "-blake2".
    $ borg --repo       ssh://borg2@borgbackup/./tests/b20 repo-create \
           --other-repo ssh://borg2@borgbackup/./tests/b12 -e repokey-blake2-aes-ocb
    # 2. Check what and how much it would transfer:
    $ borg --repo       ssh://borg2@borgbackup/./tests/b20 transfer --upgrader=From12To20 \
           --other-repo ssh://borg2@borgbackup/./tests/b12 --dry-run
    # 3. Transfer (copy) archives from the old repository into the new repository (takes time and space!):
    $ borg --repo       ssh://borg2@borgbackup/./tests/b20 transfer --upgrader=From12To20 \
           --other-repo ssh://borg2@borgbackup/./tests/b12
    # 4. Check whether we have everything (same as step 2):
    $ borg --repo       ssh://borg2@borgbackup/./tests/b20 transfer --upgrader=From12To20 \
           --other-repo ssh://borg2@borgbackup/./tests/b12 --dry-run

  Keyfile considerations when upgrading from borg 1.x

If you are using a keyfile encryption mode (not repokey), borg 2 may not automatically find your borg 1.x key file, because the default key file directory has changed on some platforms due to the switch to the platformdirs <https://pypi.org/project/platformdirs/> library.

On Linux, there is typically no change -- both borg 1.x and borg 2 use ~/.config/borg/keys/.

On macOS, borg 1.x stored key files in ~/.config/borg/keys/, but borg 2 defaults to ~/Library/Application Support/borg/keys/.

On Windows, borg 1.x used XDG-style paths (e.g. ~/.config/borg/keys/), while borg 2 defaults to C:\Users\<user>\AppData\Roaming\borg\keys\.

If borg 2 cannot find your key file, you have several options:

1.  Copy the key file from the old location to the new one.

2.  Set BORG_KEYS_DIR to point to the old key file directory:

        export BORG_KEYS_DIR=~/.config/borg/keys

3.  Set BORG_KEY_FILE to point directly to the specific key file:

        export BORG_KEY_FILE=~/.config/borg/keys/your_key_file

4.  Set BORG_BASE_DIR to force borg 2 to use the same base directory as borg 1.x:

        export BORG_BASE_DIR=$HOME

    This makes borg 2 use $HOME/.config/borg, $HOME/.cache/borg, etc., matching borg 1.x behaviour on all platforms.

    See env_vars for more details on directory environment variables.

SEE ALSO

borg-common(1)

Author
The Borg Collective