.\" Man page generated from reStructuredText
.\" by the Docutils 0.22.4 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "borg-patterns" "1" "2026-07-18" "" "borg backup tool"
.SH "نام (NAME)"
borg-patterns \- جزئیات مربوط به الگوهای تطبیق در بورگ
.SH "توضیحات (DESCRIPTION)"
.sp
نام‌ها و مسیرهای پرونده‌هایی که به عنوان ورودی برای تطبیق الگو استفاده می‌شوند، با ریشه بازگشت (recursion root) فعال فعلی آغاز می‌گردند. شما معمولاً ریشه(های) بازگشت را هنگام فراخوانی borg مشخص می‌کنید و این‌ها می‌توانند مسیرهای نسبی یا مطلق باشند.
.sp
دقت کنید، الگوهای شما باید با مسیرهای بایگانی‌شده مطابقت داشته باشند:
.INDENT 0.0
.IP \(bu 2
مسیرهای بایگانی‌شده هرگز با اسلش آغازین ('/')، و همچنین با '.' یا '..' شروع نمی‌شوند.
.INDENT 2.0
.IP \(bu 2
هنگامی که از مسیرهای مطلق مانند \fB/home/user\fP پشتیبان می‌گیرید، مسیرهای بایگانی‌شده با \fBhome/user\fP آغاز می‌شوند.
.IP \(bu 2
هنگامی که از مسیرهای نسبی مانند \fB\&./src\fP پشتیبان می‌گیرید، مسیرهای بایگانی‌شده با \fBsrc\fP آغاز می‌شوند.
.IP \(bu 2
هنگامی که از مسیرهای نسبی مانند \fB\&../../src\fP پشتیبان می‌گیرید، مسیرهای بایگانی‌شده با \fBsrc\fP آغاز می‌شوند.
.UNINDENT
.IP \(bu 2
هنگام استفاده از ترفند slashdot، الگوها با مسیر دست‌نخورده تطبیق داده می‌شوند؛ یعنی اگر از \fB/this/gets/stripped/./this/gets/archived\fP نسخه پشتیبان تهیه کنید، الگوها باید با \fBthis/gets/stripped/this/gets/archived\fP تطبیق یابند.
.UNINDENT
.sp
الگوی استثنا کردن شاخه (دایرکتوری) می‌تواند با یک اسلش ('/') ختم شود یا نشود.
اگر با اسلش ختم شود (مانند \fIsome/path/\fP)، خود شاخه گنجانده می‌شود اما محتویات آن مستثنی می‌گردند.
اگر با اسلش ختم نشود (مانند \fIsome/path\fP)، هم خود شاخه و هم محتویات آن مستثنی خواهند شد.
.sp
بورگ از سبک‌های مختلف الگو پشتیبانی می‌کند. برای تعیین سبکی غیر از پیش‌فرض برای یک الگوی خاص، دو نویسه به همراه دونقطه ':' را به عنوان پیشوند قرار دهید (مانند \fBfm:path/*\fP یا \fBsh:path/**\fP).
.sp
سبک الگوی پیش‌فرض برای \fB\-\-exclude\fP با \fB\-\-pattern\fP متفاوت است؛ توضیحات زیر را ببینید.
.INDENT 0.0
.TP
.B Fnmatch \%<https://\:docs\:.python\:.org/\:3/\:library/\:fnmatch\:.html>, برگزیننده \fIfm:\fP
این سبک پیش‌فرض برای گزینه‌های \fB\-\-exclude\fP و \fB\-\-exclude\-from\fP است.
این الگوها گونه‌ای از قواعد الگوی پوسته (shell) را به کار می‌برند؛ به طوری که '*' با هر تعداد نویسه، '?' با هر تک‌نویسه، '[...]' با هر تک‌نویسه تعیین‌شده شامل بازه‌ها، و '[!...]' با هر نویسه‌ای غیر از موارد تعیین‌شده تطبیق می‌یابد. در این سبک، جداکننده مسیر (بک‌اسلش در ویندوز و '/' در سایر سیستم‌ها) رفتار ویژه‌ای ندارد. فرانویسه‌ها را در براکت قرار دهید تا به صورت لفظی مطابقت داده شوند (مثلاً [?] برای تطبیق خود نویسه ?). برای مطابقت مسیر با الگو، کل مسیر باید مطابقت داشته باشد، یا باید از ابتدای مسیر تا پیش از جداکننده مسیر تطابق یابد. به جز مسیر ریشه، مسیرها هنگام بررسی تطابق هرگز به جداکننده ختم نمی‌شوند. بنابراین، اگر الگویی به جداکننده ختم شود، پیش از تطبیق یک '*' به انتهای آن افزوده می‌شود. جداکننده آغازین مسیر همواره حذف می‌گردد.
.TP
.B الگوهای سبک پوسته (Shell\-style patterns), برگزیننده \fIsh:\fP
این سبک پیش‌فرض برای گزینه‌های \fB\-\-pattern\fP و \fB\-\-patterns\-from\fP است.
همانند الگوهای fnmatch، این‌ها نیز شبیه به الگوهای شل هستند. تفاوت در این است که الگو می‌تواند شامل \fI**/\fP برای تطبیق صفر یا چند سطح دایرکتوری باشد، و \fI*\fP برای تطبیق صفر یا چند نویسه دلخواه به استثنای جداکننده‌های مسیر به کار می‌رود. جداکننده آغازین مسیر همواره حذف می‌شود.
.TP
.B عبارات باقاعده (Regular expressions), برگزیننده \fIre:\fP
عبارات باقاعده مشابه آنچه در پرل (Perl) یافت می‌شود پشتیبانی می‌گردند. برخلاف الگوهای پوسته، عبارات باقاعده نیازی به تطابق با کل مسیر ندارند و انطباق با هر زیررشته‌ای کافی است. اکیداً توصیه می‌شود الگوها را به ابتدا ('^')، به انتها ('$') یا هر دو مهار (anchor) کنید. جداکننده‌های مسیر (بک‌اسلش در ویندوز و '/' در دیگر سیستم‌ها) همواره قبل از اعمال الگو به اسلش رو به جلو ('/') تبدیل می‌شوند. قواعد نحوی عبارت باقاعده در مستندات پایتون برای ماژول re \%<https://\:docs\:.python\:.org/\:3/\:library/\:re\:.html> توضیح داده شده است.
.TP
.B پیشوند مسیر (Path prefix), برگزیننده \fIpp:\fP
این سبک برای تطبیق کل زیرشاخه‌ها مفید است. الگوی \fIpp:root/somedir\fP با \fIroot/somedir\fP و هر آنچه درون آن قرار دارد مطابقت می‌یابد. جداکننده آغازین مسیر همواره حذف می‌گردد.
.TP
.B تطابق کامل مسیر (Path full\-match), برگزیننده \fIpf:\fP
این سبک (تنها) برای تطبیق کامل و دقیق مسیرها کاربرد دارد.
این نوعی شبه‌الگو است چرا که نمی‌تواند شامل بخش‌های متغیر یا نامشخص باشد؛ کل مسیر باید دقیقاً ذکر شود. الگوی \fIpf:root/file.ext\fP تنها با \fIroot/file.ext\fP مطابقت می‌یابد. جداکننده آغازین مسیر همواره حذف می‌شود.
.sp
نکته پیاده‌سازی: این سبک از طریق جدول درهم‌سازی (hashtable) بسیار کارآمد با پیچیدگی زمانی O(1) پیاده‌سازی شده است (بدین معنی که می‌توانید حجم عظیمی از این الگوها را بدون افت محسوس کارایی داشته باشید).
به همین دلیل، این نوع الگو هیچ زمینه یا ترتیبی را رعایت نمی‌کند.
اگر از چنین الگویی برای گنجاندن پرونده‌ای استفاده کنید، همواره گنجانده خواهد شد (چنانچه پیمایش بازگشتی شاخه به آن برسد).
سایر الگوهای شمول/استثنا که در حالت عادی تطبیق می‌یافتند نادیده گرفته می‌شوند. منطق مشابهی برای استثنا نیز برقرار است.
.UNINDENT
.sp
\fBنکته:\fP
.INDENT 0.0
.INDENT 3.5
الگوهای \fIre:\fP، \fIsh:\fP و \fIfm:\fP همگی بر روی موتور SRE پایتون پیاده‌سازی شده‌اند. تنظیم الگوهایی از این انواع که تطبیق آن‌ها زمان نامتعارفی طول بکشد بسیار آسان است. اگر کاربران غیرقابل اعتماد می‌توانند الگو وارد کنند، مطمئن شوید نمی‌توانند الگوهای \fIre:\fP ارائه دهند. علاوه بر این، مطمئن شوید الگوهای \fIsh:\fP و \fIfm:\fP حداکثر شامل تعداد اندکی نویسه عام (wildcard) باشند.
.UNINDENT
.UNINDENT
.sp
استثناها را می‌توان از طریق گزینه خط فرمان \fB\-\-exclude\fP وارد کرد. هنگام استفاده در محیط پوسته (شل)، الگوها باید داخل علامت نقل‌قول قرار گیرند تا از بسط آن‌ها جلوگیری شود.
.sp
الگوهای دارای نویسه‌های خاص، مثلاً فاصله خالی (space)، ممکن است نیازمند قرار گرفتن در علامت نقل‌قول باشند.
مثال:
در bash، گزینه خط فرمان زیر با "item name" مطابقت یافته و آن را مستثنی می‌کند:
\fB\-\-pattern=\(aq\-path/item name\(aq\fP
توجه داشته باشید هنگامی که الگوها در پرونده الگویی که مستقیماً توسط بورگ خوانده می‌شود قرار دارند (مثلاً با استفاده از \fB\-\-exclude\-from\fP یا \fB\-\-patterns\-from\fP)، پای پوسته در میان نیست و نیازی به نقل‌قول نیست.
.sp
گزینه \fB\-\-exclude\-from\fP امکان بارگذاری الگوهای استثنا را از یک پرونده متنی به صورت یک الگو در هر سطر فراهم می‌آورد. سطرهای خالی یا سطرهایی که پس از حذف فاصله‌های ابتدا و انتها با علامت ('#') شروع می‌شوند، نادیده گرفته می‌شوند. پیشوند اختیاری انتخاب سبک نیز در پرونده‌ها پشتیبانی می‌شود. به دلیل حذف فواصل خالی، مسیرهایی با فاصله در ابتدا یا انتها فقط با عبارات باقاعده قابل استثنا هستند.
.sp
برای آزمایش الگوهای استثنای خود بدون انجام پشتیبان‌گیری واقعی می‌توانید دستور \fBborg create \-\-list \-\-dry\-run ...\fP را اجرا کنید.
.sp
مثال‌ها:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# استثنا کردن شاخه‌ای در هر کجای درخت با نام steamapps/common (و زیرمجموعه‌های آن):
$ borg create \-e \(aqsh:**/steamapps/common/**\(aq backup /

# استثنا کردن محتویات /home/user/.cache:
$ borg create \-e \(aqsh:home/user/.cache/**\(aq backup /home/user
$ borg create \-e home/user/.cache/ backup /home/user

# پرونده /home/user/.cache/important پشتیبان‌گیری نمی‌شود:
$ borg create \-e home/user/.cache/ backup / /home/user/.cache/important

# استثنا کردن /home/user/file.o اما نه /home/user/file.odt:
$ borg create \-e \(aq*.o\(aq backup /

# استثنا کردن junk در home/user و زیرشاخه‌های آن:
$ borg create \-e \(aqhome/*/junk\(aq backup /

# استثنا کردن محتویات شاخه‌هایی در home که به tmp. ختم می‌شوند:
$ borg create \-\-exclude \(aqre:^home/[^/]+\e.tmp/\(aq backup /

# بارگذاری الگوهای استثنا از پرونده
$ cat >exclude.txt <<EOF
# سطر توضیحات
home/*/junk
*.tmp
fm:aa:something/*
re:^home/[^/]+\e.tmp/
sh:home/*/.thumbnails
# مثال با فاصله، نیازی به اسکیپ نیست
some file with spaces.txt
EOF
$ borg create \-\-exclude\-from exclude.txt backup /
.EE
.UNINDENT
.UNINDENT
.sp
روش عمومی‌تر و ساده‌تری برای تعریف الگوهای تطبیق پرونده از طریق گزینه‌های \fB\-\-pattern\fP و \fB\-\-patterns\-from\fP وجود دارد. با استفاده از این‌ها، می‌توانید ریشه‌های پشتیبان‌گیری، سبک‌های الگوی پیش‌فرض و الگوهای شمول و استثنا را تعیین کنید.
.INDENT 0.0
.TP
.B پیشوند مسیر ریشه \fBR\fP
مسیر ریشه بازگشت با پیشوند \fBR\fP آغاز می‌شود و به دنبال آن مسیر می‌آید (یک مسیر ساده، نه الگوی پرونده). از این پیشوند برای قرار دادن مسیرهای ریشه در پرونده الگوها به جای آرگومان‌های خط فرمان استفاده کنید.
.TP
.B پیشوند سبک الگو \fBP\fP (تنها در پرونده‌های الگو کاربرد دارد)
برای تغییر سبک پیش‌فرض الگو، از پیشوند \fBP\fP به همراه شناسه مختصر سبک الگو (\fBfm\fP، \fBpf\fP، \fBpp\fP، \fBre\fP، \fBsh\fP) استفاده کنید. تمامی الگوهای پس از این سطر در همان پرونده از این سبک استفاده خواهند کرد تا زمانی که سبک دیگری تعیین شود یا پرونده پایان یابد. با پایان یافتن پرونده الگو، سبک الگو به پیش‌فرض بازمی‌گردد.
.TP
.B پیشوند الگوی استثنا \fB\-\fP
از پیشوند \fB\-\fP و در ادامه یک الگو برای تعریف یک استثنا استفاده کنید. این کار اثری مشابه گزینه \fB\-\-exclude\fP دارد.
.TP
.B پیشوند الگوی استثنای بدون بازگشت \fB!\fP
از پیشوند \fB!\fP و در ادامه یک الگو برای تعریف استثنایی استفاده کنید که وارد زیرشاخه‌ها نمی‌شود. این کار در زمان صرفه‌جویی می‌کند، اما مانع از تطبیق الگوهای شمول روی پرونده‌های درون زیرشاخه‌ها می‌شود.
.TP
.B پیشوند الگوی شمول \fB+\fP
از پیشوند \fB+\fP و در ادامه یک الگو برای تعریف موارد شمول استفاده کنید. این قابلیت برای گنجاندن مسیرهایی کاربرد دارد که تحت پوشش الگوی استثنا قرار گرفته‌اند و در غیر این صورت پشتیبان‌گیری نمی‌شدند.
.UNINDENT
.sp
\fBنکته:\fP
.INDENT 0.0
.INDENT 3.5
از طریق \fB\-\-pattern\fP یا \fB\-\-patterns\-from\fP می‌توانید با پیشوندهای \fB+\fP و \fB\-\fP هم شمول و هم استثنای پرونده‌ها را تعریف کنید. در حالی که با \fB\-\-exclude\fP و \fB\-\-exclude\-from\fP تنها استثناها تعریف می‌شوند.
.UNINDENT
.UNINDENT
.sp
نخستین الگوی منطبق اعمال می‌شود؛ بنابراین اگر یک الگوی شمول پیش از یک الگوی استثنا تطبیق یابد، از پرونده پشتیبان تهیه می‌شود. توجه داشته باشید که استثنای بدون بازگشت بررسی زیرشاخه‌ها را متوقف می‌کند به گونه‌ای که موارد شمول احتمالی درون آن‌ها نیز تطبیق نخواهند یافت؛ برای چنین مواردی از استثناهای عادی استفاده کنید.
.sp
مثال:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# تعریف ریشه بازگشت
R /
# استثنا کردن تمام پرونده‌های iso در هر شاخه‌ای
\- **/*.iso
# شمول صریح تمام محتویات etc و root
+ etc/**
+ root/**
# استثنا کردن شاخه‌ای مشخص در شاخه خانگی هر کاربر
\- home/*/.cache
# شمول صریح تمام محتویات /home
+ home/**
# استثنای صریح برخی شاخه‌ها بدون پیمایش زیرشاخه‌های آنها
! re:^(dev|proc|run|sys|tmp)
# استثنا کردن سایر پرونده‌ها و شاخه‌ها
# که پیش‌تر به صورت صریح گنجانده نشده‌اند.
\- **
.EE
.UNINDENT
.UNINDENT
.sp
\fBنکته:\fP
.INDENT 0.0
.INDENT 3.5
این احتمال وجود دارد که یک زیرشاخه یا پرونده تطبیق یابد در حالی که شاخه‌های والد آن مطابقت نیافته باشند. در این صورت، از شاخه‌های والد پشتیبان گرفته نمی‌شود، بنابراین کاربر، گروه، مجوزها و سایر ویژگی‌های آن‌ها قابل بازیابی نخواهد بود.
.UNINDENT
.UNINDENT
.sp
توجه داشته باشید که سبک پیش‌فرض الگو برای \fB\-\-pattern\fP و \fB\-\-patterns\-from\fP سبک پوسته (\fIsh:\fP) است، بنابراین عملکرد آن‌ها مشابه الگوهای include/exclude در rsync است. این سبک با پیشوند \fIP\fP قابل تنظیم است.
.sp
الگوها (\fB\-\-pattern\fP) و استثناها (\fB\-\-exclude\fP) از خط فرمان اولویت اول را دارند (به ترتیبی که وارد شده‌اند). سپس الگوهای برگرفته از \fB\-\-patterns\-from\fP اضافه می‌شوند. در نهایت، الگوهای استثنای پرونده‌های \fB\-\-exclude\-from\fP اضافه می‌گردند.
.sp
مثال‌ها:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# پشتیبان‌گیری از تصاویر، به جز موارد سال ۲۰۱۸، مگر عکس‌های منتخب:
# توجه: استفاده از = برای جلوگیری از مشکلات پردازش آرگومان خط فرمان ضروری است.
borg create \-\-pattern=+pics/2018/good \-\-pattern=\-pics/2018 repo::arch pics

# استفاده از پرونده حاوی الگوها:
borg create \-\-patterns\-from patterns.lst repo::arch
.EE
.UNINDENT
.UNINDENT
.sp
پرونده patterns.lst می‌تواند به شکل زیر باشد:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# سبک "sh:" پیش‌فرض است، بنابراین سطر زیر الزامی نیست:
P sh
R /
# می‌توان مجدداً ایجاد کرد
\- home/*/.cache
# بارگیری‌ها نیازی به پشتیبان ندارند
\- home/*/Downloads
# سوزان کاربر مهمی است
# خانه سوزان گنجانده شود
+ home/susan
# همچنین این پرونده خاص پشتیبان‌گیری شود
+ pf:home/bobby/specialfile.txt
# از شاخه‌های خانگی سایر کاربران پشتیبان گرفته نشود
\- home/*
# اصلاً مسیر proc/ بررسی نشود
! proc
.EE
.UNINDENT
.UNINDENT
.sp
می‌توانید ریشه‌های بازگشت را در خط فرمان یا درون یک پرونده الگو مشخص کنید:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# این دو دستور عملکرد یکسانی دارند
borg create \-\-exclude home/bobby/junk repo::arch /home/bobby /home/susan
borg create \-\-patterns\-from patternfile.lst repo::arch
.EE
.UNINDENT
.UNINDENT
.sp
نمونه پرونده الگو:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# توجه داشته باشید excludes به طور پیش‌فرض از fm: و پرونده‌های الگو از sh: استفاده می‌کنند.
# بنابراین برای داشتن رفتار کاملاً یکسان باید fm: را صریحاً ذکر کنیم.
P fm
R /home/bobby
R /home/susan

\- home/bobby/junk
.EE
.UNINDENT
.UNINDENT
.sp
این قابلیت به شما امکان می‌دهد الگوهای یکسانی را بدون نیاز به بازنویسی در خط فرمان، میان چندین مخزن مختلف به اشتراک بگذارید.
.SH "نویسنده (AUTHOR)"
The Borg Collective
.\" End of generated man page.