build_usage / build_man

Author: ThomasWaldmann

docs/man/borg-analyze.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-ANALYZE" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-ANALYZE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-analyze \- Analyze archives
 .SH SYNOPSIS

docs/man/borg-benchmark-cpu.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK-CPU" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CPU" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-benchmark-cpu \- Benchmark CPU bound operations.
 .SH SYNOPSIS

docs/man/borg-benchmark-crud.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK-CRUD" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-BENCHMARK-CRUD" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-benchmark-crud \- Benchmark Create, Read, Update, Delete for archives.
 .SH SYNOPSIS
@@ -47,11 +47,9 @@ If your repository is encrypted and borg needs a passphrase to unlock the key, u
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp

docs/man/borg-benchmark.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BENCHMARK" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-BENCHMARK" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-benchmark \- benchmark command
 .SH SYNOPSIS

docs/man/borg-break-lock.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-BREAK-LOCK" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-BREAK-LOCK" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-break-lock \- Break the repository lock (e.g. in case it was left by a dead borg.
 .SH SYNOPSIS

docs/man/borg-check.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CHECK" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-CHECK" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-check \- Check repository consistency
 .SH SYNOPSIS
@@ -44,7 +44,7 @@ the file magic headers, and both the metadata and data of all objects in
 the repository. The read data is checked by size and hash. Bit rot and other
 types of accidental damage can be detected this way. Running the repository
 check can be split into multiple partial checks using \fB\-\-max\-duration\fP\&.
-When checking a \fI\%ssh://\fP remote repository, please note that the checks run on
+When checking a  <ssh://>  remote repository, please note that the checks run on
 the server and do not cause significant network traffic.
 .IP 2. 3
 Checking consistency and correctness of the archive metadata and optionally
@@ -137,37 +137,16 @@ objects from the repository after it did a 2nd try to read them correctly.
 .IP 2. 3
 When checking the consistency and correctness of archives, repair mode might
 remove whole archives from the manifest if their archive metadata chunk is
-corrupt or lost. On a chunk level (i.e. the contents of files), repair mode
-will replace corrupt or lost chunks with a same\-size replacement chunk of
-zeroes. If a previously zeroed chunk reappears, repair mode will restore
-this lost chunk using the new chunk.
+corrupt or lost. Borg will also report files that reference missing chunks.
 .UNINDENT
 .sp
-Most steps taken by repair mode have a one\-time effect on the repository, like
-removing a lost archive from the repository. However, replacing a corrupt or
-lost chunk with an all\-zero replacement will have an ongoing effect on the
-repository: When attempting to extract a file referencing an all\-zero chunk,
-the \fBextract\fP command will distinctly warn about it. The FUSE filesystem
-created by the \fBmount\fP command will reject reading such a \(dqzero\-patched\(dq
-file unless a special mount option is given.
-.sp
-As mentioned earlier, Borg might be able to \(dqheal\(dq a \(dqzero\-patched\(dq file in
-repair mode, if all its previously lost chunks reappear (e.g. via a later
-backup). This is achieved by Borg not only keeping track of the all\-zero
-replacement chunks, but also by keeping metadata about the lost chunks. In
-repair mode Borg will check whether a previously lost chunk reappeared and will
-replace the all\-zero replacement chunk by the reappeared chunk. If all lost
-chunks of a \(dqzero\-patched\(dq file reappear, this effectively \(dqheals\(dq the file.
-Consequently, if lost chunks were repaired earlier, it is advised to run
-\fB\-\-repair\fP a second time after creating some new backups.
-.sp
 If \fB\-\-repair \-\-find\-lost\-archives\fP is given, previously lost entries will
 be recreated in the archive directory. This is only possible before
 \fBborg compact\fP would remove the archives\(aq data completely.
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-\-repository\-only

docs/man/borg-common.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMMON" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-COMMON" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-common \- Common options of Borg commands
 .SH SYNOPSIS

docs/man/borg-compact.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMPACT" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-COMPACT" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-compact \- Collect garbage in repository
 .SH SYNOPSIS
@@ -70,19 +70,36 @@ archives directory corruption. Such archives could potentially be restored with
 might not want to do that unless there are signs of lost archives (e.g. when
 seeing fatal errors when creating backups or when archives are missing in
 \fBborg repo\-list\fP).
+.sp
+When giving the \fB\-\-stats\fP option, borg will internally list all repository
+objects to determine their existence AND stored size. It will build a fresh
+chunks index from that information and cache it in the repository. For some
+types of repositories, this might be very slow. It will tell you the sum of
+stored object sizes, before and after compaction.
+.sp
+Without \fB\-\-stats\fP, borg will rely on the cached chunks index to determine
+existing object IDs (but there is no stored size information in the index,
+thus it can\(aqt compute before/after compaction size statistics).
 .SH OPTIONS
 .sp
 See \fIborg\-common(1)\fP for common options of Borg commands.
+.SS options
+.INDENT 0.0
+.TP
+.B  \-n\fP,\fB  \-\-dry\-run
+do nothing
+.TP
+.B  \-s\fP,\fB  \-\-stats
+print statistics (might be much slower)
+.UNINDENT
 .SH EXAMPLES
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # compact segments and free repo disk space
 $ borg compact
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH SEE ALSO

docs/man/borg-compression.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-COMPRESSION" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-COMPRESSION" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-compression \- Details regarding compression
 .SH DESCRIPTION
@@ -103,69 +103,75 @@ Available factors:
 .INDENT 7.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 1:     0.01 ..        100
 2:     0.1  ..      1,000
 3:     1    ..     10,000
 4:    10    ..    100,000
 5:   100    ..  1,000,000
 6: 1,000    .. 10,000,000
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
 Example probabilities for SPEC \fB1\fP:
 .INDENT 7.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 90   %  0.01 ..   0.1
  9   %  0.1  ..   1
  0.9 %  1    ..  10
  0.09% 10    .. 100
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .sp
 \fIRandomly sized padding up to the given size\fP (additive)
 .INDENT 7.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 110: 1kiB (2 ^ (SPEC \- 100))
 \&...
 120: 1MiB
 \&...
 123: 8MiB (max.)
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
+.sp
+\fIPadmé padding\fP (deterministic)
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.EX
+250: pads to sums of powers of 2, max 12% overhead
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+Uses the Padmé algorithm to deterministically pad the compressed size to a sum of
+powers of 2, limiting overhead to 12%. See  <https://lbarman.ch/blog/padme/>  for details.
 .UNINDENT
 .sp
 Examples:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-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
+.EX
+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 ...
 borg create \-\-compression obfuscate,2,zstd,6 ...
-.ft P
-.fi
+borg create \-\-compression obfuscate,250,zstd,3 ...
+.EE
 .UNINDENT
 .UNINDENT
 .SH AUTHOR

docs/man/borg-create.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "BORG-CREATE" 1 "2024-11-16" "" "borg backup tool"
+.TH "BORG-CREATE" "1" "2025-04-21" "" "borg backup tool"
 .SH NAME
 borg-create \- Create new archive
 .SH SYNOPSIS
@@ -137,7 +137,7 @@ specify the archive name
 .B PATH
 paths to archive
 .UNINDENT
-.SS optional arguments
+.SS options
 .INDENT 0.0
 .TP
 .B  \-n\fP,\fB  \-\-dry\-run
@@ -195,7 +195,7 @@ include/exclude paths matching PATTERN
 read include/exclude patterns from PATTERNFILE, one per line
 .TP
 .B  \-\-exclude\-caches
-exclude directories that contain a CACHEDIR.TAG file (\fI\%http://www.bford.info/cachedir/spec.html\fP)
+exclude directories that contain a CACHEDIR.TAG file ( <http://www.bford.info/cachedir/spec.html> )
 .TP
 .BI \-\-exclude\-if\-present \ NAME
 exclude directories that are tagged by containing a filesystem object with the given NAME
@@ -261,16 +261,15 @@ select compression algorithm, see the output of the \(dqborg help compression\(d
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
+.EX
 # Backup ~/Documents into an archive named \(dqmy\-documents\(dq
 $ borg create my\-documents ~/Documents
 
 # same, but list all files as we process them
 $ 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                \e
@@ -340,8 +339,7 @@ $ find ~ \-size \-1000k \-print0 | borg create \e
     \-\-paths\-from\-stdin \e
     \-\-paths\-delimiter \(dq\e0\(dq \e
     smallfiles\-handle\-newline
-.ft P
-.fi
+.EE
 .UNINDENT
 .UNINDENT
 .SH NOTES
@@ -432,11 +430,9 @@ pipe directly to borg:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-backup\-vm \-\-id myvm \-\-stdout | borg create REPO::ARCHIVE \-
-.ft P
-.fi
+.EX
+backup\-vm \-\-id myvm \-\-stdout | borg create \-\-repo REPO ARCHIVE \-
+.EE
 .UNINDENT
 .UNINDENT
 .sp
@@ -447,11 +443,9 @@ to the command:
 .INDENT 0.0
 .INDENT 3.5
 .sp
-.nf
-.ft C
-borg create \-\-content\-from\-command REPO::ARCHIVE \-\- backup\-vm \-\-id myvm \-\-stdout
-.ft P
-.fi
+.EX
+borg create \-\-content\-from\-command \-\-repo REPO ARCHIVE \-\- backup\-vm \-\-id myvm \-\-stdout
+.EE
 .UNINDENT
 .UNINDENT
 .sp