نام (NAME)

bup-get - کپی کردن یا دانلود زیرمجموعه‌ای از مخزن bup

خلاصه دستور (SYNOPSIS)

bup get [-s source-path] [-r host:path] OPTIONS <(METHOD ref [dest])>...

توضیحات (DESCRIPTION)

دستور bup get مراجع مشخص‌شده (refها) را از مخزن مبدأ به مخزن مقصد (با رعایت --bup-dir و BUP_DIR)، بر اساس METHOD مشخص‌شده منتقل می‌کند؛ این METHOD می‌تواند یکی از موارد --ff، --ff:، --append، --append:، --pick، --pick:، --force-pick، --force-pick:، --new-tag، --new-tag:، --replace، --replace: یا --unnamed باشد. به‌طور پیش‌فرض، داده‌ها را بدون تغییر کپی می‌کند (--copy)، اما همچنین می‌تواند آن‌ها را بازنویسی کند (--rewrite) که احتمالاً دانه‌بندی یکتاسازی (deduplication granularity) را تغییر می‌دهد، و برخی از انواع آسیب‌ها را تعمیر کند (--repair). برای آشنایی سریع، بخش «مثال‌ها» در زیر را ببینید.

مقدار ref مرجع شیء مورد نظر برای دریافت در مخزن مبدأ است، و dest مرجع اختیاری در مقصد است. مقدار dest تنها می‌تواند برای METHODهایی مشخص شود که نام آن‌ها با دونقطه پایان می‌یابد. برای مثال:

bup get -s /source/repo --ff foo
bup get -s /source/repo --ff: foo/latest bar
bup get -s /source/repo --pick: foo/2010-10-10-101010 bar
bup get -s /source/repo --pick: foo/2010-10-10-101010 .tag/bar

رفتار هر METHOD مشخص تا حدی بر اساس انواع ref و dest تعیین می‌شود، یعنی شاخه (branch)، ذخیره (save)، برچسب (tag) و غیره.

به‌عنوان یک حالت خاص، اگر ref به پیوند نمادین ذخیره “latest” اشاره کند، bup دقیقاً به گونه‌ای عمل می‌کند که گویی به ذخیره‌ای که “latest” به آن اشاره دارد ارجاع داده شده است، نه به خود پیوند نمادین “latest”؛ بنابراین bup get foo/latest در عمل به چیزی مانند bup get foo/2013-01-01-030405 تفسیر خواهد شد.

در برخی شرایط، bup get یک عملیات شاخه را بر این اساس ارزیابی می‌کند که آیا یک «انتقال سریع به جلو» (“fast-forward”) خواهد بود یا خیر (که مستلزم آن است که هر شاخه موجود در مقصد، نیای شاخه مبدأ باشد).

یک برچسب موجود در مقصد تنها می‌تواند توسط --replace یا --force-pick بازنویسی شود.

هنگامی که یک کامیت جدید ایجاد می‌شود (یعنی از طریق --append، --pick و غیره)، همان پدیدآورنده (author)، تاریخ پدیدآورنده و پیام کامیت اصلی را خواهد داشت، اما ثبت‌کننده (committer) و تاریخ ثبت آن مربوط به کاربر فعلی و زمان کنونی خواهد بود.

اگر از طریق گزینه‌های مربوطه درخواست شود، bup هش کامیت، درخت (tree) یا برچسب را برای هر ارجاع به‌روزشده در مقصد چاپ می‌کند. در صورت لزوم، هش درخت پیش از هش کامیت چاپ خواهد شد.

مراجع محلی (refها) را می‌توان با گزینه --remote به یک مخزن دوردست ارسال کرد، و مراجع دوردست را می‌توان از طریق دستور «“bup on HOST get ...”» به مخزن محلی دریافت نمود. برای اطلاعات بیشتر، bup-on(1) و بخش «مثال‌ها» در زیر را ببینید.

