Merge pull request #6803 from ThomasWaldmann/fix-docs-borg2

borg2: fix docs
2026-04-09 19:06:30 -04:00 · 2022-06-26 23:01:34 +02:00 · 2022-06-26 23:01:34 +02:00 · 6ebcfb7490
commit 6ebcfb7490
parent 70cc578fc2 0a7baa53c4
10 changed files with 57 additions and 55 deletions
--- a/docs/changes.rst
+++ b/docs/changes.rst
@ -90,7 +90,7 @@ Changes:

  - symmetric hlid (all hardlinks pointing to same inode have same hlid)
  - all archived hardlinked regular files have a chunks list
- borg init --other-repo=OTHER_REPO: reuse key material from OTHER_REPO, #6554.
+- borg rcreate --other-repo=OTHER_REPO: reuse key material from OTHER_REPO, #6554.
  This is useful if you want to use borg transfer to transfer archives from an
  existing borg 1.1/1.2 repo. If the chunker secret and the id key and algorithm
  stay the same, the deduplication will also work between past and future backups.
--- a/docs/man/borg-list.1
+++ b/docs/man/borg-list.1
@ -144,13 +144,22 @@ $ borg list \-\-format \(aq{mode} {user:>6} {group:>6} {size:<8} {mtime} {path}{
 .UNINDENT
 .sp
 The following keys are always available:
-\- NEWLINE: OS dependent line separator
-\- NL: alias of NEWLINE
-\- NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below
-\- SPACE
-\- TAB
-\- CR
-\- LF
+.INDENT 0.0
+.IP \(bu 2
+NEWLINE: OS dependent line separator
+.IP \(bu 2
+NL: alias of NEWLINE
+.IP \(bu 2
+NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below
+.IP \(bu 2
+SPACE
+.IP \(bu 2
+TAB
+.IP \(bu 2
+CR
+.IP \(bu 2
+LF
+.UNINDENT
 .sp
 Keys available only when listing files in an archive:
 .INDENT 0.0
--- a/docs/man/borg-rlist.1
+++ b/docs/man/borg-rlist.1
@ -116,13 +116,22 @@ ArchiveFoo                           Thu, 2021\-12\-09 10:22:28 [0b8e9a312bef3f2
 .UNINDENT
 .sp
 The following keys are always available:
-\- NEWLINE: OS dependent line separator
-\- NL: alias of NEWLINE
-\- NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below
-\- SPACE
-\- TAB
-\- CR
-\- LF
+.INDENT 0.0
+.IP \(bu 2
+NEWLINE: OS dependent line separator
+.IP \(bu 2
+NL: alias of NEWLINE
+.IP \(bu 2
+NUL: NUL character for creating print0 / xargs \-0 like output, see barchive and bpath keys below
+.IP \(bu 2
+SPACE
+.IP \(bu 2
+TAB
+.IP \(bu 2
+CR
+.IP \(bu 2
+LF
+.UNINDENT
 .sp
 Keys available only when listing archives in a repository:
 .INDENT 0.0
--- a/docs/man/borg-transfer.1
+++ b/docs/man/borg-transfer.1
@ -93,10 +93,12 @@ consider last N archives after other filters were applied
 .UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
-.TP
-.B ::
-# 0. Have borg 2.0 installed on client AND server, have a b12 repo copy for testing.
+.INDENT 3.5
 .sp
+.nf
+.ft C
+# 0. Have borg 2.0 installed on client AND server, have a b12 repo copy for testing.
+
 # 1. Create a new "related" repository:
 # here, the existing borg 1.2 repo used repokey\-blake2 (and aes\-ctr mode),
 # thus we use repokey\-blake2\-aes\-ocb for the new borg 2.0 repo.
@ -106,43 +108,22 @@ consider last N archives after other filters were applied
 # 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 repo did not use blake2, just remove the "\-blake2".
-$ borg \-\-repo       \fI\%ssh://borg2@borgbackup/./tests/b20\fP rcreate 
-.IP "System Message: ERROR/3 (docs/borg-transfer.rst:, line 88)"
-Unexpected indentation.
-.INDENT 7.0
-.INDENT 3.5
-\-\-other\-repo \fI\%ssh://borg2@borgbackup/./tests/b12\fP \-e repokey\-blake2\-aes\-ocb
-.UNINDENT
-.UNINDENT
-.sp
+$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 rcreate \e
+       \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-e repokey\-blake2\-aes\-ocb
+
 # 2. Check what and how much it would transfer:
-$ borg \-\-repo       \fI\%ssh://borg2@borgbackup/./tests/b20\fP transfer 
-.IP "System Message: ERROR/3 (docs/borg-transfer.rst:, line 92)"
-Unexpected indentation.
-.INDENT 7.0
-.INDENT 3.5
-\-\-other\-repo \fI\%ssh://borg2@borgbackup/./tests/b12\fP \-\-dry\-run
-.UNINDENT
-.UNINDENT
-.sp
+$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \e
+       \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run
+
 # 3. Transfer (copy) archives from old repo into new repo (takes time and space!):
-$ borg \-\-repo       \fI\%ssh://borg2@borgbackup/./tests/b20\fP transfer 
-.IP "System Message: ERROR/3 (docs/borg-transfer.rst:, line 96)"
-Unexpected indentation.
-.INDENT 7.0
-.INDENT 3.5
-\-\-other\-repo \fI\%ssh://borg2@borgbackup/./tests/b12\fP
-.UNINDENT
-.UNINDENT
-.sp
+$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \e
+       \-\-other\-repo ssh://borg2@borgbackup/./tests/b12
+
 # 4. Check if we have everything (same as 2.):
-$ borg \-\-repo       \fI\%ssh://borg2@borgbackup/./tests/b20\fP transfer 
-.IP "System Message: ERROR/3 (docs/borg-transfer.rst:, line 100)"
-Unexpected indentation.
-.INDENT 7.0
-.INDENT 3.5
-\-\-other\-repo \fI\%ssh://borg2@borgbackup/./tests/b12\fP \-\-dry\-run
-.UNINDENT
+$ borg \-\-repo       ssh://borg2@borgbackup/./tests/b20 transfer \e
+       \-\-other\-repo ssh://borg2@borgbackup/./tests/b12 \-\-dry\-run
+.ft P
+.fi
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO
--- a/docs/man/borg.1
+++ b/docs/man/borg.1
@ -615,7 +615,6 @@ it should be a move (not a copy) operation, and in case of a directory
 it should fail if the destination exists and is not an empty directory,
 since this is used for locking.
 .IP \(bu 2
-Hardlinks are needed for \fIborg_upgrade\fP (if \fB\-\-inplace\fP option is not used).
 Also hardlinks are used for more safe and secure file updating (e.g. of the repo
 config file), but the code tries to work also if hardlinks are not supported.
 .UNINDENT
--- a/docs/usage/general/file-systems.rst.inc
+++ b/docs/usage/general/file-systems.rst.inc
@ -26,6 +26,5 @@ and readable after one of the failures mentioned above occurred, run
  it should be a move (not a copy) operation, and in case of a directory
  it should fail if the destination exists and is not an empty directory,
  since this is used for locking.
- Hardlinks are needed for :ref:`borg_upgrade` (if ``--inplace`` option is not used).
-  Also hardlinks are used for more safe and secure file updating (e.g. of the repo
+- Also hardlinks are used for more safe and secure file updating (e.g. of the repo
  config file), but the code tries to work also if hardlinks are not supported.
--- a/docs/usage/list.rst.inc
+++ b/docs/usage/list.rst.inc
@ -103,6 +103,7 @@ Examples:
    ...

 The following keys are always available:
+
 - NEWLINE: OS dependent line separator
 - NL: alias of NEWLINE
 - NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below
--- a/docs/usage/rlist.rst.inc
+++ b/docs/usage/rlist.rst.inc
@ -99,6 +99,7 @@ Examples:
    ...

 The following keys are always available:
+
 - NEWLINE: OS dependent line separator
 - NL: alias of NEWLINE
 - NUL: NUL character for creating print0 / xargs -0 like output, see barchive and bpath keys below
--- a/docs/usage/transfer.rst
+++ b/docs/usage/transfer.rst
@ -3,6 +3,7 @@
 Examples
 ~~~~~~~~
 ::
+
    # 0. Have borg 2.0 installed on client AND server, have a b12 repo copy for testing.

    # 1. Create a new "related" repository:
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@ -4653,6 +4653,7 @@ class Archiver:

        The following keys are always available:

+
        """) + BaseFormatter.keys_help() + textwrap.dedent("""

        Keys available only when listing files in an archive:
@ -4710,6 +4711,7 @@ class Archiver:

        The following keys are always available:

+
        """) + BaseFormatter.keys_help() + textwrap.dedent("""

        Keys available only when listing archives in a repository: