docs: borg commands updated with --repo option, fixes #8550

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

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

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                \

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``.

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::
 

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.

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``.

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 ...