هشدار: این یکی از معدود دستورات bup است که می‌تواند آرشیوهای شما را به شیوه‌های مخربِ عمدی تغییر دهد. با این وجود، اگر پس از اجرای این دستور، تلاش برای اتصال (join) یا بازیابی داده‌هایی که همچنان برایتان اهمیت دارند موفقیت‌آمیز باشد، نشانه بسیار امیدوارکننده‌ای است که دستور به درستی کار کرده است. (دستور dev/compare-trees در درخت مبدأ می‌تواند برای کمک به بررسی نتایج قبل و بعد استفاده شود.)

روش‌ها (METHODS)

--ff ref, --ff: ref dest

انتقال سریع به جلو (fast-forward) ارجاع dest برای تطبیق با ref. اگر dest مشخص نشده باشد و ref نام یک ذخیره (save) باشد، مقدار dest روی شاخه مربوط به آن ذخیره تنظیم می‌شود. اگر dest مشخص نشده باشد و ref نام یک شاخه یا برچسب باشد، از همان نام برای dest استفاده می‌شود.

--append ref, --append: ref dest

افزودن تمام کامیت‌های ارائه‌شده توسط ref به انتهای dest به‌عنوان کامیت‌های جدید. اگر ref نام یک پوشه/درخت باشد، یک کامیت جدید برای آن درخت اضافه می‌کند. اگر dest مشخص نشده باشد و ref نام یک ذخیره یا شاخه باشد، مقدار dest روی نام شاخه ref تنظیم می‌شود. اگر dest مشخص نشده باشد و ref نام یک برچسب باشد، از همان نام برای dest استفاده می‌شود.

--pick ref, --pick: ref dest

افزودن تک‌کامیت مشخص‌شده با ref به dest به‌عنوان یک کامیت جدید. اگر dest مشخص نشده باشد و ref نام یک ذخیره باشد، مقدار dest روی نام شاخه ref تنظیم می‌شود. اگر dest مشخص نشده باشد و ref نام یک برچسب باشد، از همان نام برای dest استفاده می‌شود.

--force-pick ref, --force-pick: ref dest

همان عملیات --pick را انجام می‌دهد، با این تفاوت که از بازنویسی برچسب موجود امتناع نمی‌کند، و اگر برچسب به یک کامیت اشاره داشته باشد، آن را والد (parent) ارجاع ref قرار می‌دهد.

--new-tag ref, --new-tag: ref dest

ایجاد یک برچسب dest برای ref، با این تفاوت که از بازنویسی برچسب موجود خودداری می‌کند. اگر dest مشخص نشده باشد و ref نام یک برچسب باشد، از همان نام برای dest استفاده می‌شود.

--replace ref, --replace: ref dest

جایگزینی کامل dest با ref، رونویسی هر برچسب موجود یا جایگزین کردن هر شاخه موجود. اگر dest مشخص نشده باشد و ref نام یک شاخه یا برچسب باشد، از همان نام برای dest استفاده می‌شود.

--unnamed ref

کپی کردن ref به مخزن مقصد، بدون هیچ نامی، که یک ارجاع بالقوه معلق باقی می‌گذارد مگر آن‌که/تا زمانی که شیء مشخص‌شده با ref به روش دیگری مورد ارجاع قرار گیرد (مقایسه کنید با bup tag). در حال حاضر تنها با گزینه --copy سازگار است.

گزینه‌ها (OPTIONS)

-s path, -S url, --source path, --source-url url*

استفاده از path یا url به‌عنوان مخزن مبدأ، به‌جای مقدار پیش‌فرض. برای اطلاعات بیشتر، به بخش «REPOSITORY URLS» در bup(1) مراجعه کنید.

-r, --remote=[user@]host:[path], --remote=URL

نوشتن مراجع ref در مخزن دوردست مشخص‌شده، که به‌طور پیش‌فرض از طریق SSH انجام می‌شود. برای اطلاعات بیشتر، به بخش «REMOTE OPTIONS» در bup(1) مراجعه کنید.

-c, --print-commits

برای هر شاخه به‌روزشده، شناسه کامیت گیت جدید را چاپ می‌کند.

-t, --print-trees

برای هر شاخه به‌روزشده، شناسه درخت گیت جدید از ریشه فایل‌سیستم را چاپ می‌کند.

