build_man / build_usage

1 files changed, 71 insertions, 34 deletions

diff --git a/docs/man/borg-patterns.1 b/docs/man/borg-patterns.1
index e082a59e4..096c27ea2 100644
--- a/docs/man/borg-patterns.1
+++ b/docs/man/borg-patterns.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-PATTERNS" 1 "2023-03-22" "" "borg backup tool"
+.TH "BORG-PATTERNS" 1 "2023-07-20" "" "borg backup tool"
 .SH NAME
 borg-patterns \- Details regarding patterns
 .SH DESCRIPTION
@@ -36,34 +36,20 @@ The path/filenames used as input for the pattern matching start from the
 currently active recursion root. You usually give the recursion root(s)
 when invoking borg and these can be either relative or absolute paths.
 .sp
-If you give \fI/absolute/\fP as root, the paths going into the matcher will
-look relative like \fIabsolute/.../file.ext\fP, because file paths in Borg
-archives are always stored normalized and relative. This means that e.g.
-\fBborg create /path/to/repo ../some/path\fP will store all files as
-\fIsome/path/.../file.ext\fP and \fBborg create /path/to/repo /home/user\fP
-will store all files as \fIhome/user/.../file.ext\fP\&.
+Starting with Borg 1.2, paths that are matched against patterns always
+appear relative. If you give \fB/absolute/\fP as root, the paths going
+into the matcher will start with \fBabsolute/\fP\&.
+If you give \fB\&../../relative\fP as root, the paths will be normalized
+as \fBrelative/\fP\&.
 .sp
 A directory exclusion pattern can end either with or without a slash (\(aq/\(aq).
 If it ends with a slash, such as \fIsome/path/\fP, the directory will be
 included but not its content. If it does not end with a slash, such as
 \fIsome/path\fP, both the directory and content will be excluded.
 .sp
-File patterns support these styles: fnmatch, shell, regular expressions,
-path prefixes and path full\-matches. By default, fnmatch is used for
-\fB\-\-exclude\fP patterns and shell\-style is used for the \fB\-\-pattern\fP
-option. For commands that support patterns in their \fBPATH\fP argument
-like (\fBborg list\fP), the default pattern is path prefix.
-.sp
-Starting with Borg 1.2, discovered fs paths are normalised, have leading
-slashes removed and then are matched against your patterns.
-Note: You need to review your include / exclude patterns and make
-sure they do not expect leading slashes. Borg can only deal with this
-for some very simple patterns by removing leading slashes there also.
-.sp
-If followed by a colon (\(aq:\(aq) the first two characters of a pattern are
-used as a style selector. Explicit style selection is necessary when a
-non\-default style is desired or when the desired pattern starts with
-two alphanumeric characters followed by a colon (i.e. \fIaa:something/*\fP).
+Borg supports different pattern styles. To define a non\-default
+style for a specific pattern, prefix it with two characters followed
+by a colon \(aq:\(aq (i.e. \fBfm:path/*\fP, \fBsh:path/**\fP).
 .INDENT 0.0
 .TP
 .B \fI\%Fnmatch\fP, selector \fIfm:\fP
@@ -186,12 +172,37 @@ $ borg create \-\-exclude\-from exclude.txt backup /
 .UNINDENT
 .UNINDENT
 .sp
-A more general and easier to use way to define filename matching patterns exists
-with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using these, you may
-specify the backup roots (starting points) and patterns for inclusion/exclusion.
-A root path starts with the prefix \fIR\fP, followed by a path (a plain path, not a
-file pattern). An include rule starts with the prefix +, an exclude rule starts
-with the prefix \-, an exclude\-norecurse rule starts with !, all followed by a pattern.
+A more general and easier to use way to define filename matching patterns
+exists with the \fB\-\-pattern\fP and \fB\-\-patterns\-from\fP options. Using
+these, you may specify the backup roots, default pattern styles and
+patterns for inclusion and exclusion.
+.INDENT 0.0
+.TP
+.B Root path prefix \fBR\fP
+A recursion root path starts with the prefix \fBR\fP, followed by a path
+(a plain path, not a file pattern). Use this prefix to have the root
+paths in the patterns file rather than as command line arguments.
+.TP
+.B Pattern style prefix \fBP\fP
+To change the default pattern style, use the \fBP\fP prefix, followed by
+the pattern style abbreviation (\fBfm\fP, \fBpf\fP, \fBpp\fP, \fBre\fP, \fBsh\fP).
+All patterns following this line will use this style until another style
+is specified.
+.TP
+.B Exclude pattern prefix \fB\-\fP
+Use the prefix \fB\-\fP, followed by a pattern, to define an exclusion.
+This has the same effect as the \fB\-\-exclude\fP option.
+.TP
+.B Exclude no\-recurse pattern prefix \fB!\fP
+Use the prefix \fB!\fP, followed by a pattern, to define an exclusion
+that does not recurse into subdirectories. This saves time, but
+prevents include patterns to match any files in subdirectories.
+.TP
+.B Include pattern prefix \fB+\fP
+Use the prefix \fB+\fP, followed by a pattern, to define inclusions.
+This is useful to include paths that are covered in an exclude
+pattern and would otherwise not be backed up.
+.UNINDENT
 .sp
 \fBNOTE:\fP
 .INDENT 0.0
@@ -202,11 +213,37 @@ of files using pattern prefixes \fB+\fP and \fB\-\fP\&. With \fB\-\-exclude\fP a
 .UNINDENT
 .UNINDENT
 .sp
-Inclusion patterns are useful to include paths that are contained in an excluded
-path. The first matching pattern is used so if an include pattern matches before
-an exclude pattern, the file is backed up. If an exclude\-norecurse pattern matches
-a directory, it won\(aqt recurse into it and won\(aqt discover any potential matches for
-include rules below that directory.
+The first matching pattern is used, so if an include pattern matches
+before an exclude pattern, the file is backed up. Note that a no\-recurse
+exclude stops examination of subdirectories so that potential includes
+will not match \- use normal excludes for such use cases.
+.sp
+Example:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+# Define the recursion root
+R /
+# Exclude all iso files in any directory
+\- **/*.iso
+# Explicitly include all inside etc and root
++ etc/**
++ root/**
+# Exclude a specific directory under each user\(aqs home directories
+\- home/*/.cache
+# Explicitly include everything in /home
++ home/**
+# Explicitly exclude some directories without recursing into them
+! re:^(dev|proc|run|sys|tmp)
+# Exclude all other files and directories
+# that are not specifically included earlier.
+\- **
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .sp
 \fBNOTE:\fP
 .INDENT 0.0