.\" 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-create" "1" "2026-07-18" "" "ابزار پشتیبان‌گیری borg"
.SH "نام (NAME)"
borg-create \- ایجاد یک آرشیو جدید
.SH "خلاصه دستور (SYNOPSIS)"
.sp
borg [گزینه‌های عمومی] create [گزینه‌ها] ARCHIVE [PATH...]
.SH "توضیحات (DESCRIPTION)"
.sp
این دستور یک آرشیو پشتیبان شامل تمامی فایل‌های یافت‌شده حین پیمایش بازگشتی مسیرهای مشخص‌شده ایجاد می‌کند. مسیرها همان‌طور که مشخص شده‌اند به آرشیو اضافه می‌شوند، به این معنی که اگر مسیرهای نسبی مد نظر باشد، دستور باید از پوشه صحیح اجرا شود.
.sp
شگرد نقطه‌اسلش در مسیرها (ریشه‌های بازگشتی) با استفاده از \fB/./\fP فعال می‌شود:
\fB/this/gets/stripped/./this/gets/archived\fP به معنای پردازش آن شیء در سیستم‌فایل است، اما پیشوند سمت چپ \fB\&./\fP از موارد آرشیوشده حذف خواهد شد (در این حالت، \fBthis/gets/archived\fP مسیر شیء در آرشیو خواهد بود).
.sp
هنگام مشخص کردن '-' به عنوان مسیر، Borg داده‌ها را از ورودی استاندارد می‌خواند و فایلی با نام 'stdin' در آرشیو ایجاد می‌کند. در برخی موارد استفاده از \fB\-\-content\-from\-command\fP مناسب‌تر است. برای جزئیات به بخش "خواندن از stdin" در زیر مراجعه کنید.
.sp
آرشیو برای فایل‌ها یا بخش‌هایی از فایل‌ها که قبلاً در آرشیوهای دیگر ذخیره شده‌اند، تقریباً هیچ فضای دیسکی مصرف نمی‌کند.
.sp
نام آرشیو باید یکتا باشد. نباید به '.checkpoint' یا '.checkpoint.N' (که N عدد است) ختم شود، زیرا این نام‌ها برای نقاط بازرسی استفاده شده و رفتار ویژه‌ای با آن‌ها می‌شود.
.sp
در نام آرشیو می‌توانید از جانگهدارنده‌های زیر استفاده کنید:
{now}، {utcnow}، {fqdn}، {hostname}، {user} و چند مورد دیگر.
.sp
سرعت پشتیبان‌گیری با پردازش نکردن مجدد فایل‌هایی که قبلاً در آرشیوهای موجود ذخیره شده‌اند و تغییر نکرده‌اند، افزایش می‌یابد. تشخیص فایل‌های تغییرنیافته با مقایسه فراداده‌های فایل با مقادیر قبلی موجود در حافظه پنهان فایل‌ها انجام می‌شود.
.sp
این مقایسه می‌تواند در حالت‌های مختلفی که با \fB\-\-files\-cache\fP مشخص می‌شود عمل کند:
.INDENT 0.0
.IP \(bu 2
ctime,size,inode (پیش‌فرض)
.IP \(bu 2
mtime,size,inode (رفتار پیش‌فرض در نسخه‌های قدیمی‌تر از 1.1.0rc4)
.IP \(bu 2
ctime,size (نادیده گرفتن شماره inode)
.IP \(bu 2
mtime,size (نادیده گرفتن شماره inode)
.IP \(bu 2
rechunk,ctime (همه فایل‌ها تغییریافته تلقی می‌شوند \- قطعه‌بندی مجدد، ذخیره ctime در کش)
.IP \(bu 2
rechunk,mtime (همه فایل‌ها تغییریافته تلقی می‌شوند \- قطعه‌بندی مجدد، ذخیره mtime در کش)
.IP \(bu 2
disabled (غیرفعال‌سازی کش فایل‌ها، همه فایل‌ها تغییریافته تلقی می‌شوند \- قطعه‌بندی مجدد)
.UNINDENT
.sp
شماره inode: ایمنی بیشتر، اما اغلب ناپایدار در سیستم‌فایل‌های شبکه‌ای
.sp
در حالت عادی، تشخیص تغییر فایل‌ها اطلاعات inode را در نظر می‌گیرد تا دقت تشخیص بهبود یابد. این مورد برای فایل‌های روی SSHFS و سیستم‌های فایل شبکه‌ای مشابه که شماره inode پایداری ارائه نمی‌دهند مشکل‌ساز است؛ چنین فایل‌هایی همیشه تغییریافته تلقی خواهند شد. در این موارد می‌توانید از حالت‌های بدون \fIinode\fP برای بهبود کارایی استفاده کنید، اما قابلیت اطمینان تشخیص ممکن است کاهش یابد.
.sp
مقایسه ctime در برابر mtime: ایمنی در برابر سرعت
.INDENT 0.0
.IP \(bu 2
مقدار ctime روشی کاملاً ایمن برای تشخیص تغییرات فایل (فراداده و محتوا) است زیرا نمی‌توان آن را از فضای کاربری تغییر داد. با این حال، حتی تغییر در فراداده نیز ctime را به‌روز می‌کند، بنابراین ممکن است حتی بدون تغییر محتوا قطعه‌بندی/درهم‌سازی غیرضروری انجام شود. برخی سیستم‌های فایل از ctime پشتیبانی نمی‌کنند. برای مثال، دستور chown یا chmod روی یک فایل، ctime آن را تغییر می‌دهد.
.IP \(bu 2
مقدار mtime معمولاً به درستی کار می‌کند و تنها در صورت تغییر محتوای فایل به‌روز می‌شود. اما mtime می‌تواند به دلخواه از فضای کاربری تنظیم شود، مثلاً برای بازگرداندن mtime به همان مقداری که قبل از تغییر محتوا داشت. این مورد می‌تواند برای اهداف مخرب یا حتی کاربردهای عادی استفاده شود، اما در هر دو حالت حالت‌های کش مبتنی بر mtime می‌توانند مشکل‌ساز باشند.
.UNINDENT
.sp
گزینه \fB\-\-files\-changed\fP کنترل می‌کند که Borg چگونه تغییر فایل را در طول پشتیبان‌گیری تشخیص دهد:
.INDENT 0.0
.IP \(bu 2
ctime (پیش‌فرض): استفاده از ctime برای تشخیص تغییرات. این ایمن‌ترین گزینه است.
.IP \(bu 2
mtime: استفاده از mtime برای تشخیص تغییرات.
.IP \(bu 2
disabled: غیرفعال‌سازی کامل تشخیص تغییر فایل در طول پشتیبان‌گیری. این گزینه توصیه نمی‌شود مگر اینکه بدانید چه می‌کنید، زیرا در صورت تغییر فایل‌ها در حین فرایند پشتیبان‌گیری می‌تواند منجر به ناسازگاری آرشیو شود.
.UNINDENT
.sp
نقاط اتصال سیستم‌های فایل یا عکس‌های لحظه‌ای (snapshots) باید برای هر بار ایجاد آرشیو جدید یکسان باشد تا عملیات سریع تضمین شود، زیرا حافظه پنهان فایل از نام‌های مطلق فایل استفاده می‌کند. اگر این امر امکان‌پذیر نیست، استفاده از bind mount در یک مکان پایدار را در نظر بگیرید.
.sp
گزینه \fB\-\-progress\fP مقادیر داده اصلی، فشرده‌شده و یکتاشده (به ترتیب با حروف O، C و D)، سپس تعداد فایل‌های پردازش‌شده (N) و پس از آن مسیر فعلی در حال پردازش را نمایش می‌دهد.
.sp
هنگام استفاده از \fB\-\-stats\fP آماری درباره میزان داده‌های اضافه‌شده دریافت خواهید کرد \- اندازه یکتاشده در بخش "This Archive" مهم‌ترین است زیرا نشان می‌دهد مخزن چقدر رشد خواهد کرد. گزینه \fB\-\-quick\-stats\fP سریع‌تر است زیرا از آمار سرتاسری مخزن صرف‌نظر می‌کند. گزینه‌های \fB\-\-stats\fP یا \fB\-\-quick\-stats\fP با \fB\-\-dry\-run\fP ناسازگار هستند زیرا در اجرای آزمایشی فشرده‌سازی و حذف داده‌های تکراری انجام نمی‌شود.
.sp
برای راهنمایی بیشتر درباره الگوها، خروجی دستور \fIborg_patterns\fP را ببینید.
.sp
برای راهنمایی بیشتر درباره جانگهدارنده‌ها، خروجی دستور \fIborg_placeholders\fP را ببینید.
.SH "گزینه‌ها (OPTIONS)"
.sp
برای گزینه‌های عمومی دستورات Borg به \fIborg\-common(1)\fP مراجعه کنید.
.SS "آرگومان‌ها (arguments)"
.INDENT 0.0
.TP
.B ARCHIVE
نام آرشیو جهت ایجاد (باید یک نام پوشه معتبر نیز باشد)
.TP
.B PATH
مسیرها برای آرشیو کردن
.UNINDENT
.SS "گزینه‌ها (options)"
.INDENT 0.0
.TP
.B  \-n\fP,\fB  \-\-dry\-run
آرشیو پشتیبان ایجاد نشود (اجرای آزمایشی)
.TP
.B  \-s\fP,\fB  \-\-stats
چاپ آمار مربوط به آرشیو ایجادشده
.TP
.B  \-\-quick\-stats
چاپ تنها آمار آرشیو بدون محاسبه آمار سرتاسری مخزن
.TP
.B  \-\-list
خروجی مشروح از موارد پردازش‌شده (فایل‌ها، پوشه‌ها، ...)
.TP
.BI \-\-filter \ STATUSCHARS
فقط نمایش مواردی با نویسه‌های وضعیت مشخص‌شده (توضیحات را ببینید)
.TP
.B  \-\-json
خروجی آمار در قالب JSON (به همراه \fB\-\-stats\fP)
.TP
.B  \-\-no\-cache\-sync
آزمایشی: هماهنگ‌سازی حافظه پنهان انجام نشود. به معنی عدم استفاده از کش فایل‌هاست.
.TP
.BI \-\-stdin\-name \ NAME
استفاده از NAME در آرشیو برای داده‌های ورودی استاندارد (پیش‌فرض: 'stdin')
.TP
.BI \-\-stdin\-user \ USER
تنظیم کاربر USER در آرشیو برای داده‌های ورودی استاندارد (پیش‌فرض: 'root')
.TP
.BI \-\-stdin\-group \ GROUP
تنظیم گروه GROUP در آرشیو برای داده‌های ورودی استاندارد (پیش‌فرض: 'wheel')
.TP
.BI \-\-stdin\-mode \ M
تنظیم سطح دسترسی M در آرشیو برای داده‌های stdin (پیش‌فرض: 0660)
.TP
.B  \-\-content\-from\-command
تفسیر PATH به عنوان دستور و ذخیره خروجی استاندارد آن
.TP
.B  \-\-paths\-from\-stdin
خواندن فهرست مسیرهای جداشده با جداکننده از stdin
.TP
.B  \-\-paths\-from\-command
تفسیر PATH به عنوان دستور و رفتار با خروجی آن همانند \fB\-\-paths\-from\-stdin\fP
.TP
.BI \-\-paths\-delimiter \ DELIM
تنظیم جداکننده مسیر برای \fB\-\-paths\-from\-stdin\fP و \fB\-\-paths\-from\-command\fP (پیش‌فرض: خط جدید)
.UNINDENT
.SS "گزینه‌های گنجاندن/استثنا کردن (Include/Exclude options)"
.INDENT 0.0
.TP
.BI \-e \ PATTERN\fR,\fB \ \-\-exclude \ PATTERN
مستثنی کردن مسیرهای منطبق با PATTERN
.TP
.BI \-\-exclude\-from \ EXCLUDEFILE
خواندن الگوهای استثنا از EXCLUDEFILE (هر خط یک الگو)
.TP
.BI \-\-pattern \ PATTERN
گنجاندن یا استثنا کردن مسیرهای منطبق با PATTERN
.TP
.BI \-\-patterns\-from \ PATTERNFILE
خواندن الگوهای گنجاندن/استثنا از PATTERNFILE
.TP
.B  \-\-exclude\-caches
مستثنی کردن پوشه‌های دارای فایل CACHEDIR.TAG
.TP
.BI \-\-exclude\-if\-present \ NAME
مستثنی کردن پوشه‌هایی که شیئی با نام NAME دارند
.TP
.B  \-\-keep\-exclude\-tags
در صورت استفاده از \-\-exclude\-if\-present، خود شیء نشانه‌گذاری‌شده در آرشیو نگهداری شود
.TP
.B  \-\-exclude\-nodump
مستثنی کردن فایل‌های دارای نشان NODUMP
.TP
.B  \-\-exclude\-dataless
مستثنی کردن فایل‌های نشانه‌گذاری‌شده به عنوان DATALESS (در macOS)
.UNINDENT
.SS "گزینه‌های سیستم‌فایل (Filesystem options)"
.INDENT 0.0
.TP
.B  \-x\fP,\fB  \-\-one\-file\-system
عدم خروج از سیستم‌فایل جاری و نادیده گرفتن نقاط اتصال سیستم‌فایل‌های دیگر
.TP
.B  \-\-numeric\-owner
منسوخ‌شده، از \fB\-\-numeric\-ids\fP استفاده کنید
.TP
.B  \-\-numeric\-ids
تنها ذخیره شناسه‌های عددی کاربر و گروه
.TP
.B  \-\-noatime
عدم ذخیره زمان دسترسی (atime) در آرشیو
.TP
.B  \-\-atime
ذخیره زمان دسترسی (atime) در آرشیو
.TP
.B  \-\-noctime
عدم ذخیره ctime در آرشیو
.TP
.B  \-\-nobirthtime
عدم ذخیره زمان ایجاد (birthtime) در آرشیو
.TP
.B  \-\-nobsdflags
منسوخ‌شده، از \fB\-\-noflags\fP استفاده کنید
.TP
.B  \-\-noflags
عدم خواندن و ذخیره پرچم‌های فایل (مانند NODUMP یا IMMUTABLE)
.TP
.B  \-\-noacls
عدم خواندن و ذخیره فهرست‌های کنترل دسترسی (ACL)
.TP
.B  \-\-noxattrs
عدم خواندن و ذخیره ویژگی‌های توسعه‌یافته (xattrs)
.TP
.B  \-\-sparse
تشخیص حفره‌های فایل خلوت (sparse holes)
.TP
.BI \-\-files\-cache \ MODE
تنظیم حالت حافظه پنهان فایل‌ها (پیش‌فرض: ctime,size,inode)
.TP
.BI \-\-files\-changed \ MODE
تعیین نحوه تشخیص تغییر فایل در حین پشتیبان‌گیری (پیش‌فرض: ctime)
.TP
.B  \-\-read\-special
خواندن فایل‌های دستگاهی بلوکی و نویسه‌ای و FIFOها همانند فایل‌های عادی
.UNINDENT
.SS "گزینه‌های آرشیو (Archive options)"
.INDENT 0.0
.TP
.BI \-\-comment \ COMMENT
افزودن یادداشت متنی به آرشیو
.TP
.BI \-\-timestamp \ TIMESTAMP
تنظیم دستی زمان ایجاد آرشیو (قالب UTC یا یک فایل مرجع)
.TP
.BI \-c \ SECONDS\fR,\fB \ \-\-checkpoint\-interval \ SECONDS
نوشتن نقطه بازرسی در هر فواصل ثانیه‌ای مشخص (پیش‌فرض: ۱۸۰۰)
.TP
.BI \-\-chunker\-params \ PARAMS
مشخص کردن پارامترهای قطعه‌بندی (الگوریتم، حداقل، حداکثر، بیت‌های ماسک و اندازه پنجره)
.TP
.BI \-C \ COMPRESSION\fR,\fB \ \-\-compression \ COMPRESSION
انتخاب الگوریتم فشرده‌سازی
.UNINDENT
.SH "مثال‌ها (EXAMPLES)"
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# پشتیبان‌گیری از ~/Documents در آرشیوی به نام "my-documents"
$ borg create /path/to/repo::my\-documents ~/Documents

# پشتیبان‌گیری به همراه فهرست کردن فایل‌ها در حین پردازش
$ borg create \-\-list /path/to/repo::my\-documents ~/Documents

# پشتیبان‌گیری و حذف پیشوند مسیر با شگرد نقطه‌اسلش
$ borg create /path/to/repo::docs /mnt/disk/./docs

# پشتیبان‌گیری و مستثنی کردن فایل‌های pyc
$ borg create /path/to/repo::my\-files \e
    ~/Documents                       \e
    ~/src                             \e
    \-\-exclude \(aq*.pyc\(aq

# پشتیبان‌گیری از ریشه سیستم‌فایل و استفاده از فشرده‌سازی zlib
$ borg create \-C zlib,6 \-\-one\-file\-system /path/to/repo::root\-{now:%Y\-%m\-%d} /

# پشتیبان‌گیری به سمت سرور دوردست از طریق SSH
$ borg create ssh://borg@backup.example.org:2222/path/to/repo::{fqdn}\-root\-{now} /

# پشتیبان‌گیری بدون فشرده‌سازی
$ borg create \-\-compression none /path/to/repo::arch ~

# پشتیبان‌گیری با فشرده‌سازی پیش‌فرض و بسیار سریع (lz4)
$ borg create /path/to/repo::arch ~

# فشرده‌سازی قوی‌تر با lzma
$ borg create \-\-compression lzma,9 /path/to/repo::arch ~

# استفاده از خروجی find برای انتخاب فایل‌ها
$ find ~ \-size \-1000k | borg create \-\-paths\-from\-stdin /path/to/repo::small\-files\-only
.EE
.UNINDENT
.UNINDENT
.SH "یادداشت‌ها (NOTES)"
.sp
الگوهای \fB\-\-exclude\fP با دستور tar متفاوت است؛ برای نمونه باید از \fB\-\-exclude\fP '*/.bundler/gems' برای تطبیق مسیرها استفاده کنید.
.sp
گزینه \fB\-x\fP یا \fB\-\-one\-file\-system\fP پوشه‌هایی را که نقاط اتصال سیستم‌فایل‌های دیگر هستند مستثنی می‌کند. این کار با مقایسه شماره دستگاه در خروجی دستور stat انجام می‌شود.
.SS "مدیریت خطا (Error handling)"
.sp
هنگامی که Borg با فایلی مواجه می‌شود که قابل خواندن نیست (مثلاً عدم دسترسی)، پیامی هشدار در لاگ ثبت می‌کند، از آن فایل صرف‌نظر کرده و به کار ادامه می‌دهد و در پایان با کد هشدار خارج می‌شود تا یک فایل مانع کل پشتیبان‌گیری نشود.
.SS "پرچم‌های وضعیت موارد (Item flags)"
.sp
در خروجی \fB\-\-list\fP حروف زیر نشان‌دهنده وضعیت فایل هستند:
.INDENT 0.0
.IP \(bu 2
'A' = فایل عادی، اضافه‌شده (Added)
.IP \(bu 2
'M' = فایل عادی، تغییریافته (Modified)
.IP \(bu 2
'U' = فایل عادی، بدون تغییر (Unchanged)
.IP \(bu 2
'C' = فایل عادی، در حین پشتیبان‌گیری تغییر کرد
.IP \(bu 2
'E' = بروز خطا هنگام دسترسی به این فایل
.UNINDENT
.sp
نویسه‌های کوچک نشان‌دهنده سایر انواع شیء هستند:
'd' برای پوشه، 'b' دستگاه بلوکی، 'c' دستگاه نویسه‌ای، 'h' پیوند سخت، 's' پیوند نمادین و 'f' برای لوله FIFO.
.SS "خواندن داده‌های پشتیبان از stdin"
.sp
می‌توان مسیر را '-' تعیین کرده و مستقیماً داده را پایپ کرد یا از \fB\-\-content\-from\-command\fP استفاده نمود که تضمین می‌کند در صورت شکست دستور تولیدکننده داده، آرشیو ناقص ساخته نشود.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fIborg\-common(1)\fP, \fIborg\-delete(1)\fP, \fIborg\-prune(1)\fP, \fIborg\-check(1)\fP, \fIborg\-patterns(1)\fP, \fIborg\-placeholders(1)\fP, \fIborg\-compression(1)\fP
.SH "نویسندگان (Author)"
The Borg Collective