--print-tags

برای هر برچسب به‌روزشده، شناسه گیت جدید را چاپ می‌کند.

--copy

کپی کردن داده‌ها بدون تغییر (یعنی بدون بازنویسی یا تعمیرات). این مقدار پیش‌فرض است.

--rewrite

بازنویسی داده‌ها بر اساس پیکربندی مخزن مقصد، برای نمونه مقادیر bup.split.files و bup.split.trees آن. برخی از تعمیرات جزئی ممکن است در حین انتقال انجام شوند، مادامی که نتیجه را از نظر بنیادی تغییر ندهند (به بخش «تعمیرات» در زیر مراجعه کنید). در حال حاضر، هرگاه پیکربندی مخزن مبدأ و مقصد به شیوه‌ای مرتبط تفاوت داشته باشد، باید یکی از گزینه‌های --rewrite، --repair یا --copy مشخص شود، و تا کنون، --rewrite تنها برای موارد الحاق (append) و انتخاب (pick) در ذخیره‌ها (و نه درخت‌ها) پشتیبانی می‌شود.

--repair

علاوه بر آنچه --rewrite انجام می‌دهد، تمام تعمیرات شناخته‌شده را در حین انتقال انجام می‌دهد. به بخش «تعمیرات» در زیر مراجعه کنید. این گزینه زمینه‌ای است (به بخش «گزینه‌های زمینه‌ای» مراجعه کنید).

--repair-id ID

شناسه نشست تعمیر را مشخص می‌کند که پیش‌فرض آن یک UUID (نسخه ۴) است. این شناسه در هر یک از تعمیرات (--repair) انجام‌شده در طول انتقال گنجانده خواهد شد. در حال حاضر، شناسه باید از نوع ASCII باشد و نویسه‌های کنترلی یا DEL را شامل نشود (یعنی باید از بایت‌های >= 20 و < 127 تشکیل شده باشد). این گزینه زمینه‌ای است (به بخش «گزینه‌های زمینه‌ای» مراجعه کنید).

--ignore-missing

نادیده گرفتن اشیاء مفقودشده که در طول انتقال با آن‌ها مواجه می‌شوید. در حال حاضر تنها توسط --unnamed پشتیبانی می‌شود و بالقوه خطرناک است.

--exclude-rx=pattern

