From 8df4bf75d4214c876107da6c77eb8fe5418aa170 Mon Sep 17 00:00:00 2001 From: vancheese Date: Tue, 1 Apr 2025 17:28:57 +0200 Subject: [PATCH] docs: borg commands updated with --repo option, fixes #8550 --- docs/deployment/image-backup.rst | 16 ++++++++-------- docs/deployment/pull-backup.rst | 12 ++++++------ docs/usage/create.rst | 2 +- docs/usage/create.rst.inc | 4 ++-- docs/usage/general/environment.rst.inc | 2 +- docs/usage/general/logging.rst.inc | 2 +- src/borg/archiver/create_cmd.py | 4 ++-- src/borg/archiver/help_cmd.py | 18 +++++++++--------- 8 files changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/deployment/image-backup.rst b/docs/deployment/image-backup.rst index 2224607a5..9a979c4a2 100644 --- a/docs/deployment/image-backup.rst +++ b/docs/deployment/image-backup.rst @@ -63,28 +63,28 @@ deduplicating. For backup, save the disk header and the contents of each partiti HEADER_SIZE=$(sfdisk -lo Start $DISK | grep -A1 -P 'Start$' | tail -n1 | xargs echo) PARTITIONS=$(sfdisk -lo Device,Type $DISK | sed -e '1,/Device\s*Type/d') - dd if=$DISK count=$HEADER_SIZE | borg create repo::hostname-partinfo - + dd if=$DISK count=$HEADER_SIZE | borg create --repo repo hostname-partinfo - echo "$PARTITIONS" | grep NTFS | cut -d' ' -f1 | while read x; do PARTNUM=$(echo $x | grep -Eo "[0-9]+$") - ntfsclone -so - $x | borg create repo::hostname-part$PARTNUM - + ntfsclone -so - $x | borg create --repo repo hostname-part$PARTNUM - done # to back up non-NTFS partitions as well: echo "$PARTITIONS" | grep -v NTFS | cut -d' ' -f1 | while read x; do PARTNUM=$(echo $x | grep -Eo "[0-9]+$") - borg create --read-special repo::hostname-part$PARTNUM $x + borg create --read-special --repo repo hostname-part$PARTNUM $x done Restoration is a similar process:: - borg extract --stdout repo::hostname-partinfo | dd of=$DISK && partprobe + borg extract --stdout --repo repo hostname-partinfo | dd of=$DISK && partprobe PARTITIONS=$(sfdisk -lo Device,Type $DISK | sed -e '1,/Device\s*Type/d') borg list --format {archive}{NL} repo | grep 'part[0-9]*$' | while read x; do PARTNUM=$(echo $x | grep -Eo "[0-9]+$") PARTITION=$(echo "$PARTITIONS" | grep -E "$DISKp?$PARTNUM" | head -n1) if echo "$PARTITION" | cut -d' ' -f2- | grep -q NTFS; then - borg extract --stdout repo::$x | ntfsclone -rO $(echo "$PARTITION" | cut -d' ' -f1) - + borg extract --stdout --repo repo $x | ntfsclone -rO $(echo "$PARTITION" | cut -d' ' -f1) - else - borg extract --stdout repo::$x | dd of=$(echo "$PARTITION" | cut -d' ' -f1) + borg extract --stdout --repo repo $x | dd of=$(echo "$PARTITION" | cut -d' ' -f1) fi done @@ -105,11 +105,11 @@ except it works in place, zeroing the original partition. This makes the backup a bit simpler:: sfdisk -lo Device,Type $DISK | sed -e '1,/Device\s*Type/d' | grep Linux | cut -d' ' -f1 | xargs -n1 zerofree - borg create --read-special repo::hostname-disk $DISK + borg create --read-special --repo repo hostname-disk $DISK Because the partitions were zeroed in place, restoration is only one command:: - borg extract --stdout repo::hostname-disk | dd of=$DISK + borg extract --stdout --repo repo hostname-disk | dd of=$DISK .. note:: The "traditional" way to zero out space on a partition, especially one already mounted, is simply to ``dd`` from ``/dev/zero`` to a temporary file and delete diff --git a/docs/deployment/pull-backup.rst b/docs/deployment/pull-backup.rst index 5532e2fca..1d40574d6 100644 --- a/docs/deployment/pull-backup.rst +++ b/docs/deployment/pull-backup.rst @@ -98,7 +98,7 @@ create the backup, retaining the original paths, excluding the repository: :: - borg create --exclude borgrepo --files-cache ctime,size /borgrepo::archive / + borg create --exclude borgrepo --files-cache ctime,size --repo /borgrepo archive / For the sake of simplicity only ``borgrepo`` is excluded here. You may want to set up an exclude file with additional files and folders to be excluded. Also @@ -159,7 +159,7 @@ Now we can run :: - borg extract /borgrepo::archive PATH + borg extract --repo /borgrepo archive PATH to restore whatever we like partially. Finally, do the clean-up: @@ -187,7 +187,7 @@ and extract a backup, utilizing the ``--numeric-ids`` option: sshfs root@host:/ /mnt/sshfs cd /mnt/sshfs - borg extract --numeric-ids /path/to/repo::archive + borg extract --numeric-ids --repo /path/to/repo archive cd ~ umount /mnt/sshfs @@ -199,7 +199,7 @@ directly extract it without the need of mounting with SSHFS: :: - borg export-tar /path/to/repo::archive - | ssh root@host 'tar -C / -x' + borg export-tar --repo /path/to/repo archive - | ssh root@host 'tar -C / -x' Note that in this scenario the tar format is the limiting factor – it cannot restore all the advanced features that BorgBackup supports. See @@ -301,7 +301,7 @@ ignore all arguments intended for the SSH command. All Borg commands can now be executed on *borg-client*. For example to create a backup execute the ``borg create`` command:: - borg-client:~$ borg create ssh://borg-server/path/to/repo::archive /path_to_backup + borg-client:~$ borg create --repo ssh://borg-server/path/to/repo archive /path_to_backup When automating backup creation, the interactive ssh session may seem inappropriate. An alternative way of creating @@ -312,7 +312,7 @@ a backup may be the following command:: borgc@borg-client \ borg create \ --rsh "sh -c 'exec socat STDIO UNIX-CONNECT:/run/borg/reponame.sock'" \ - ssh://borg-server/path/to/repo::archive /path_to_backup \ + --repo ssh://borg-server/path/to/repo archive /path_to_backup \ ';' rm /run/borg/reponame.sock This command also automatically removes the socket file after the ``borg diff --git a/docs/usage/create.rst b/docs/usage/create.rst index df8235159..6f13a4a12 100644 --- a/docs/usage/create.rst +++ b/docs/usage/create.rst @@ -11,7 +11,7 @@ Examples $ borg create --list my-documents ~/Documents # Backup /mnt/disk/docs, but strip path prefix using the slashdot hack - $ borg create /path/to/repo::docs /mnt/disk/./docs + $ borg create --repo /path/to/repo docs /mnt/disk/./docs # Backup ~/Documents and ~/src but exclude pyc files $ borg create my-files \ diff --git a/docs/usage/create.rst.inc b/docs/usage/create.rst.inc index f6b0a4a74..645ea3d23 100644 --- a/docs/usage/create.rst.inc +++ b/docs/usage/create.rst.inc @@ -329,14 +329,14 @@ Reading backup data from stdin There are two methods to read from stdin. Either specify ``-`` as path and pipe directly to borg:: - backup-vm --id myvm --stdout | borg create REPO::ARCHIVE - + backup-vm --id myvm --stdout | borg create --repo REPO ARCHIVE - Or use ``--content-from-command`` to have Borg manage the execution of the command and piping. If you do so, the first PATH argument is interpreted as command to execute and any further arguments are treated as arguments to the command:: - borg create --content-from-command REPO::ARCHIVE -- backup-vm --id myvm --stdout + borg create --content-from-command --repo REPO ARCHIVE -- backup-vm --id myvm --stdout ``--`` is used to ensure ``--id`` and ``--stdout`` are **not** considered arguments to ``borg`` but rather ``backup-vm``. diff --git a/docs/usage/general/environment.rst.inc b/docs/usage/general/environment.rst.inc index 54be64432..8bfabda1c 100644 --- a/docs/usage/general/environment.rst.inc +++ b/docs/usage/general/environment.rst.inc @@ -118,7 +118,7 @@ General: This workaround is **only** for emergencies and **only** to extract data from an affected repository (read-only access):: - BORG_WORKAROUNDS=authenticated_no_key borg extract repo::archive + BORG_WORKAROUNDS=authenticated_no_key borg extract --repo repo archive After you have extracted all data you need, you MUST delete the repository:: diff --git a/docs/usage/general/logging.rst.inc b/docs/usage/general/logging.rst.inc index ba1dd8f96..f13532fab 100644 --- a/docs/usage/general/logging.rst.inc +++ b/docs/usage/general/logging.rst.inc @@ -10,7 +10,7 @@ If you want to capture the log output to a file, just redirect it: :: - borg create repo::archive myfiles 2>> logfile + borg create --repo repo archive myfiles 2>> logfile Custom logging configurations can be implemented via BORG_LOGGING_CONF. diff --git a/src/borg/archiver/create_cmd.py b/src/borg/archiver/create_cmd.py index ce64795ab..ccf6a6344 100644 --- a/src/borg/archiver/create_cmd.py +++ b/src/borg/archiver/create_cmd.py @@ -712,14 +712,14 @@ class CreateMixIn: There are two methods to read from stdin. Either specify ``-`` as path and pipe directly to borg:: - backup-vm --id myvm --stdout | borg create REPO::ARCHIVE - + backup-vm --id myvm --stdout | borg create --repo REPO ARCHIVE - Or use ``--content-from-command`` to have Borg manage the execution of the command and piping. If you do so, the first PATH argument is interpreted as command to execute and any further arguments are treated as arguments to the command:: - borg create --content-from-command REPO::ARCHIVE -- backup-vm --id myvm --stdout + borg create --content-from-command --repo REPO ARCHIVE -- backup-vm --id myvm --stdout ``--`` is used to ensure ``--id`` and ``--stdout`` are **not** considered arguments to ``borg`` but rather ``backup-vm``. diff --git a/src/borg/archiver/help_cmd.py b/src/borg/archiver/help_cmd.py index b9f9e1521..04487e9da 100644 --- a/src/borg/archiver/help_cmd.py +++ b/src/borg/archiver/help_cmd.py @@ -362,12 +362,12 @@ class HelpMixIn: If literal curly braces need to be used, double them for escaping:: - borg create /path/to/repo::{{literal_text}} + borg create --repo /path/to/repo {{literal_text}} Examples:: - borg create /path/to/repo::{hostname}-{user}-{utcnow} ... - borg create /path/to/repo::{hostname}-{now:%Y-%m-%d_%H:%M:%S%z} ... + borg create --repo /path/to/repo {hostname}-{user}-{utcnow} ... + borg create --repo /path/to/repo {hostname}-{now:%Y-%m-%d_%H:%M:%S%z} ... borg prune -a 'sh:{hostname}-*' ... .. note:: @@ -472,12 +472,12 @@ class HelpMixIn: Examples:: - borg create --compression lz4 REPO::ARCHIVE data - borg create --compression zstd REPO::ARCHIVE data - borg create --compression zstd,10 REPO::ARCHIVE data - borg create --compression zlib REPO::ARCHIVE data - borg create --compression zlib,1 REPO::ARCHIVE data - borg create --compression auto,lzma,6 REPO::ARCHIVE data + borg create --compression lz4 --repo REPO ARCHIVE data + borg create --compression zstd --repo REPO ARCHIVE data + borg create --compression zstd,10 --repo REPO ARCHIVE data + borg create --compression zlib --repo REPO ARCHIVE data + borg create --compression zlib,1 --repo REPO ARCHIVE data + borg create --compression auto,lzma,6 --repo REPO ARCHIVE data borg create --compression auto,lzma ... borg create --compression obfuscate,110,none ... borg create --compression obfuscate,3,auto,zstd,10 ...