مستثنی کردن هر مسیری که با الگوی pattern مطابقت داشته باشد، که باید یک عبارت منظم پایتون باشد (http://docs.python.org/library/re.html). الگو با کل مسیر و بدون مهار (anchoring) مقایسه می‌شود، بنابراین «“x/y”» با «“ox/yard”» یا «“box/yards”» مطابقت خواهد داشت. برای مستثنی کردن محتویات /tmp بدون مستثنی کردن خود دایرکتوری، از «“^/tmp/.”» استفاده کنید. (می‌تواند تکرار شود)

--exclude-rx-from=filename

خواندن الگوهای --exclude-rx از filename، هر الگو در یک خط (می‌تواند تکرار شود). خطوط کاملاً خالی نادیده گرفته می‌شوند. تنها هنگام بازنویسی پشتیبانی می‌شود. این گزینه زمینه‌ای است (به بخش «گزینه‌های زمینه‌ای» مراجعه کنید).

--no-excludes

نادیده گرفتن و فراموش کردن هر یک از گزینه‌های قبلی --exclude-rx یا --exclude-rx-from. این گزینه زمینه‌ای است (به بخش «گزینه‌های زمینه‌ای» مراجعه کنید).

-v, --verbose

افزایش سطح گزارش جزئیات (می‌تواند بیش از یک بار استفاده شود). با -v، نام هر مورد دریافت‌شده چاپ می‌شود، با -vv نام پوشه‌ها افزوده می‌گردد، و با -vvv نام همه فایل‌ها چاپ می‌شود.

--bwlimit=bytes/sec

عدم ارسال بیش از bytes/sec بایت در ثانیه به سرور. این گزینه می‌تواند از اشغال تمام پهنای باند شبکه شما جلوگیری کند. از پسوندهایی مانند k، M یا G به ترتیب برای تعیین مضارب ۱۰۲۴، ۱۰۲۴*۱۰۲۴ و ۱۰۲۴*۱۰۲۴*۱۰۲۴ استفاده کنید.

-#, --compress=#

تنظیم سطح فشرده‌سازی روی # (مقداری از 0 تا 9، که 9 بیشترین فشرده‌سازی و 0 بدون فشرده‌سازی است). پیش‌فرض روی مقادیر پیکربندی‌شده pack.compression یا core.compression، یا مقدار 1 (فشرده‌سازی سریع و سبک) است.

گزینه‌های زمینه‌ای (CONTEXTUAL OPTIONS)

برخی از گزینه‌ها مانند --repair و --ignore-missing می‌توانند در METHODهای مختلف تفاوت داشته باشند، و هر گزینه زمینه را برای METHOD بعدی تغییر می‌دهد. بنابراین می‌توانید دستوری مانند زیر داشته باشید:

bup get ... --ignore-missing --unnamed REF \
    --no-ignore-missing --rewrite --append REF

بدون گزینه --no-ignore-missing این دستور با شکست مواجه می‌شد، چرا که گزینه --ignore-missing با --rewrite ناسازگار است.

تغییر موارد مستثنی‌شده (excludes) فعال کنونی پرهزینه است زیرا در حال حاضر حافظه موقت بازنویسی‌های به‌خاطرسپرده‌شده باید هر زمان که موارد مستثنی‌شده یک METHOD با موارد METHOD قبلی تفاوت داشته باشد، پاک شود.

تعمیرات (REPAIRS)

دستور bup get می‌تواند تعدادی از مشکلات شناخته‌شده را در طول انتقال در صورت درخواست گزینه --repair رفع کند (یا تخفیف دهد)، و زیرمجموعه‌ای از تعمیرات «اتفاقی و جزئی» نیز ممکن است در حین یک --rewrite انجام پذیرد.

• نسخه‌های bup از 0.25 به بعد و قبل از 0.30.1 ممکن است به‌ندرت ورودی‌های فراداده را برای موارد غیرپوشه از دست بدهند (که می‌تواند توسط bup-validate-refs(1) --bupm شناسایی شود). این امر فراداده‌های همه مسیرهای غیرپوشه‌ای دیگر در همان پوشه را غیرقابل‌استفاده (مبهم) می‌سازد. هنگامی که چنین .bupm خلاصه‌شده‌ای شناسایی شود، گزینه --repair تمام ورودی‌های .bupm را به جز ورودی مربوط به خود پوشه، یعنی «“.”»، حذف می‌کند و بنابراین مسیرهای متأثر بیشتر یا تمام فراداده‌های خود (مالکیت، مجوزها، نشان‌های زمانی و غیره) را از دست می‌دهند. این مسیرها در هنگام نمایش، برای نمونه از طریق bup-restore(1)، bup-ls(1) و غیره، دارای مجوزهای محدودکننده خواهند بود (گویی با umask 077 ایجاد شده‌اند).
• استفاده از نسخه‌های bup get یا bup gc قبل از 0.33.5 می‌تواند باعث شود مخازن در نهایت با اشیاء گم‌شده مواجه شوند (که توسط bup-validate-object-links(1) قابل شناسایی است). برای رفع درخت‌های تحت تأثیر، --repair «فایل‌های تعمیر» ساخته‌شده را جایگزین هر مسیری با اشیاء گم‌شده می‌کند. توجه داشته باشید که در حال حاضر هیچ پشتیبانی برای بازیابی بخش‌های آسیب‌ندیده فایل‌های تکه‌شده وجود ندارد؛ کل فایل با یک فایل تعمیر جایگزین می‌شود. این فایل‌های تعمیر شامل --repair-id و اطلاعاتی درباره جایگزینی هستند. پشتیبانی از درخت‌های تکه‌شده پس از برطرف شدن مشکل اضافه شد و بنابراین نباید متأثر شده باشد. برای اطلاعات بیشتر، یادداشت‌های انتشار نسخه 0.33.5 (0.33.5-from-0.33.4.md) را ببینید.

تعمیرات «اتفاقی» نیز ممکن است انجام شود — تعمیراتی که نتیجه را از لحاظ عملکردی تغییر نمی‌دهند. برای نمونه، bup مقاصد پیوندهای نمادین را در دو مکان ثبت می‌کند، اما عموماً تنها به یکی از آن‌ها ارجاع می‌دهد. اگر مکان دیگر مفقود باشد، می‌تواند و باید از مکان اول بازیابی شود.

مثال‌ها (EXAMPLES)

# به‌روزرسانی یا کپی شاخه archives در src-repo به مخزن محلی.
$ bup get -s src-repo --ff archives
# اضافه کردن یک ذخیره خاص archives به شاخه pruned-archives.
$ bup get -s src-repo --pick: archives/2013-01-01-030405 pruned-archives
# به‌روزرسانی یا کپی شاخه archives در remotehost به مخزن محلی.
$ bup on remotehost get --ff archives
# به‌روزرسانی یا کپی شاخه محلی archives به remotehost.
$ bup get -r remotehost: --ff archives
# به‌روزرسانی یا کپی شاخه archives در src-repo به remotehost.
$ bup get -s src-repo -r remotehost: --ff archives
# به‌روزرسانی شاخه archives-2 در remotehost برای تطبیق با archives.
# اگر archives-2 وجود داشته باشد و از نیاکان archives نباشد،
# دستور bup امتناع خواهد کرد.
$ bup get -r remotehost: --ff: archives archives-2
# جایگزینی محتویات شاخه y با محتویات x.
$ bup get --replace: x y
# کپی آخرین ذخیره محلی از شاخه archives به تگ دوردست foo.
$ bup get -r remotehost: --pick: archives/latest .tag/foo
# یا اگر foo از قبل وجود داشته باشد:
$ bup get -r remotehost: --force-pick: archives/latest .tag/foo
# اضافه کردن foo (از بالا) به شاخه محلی other-archives.
$ bup on remotehost get --append: .tag/foo other-archives
# اضافه کردن تنها پوشه /home از archives/latest به only-home.
$ bup get -s "$BUP_DIR" --append: archives/latest/home only-home
# تقسیم مجدد (بازنویسی) شاخه archives. توجه داشته باشید که انجام
# یک‌باره این کار ممکن است به فضای اضافی به اندازه شاخه archives
# نیاز داشته باشد. روش‌های pick می‌توانند بازنویسی را به‌طور انتخابی‌تر
# یا تدریجی‌تر انجام دهند. (فرض کنید BUP_DIR فاقد تنظیمات
# تقسیم است.)
#
$ git --git-dir "$BUP_DIR" config bup.split.trees true
$ git --git-dir "$BUP_DIR" config bup.split.files legacy:16
$ bup get --rewrite --append: archives archives-resplit
#
# بررسی کنید که archives-resplit مناسب به نظر برسد، شاید از طریق بازیابی‌های
# آزمایشی، اتصال آن و غیره (به بخش «هشدار» در بالا رجوع کنید)، و پس از
# اطمینان، شاید...
#
$ bup rm archives
$ bup gc
$ git --git-dir "$BUP_DIR" branch -m archives-resplit archives
#
# تعمیر یک ذخیره تکی.
$ bup get --repair --pick archives/latest fixed
#
# بررسی کنید که fixed/latest مناسب به نظر برسد، شاید از طریق بازیابی‌های
# آزمایشی، اتصال آن و غیره (به بخش «هشدار» در بالا رجوع کنید).

وضعیت خروج (EXIT STATUS)

کد خروج 3 نشان می‌دهد که تعمیرات مورد نیاز بوده و با موفقیت انجام شده‌اند، و هیچ خطای دیگری رخ نداده است.

همچنین ببینید (SEE ALSO)

bup-on(1)، bup-tag(1)، ssh_config(5)

مجموعه BUP (BUP)

بخشی از مجموعه bup(1).

نویسندگان (AUTHORS)

Rob Browning rlb@defaultvalue.org.