نام (NAME)

yadm - ابزاری دیگر برای مدیریت دات‌فایل‌ها

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

yadm command [options]

yadm git-command-or-alias [options]

yadm init [-f] [-w dir]

yadm clone url [-f] [-w dir] [-b branch] [--bootstrap] [--no-bootstrap]

yadm config name [value]

yadm config [-e]

yadm list [-a]

yadm bootstrap

yadm encrypt

yadm decrypt [-l]

yadm alt

yadm perms

yadm enter [command]

yadm git-crypt [options]

yadm transcrypt [options]

yadm upgrade [-f]

yadm introspect category

توضیحات (DESCRIPTION)

برنامهٔ yadm ابزاری برای مدیریت مجموعه‌ای از فایل‌ها در چندین رایانه با استفاده از یک مخزن Git مشترک است. علاوه بر این، yadm قابلیتی را برای انتخاب نسخه‌های جایگزین فایل‌ها برای سیستم‌های مشخص فراهم می‌کند. در نهایت، yadm امکان مدیریت زیرمجموعه‌ای از فایل‌های امن را فراهم می‌آورد که پیش از قرار گرفتن در مخزن رمزنگاری می‌شوند.

دستورها (COMMANDS)

git-command یا git-alias

هر دستوری که به‌طور داخلی توسط yadm مدیریت نشود، مستقیماً به git(1) ارسال می‌شود. دستورها یا نام‌های مستعار Git با مخزن مدیریت‌شدهٔ yadm فراخوانی می‌شوند. دایرکتوری کاری برای دستورهای Git، همان work-tree (معمولاً $HOME) پیکربندی‌شده خواهد بود.

دات‌فایل‌ها با استفاده از دستورهای استاندارد git شامل add، commit، push، pull و غیره مدیریت می‌شوند.

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

alt

ایجاد پیوندهای نمادین و پردازش الگوها برای تمامی فایل‌های مدیریت‌شده‌ای که با قوانین نام‌گذاری شرح داده شده در بخش‌های ALTERNATES و TEMPLATES همخوانی دارند. معمولاً نیازی به اجرای این دستور نیست، چرا که yadm به‌طور پیش‌فرض فایل‌های جایگزین را پردازش می‌کند. این رفتار خودکار را می‌توان با تنظیم مقدار پیکربندی yadm.auto-alt بر روی "false" غیرفعال کرد.

bootstrap

اجرای $HOME/.config/yadm/bootstrap، در صورتی که وجود داشته باشد.

clone url

شبیه‌سازی یک مخزن دوردست برای ره‌گیری دات‌فایل‌ها. پس از واکشی محتویات مخزن دوردست، تلاش می‌شود تا شاخهٔ HEAD راه دور بررسی و دریافت (check out) شود. اگر از قبل فایل‌های متداخلی در work-tree وجود داشته باشند، نسخهٔ محلی بدون تغییر باقی می‌ماند و شما باید تفاوت‌ها را بررسی و حل کنید.

مخزن در $HOME/.local/share/yadm/repo.git ذخیره می‌شود. به‌طور پیش‌فرض، $HOME به‌عنوان work-tree استفاده خواهد شد، اما این مورد را می‌توان با گزینهٔ -wتغییرداد. با ارائهٔ گزینهٔ -fمی‌توانyadmرابهبازنویسییکمخزنموجودوادارکرد. اگر می‌خواهید از شاخه‌ای به جز شاخهٔ HEAD دوردست استفاده کنید، می‌توانید آن را با گزینهٔ -bمشخصنمایید. به‌طور پیش‌فرض yadm از کاربر می‌پرسد که آیا برنامهٔ bootstrap اجرا شود یا خیر (در صورت وجود). گزینه‌های --bootstrap یا --no-bootstrap بدون اعلان به کاربر، یا اجرای bootstrap را اجباری کرده و یا از اجرای آن جلوگیری می‌کنند.

config

این دستور پیکربندی‌های yadm را مدیریت می‌کند. این دستور دقیقاً همانند git-config(1) عمل می‌کند. برای جزئیات بیشتر به بخش CONFIGURATION مراجعه کنید.

decrypt

تمام فایل‌های ذخیره‌شده در $HOME/.local/share/yadm/archive را رمزگشایی می‌کند. فایل‌های رمزگشایی‌شده نسبت به work-tree (معمولاً $HOME) پیکربندی‌شده خواهند بود. استفاده از گزینهٔ -l فایل‌های ذخیره‌شده را بدون استخراج آن‌ها فهرست می‌کند.

encrypt

تمام فایل‌های منطبق بر الگوهای موجود در $HOME/.config/yadm/encrypt را رمزنگاری می‌کند. برای جزئیات بیشتر بخش ENCRYPTION را ببینید.

enter

یک زیرپوسته با تنظیم تمامی متغیرهای Git اجرا می‌کند. خروج از این زیرپوسته همانند خروج از پوستهٔ عادی شماست (معمولاً با دستور "exit"). این زیرپوسته را می‌توان برای تعامل آسان با مخزن yadm از طریق دستورهای "git" به کار برد. این قابلیت می‌تواند هنگام استفاده از ابزارهایی که مستقیماً با Git کار می‌کنند مانند tig، vim-fugitive، git-cola و غیره مفید باشد.

به‌صورت اختیاری، می‌توانید دستوری را پس از "enter" مشخص کنید؛ در این صورت به جای فراخوانی پوسته، آن دستور با تمام متغیرهای Git که در محیط آن قرار گرفته‌اند اجرا خواهد شد.

ابزارهای Emacs Tramp و Magit می‌توانند با استفاده از این پیکربندی فایل‌ها را مدیریت کنند:

پیکربندی (CONFIGURATION)

برنامه yadm از یک فایل پیکربندی با نام $HOME/.config/yadm/config استفاده می‌کند. این فایل از همان قالبی بهره می‌برد که در git-config(1) استفاده شده است. همچنین می‌توانید محتوای فایل پیکربندی را از طریق دستور yadm config (که دقیقاً همانند git-config عمل می‌کند) مدیریت کنید. برای نمونه، جهت غیرفعال‌سازی فایل‌های جایگزین (alternates) می‌توانید دستور زیر را اجرا کنید:

فهرست کامل پیکربندی‌های پشتیبانی‌شده به شرح زیر است:

yadm.alt-copy

اگر روی "true" تنظیم شود، فایل‌های جایگزین به جای پیوندهای نمادین، رونوشت (کپی) خواهند بود. این امر ممکن است مطلوب باشد، زیرا ممکن است برخی سیستم‌ها به درستی از پیوندهای نمادین پشتیبانی نکنند.

yadm.auto-alt

غیرفعال‌سازی پیونددهی خودکارِ شرح‌داده‌شده در بخش ALTERNATES. در صورت غیرفعال بودن، همچنان می‌توانید "yadm alt" را به صورت دستی اجرا کنید تا پیوندهای جایگزین ساخته شوند. این ویژگی به صورت پیش‌فرض فعال است.

yadm.auto-exclude

غیرفعال‌سازی استثنا کردنِ خودکارِ پیوندهای جایگزینِ ایجادشده، فایل‌های الگو (template) و الگوهای تعریف‌شده در $HOME/.config/yadm/encrypt. این ویژگی به صورت پیش‌فرض فعال است.

yadm.auto-perms

غیرفعال‌سازی تغییر خودکار دسترسی‌های شرح‌داده‌شده در بخش PERMISSIONS. در صورت غیرفعال بودن، همچنان می‌توانید yadm perms را به صورت دستی برای به‌روزرسانی دسترسی‌ها اجرا کنید. این ویژگی به صورت پیش‌فرض فعال است.

yadm.auto-private-dirs

غیرفعال‌سازی ایجاد خودکار دایرکتوری‌های خصوصیِ شرح‌داده‌شده در بخش PERMISSIONS.

yadm.cipher

مشخص کردن اینکه کدام سامانه رمزنگاری توسط دستورات encrypt/decrypt استفاده شود. گزینه‌های معتبر "gpg" و "openssl" هستند. مقدار پیش‌فرض "gpg" است. اطلاعات دقیق‌تر را می‌توانید در بخش ENCRYPTION بیابید.

yadm.git-program

مشخص کردن یک برنامه جایگزین جهت استفاده به جای "git". به صورت پیش‌فرض، نخستین "git" یافت‌شده در $PATH استفاده می‌شود.

yadm.gpg-perms

غیرفعال‌سازی تغییرات دسترسی برای $HOME/.gnupg/*. این ویژگی به صورت پیش‌فرض فعال است.

yadm.gpg-program

مشخص کردن یک برنامه جایگزین جهت استفاده به جای "gpg". به صورت پیش‌فرض، نخستین "gpg" یافت‌شده در $PATH استفاده می‌شود.

yadm.gpg-recipient

رمزنگاری نامتقارن فایل‌ها با استفاده از جفت‌کلید عمومی/خصوصی gpg. یک شناسه کلید (key ID) برای تعیین اینکه رمزنگاری با کدام کلید عمومی انجام شود وارد کنید. این کلید باید در دسته‌کلیدهای عمومی شما موجود باشد. می‌توان چندین گیرنده را مشخص کرد (جدا شده با فاصله). در صورت خالی ماندن یا وارد نشدن، به جای آن از رمزنگاری متقارن استفاده می‌شود. اگر روی "ASK" تنظیم شود، gpg گیرندگان را به صورت تعاملی می‌پرسد. برای جزئیات بیشتر بخش ENCRYPTION را ببینید. این ویژگی به صورت پیش‌فرض غیرفعال است.

yadm.openssl-ciphername

مشخص می‌کند کدام الگوریتم رمزنگاری (cipher) باید توسط openssl استفاده شود. به صورت پیش‌فرض "aes-256-cbc" استفاده می‌شود.

yadm.openssl-old

نسخه‌های جدیدتر openssl از تابع اشتقاق کلید pbkdf2 پشتیبانی می‌کنند. این حالت به صورت پیش‌فرض استفاده می‌شود. اگر این پیکربندی روی "true" تنظیم شود، عملیات openssl از گزینه‌های سازگار با نسخه‌های قدیمی‌تر openssl استفاده خواهد کرد. در صورت تغییر دادن این گزینه، باید آرشیو رمزنگاری‌شده خود را مجدداً بسازید.

yadm.openssl-program

مشخص کردن یک برنامه جایگزین جهت استفاده به جای "openssl". به صورت پیش‌فرض، نخستین "openssl" یافت‌شده در $PATH استفاده می‌شود.

yadm.ssh-perms

غیرفعال‌سازی تغییرات دسترسی برای $HOME/.ssh/*. این ویژگی به صورت پیش‌فرض فعال است.

پیکربندی‌های «محلی» (local) زیر در $HOME/.config/yadm/config ذخیره نمی‌شوند، بلکه در مخزن محلی نگهداری می‌شوند.

local.class

مشخص کردن یک کلاس به منظور ایجاد پیوندهای نمادین برای فایل‌های جایگزین. به صورت پیش‌فرض، هیچ کلاسی تطبیق داده نخواهد شد. با دستور زیر می‌توان چندین کلاس را به میزبان محلی اختصاص داد:

local.arch

جایگزینی معماری (architecture) به منظور ایجاد پیوندهای نمادین فایل‌های جایگزین.

local.hostname

جایگزینی نام میزبان (hostname) به منظور ایجاد پیوندهای نمادین فایل‌های جایگزین.

local.os

جایگزینی سیستم‌عامل (OS) به منظور ایجاد پیوندهای نمادین فایل‌های جایگزین.

local.user

جایگزینی کاربر (user) به منظور ایجاد پیوندهای نمادین فایل‌های جایگزین.

local.distro

جایگزینی توزیع (distro) به منظور ایجاد پیوندهای نمادین فایل‌های جایگزین.

local.distro-family

جایگزینی خانواده توزیع (distro family) به منظور ایجاد پیوندهای نمادین فایل‌های جایگزین..SH "جایگزین‌ها (ALTERNATES)"

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

ابزار yadm زمانی که یک پسوند معتبر به انتهای نام فایل اضافه شده باشد، به‌طور خودکار پیوندی نمادین (symbolic link) به نسخه مناسب آن فایل ایجاد می‌کند. این پسوند حاوی شرایطی است که برای استفاده از آن فایل باید برقرار باشند.

پسوند با «##» شروع شده و به دنبال آن هر تعداد شرط که با کاما از هم جدا شده‌اند، می‌آید.

##<condition>[,<condition>,...]

هر شرط یک جفت ویژگی/مقدار (attribute/value) است که با یک نقطه از هم جدا می‌شوند. برخی شرایط نیازی به «مقدار» ندارند و در آن صورت، نقطه و مقدار می‌توانند حذف شوند. بیشتر ویژگی‌ها را می‌توان به صورت یک تک‌حرف خلاصه کرد. قرار دادن پیشوند «~» پیش از یک ویژگی، شرط را نفی می‌کند؛ به این معنی که شرط تنها زمانی برقرار در نظر گرفته می‌شود که جفت ویژگی/مقدار نادرست (false) ارزیابی شود.

[~]<attribute>[.<value>]

نکته: مقایسه مقدار بدون حساسیت به بزرگی و کوچکی حروف (case-insensitive) انجام می‌شود.

ویژگی‌های پشتیبانی‌شده به ترتیب اولویت وزنی عبارتند از:

template, t

زمانی معتبر است که مقدار با یک پردازنده قالب (template processor) پشتیبانی‌شده مطابقت داشته باشد. برای جزئیات بیشتر بخش TEMPLATES را ببینید.

user, u

اگر مقدار با کاربر فعلی مطابقت داشته باشد معتبر است. کاربر فعلی با اجرای دستور زیر محاسبه می‌شود: id -u -n.

hostname, h

اگر مقدار با نام کوتاه میزبان (short hostname) مطابقت داشته باشد معتبر است. نام میزبان با اجرای دستور uname -n و حذف بخش دامنه به دست می‌آید.

class, c

اگر مقدار با پیکربندی local.class مطابقت داشته باشد معتبر است. کلاس (Class) باید به‌صورت دستی با استفاده از yadm config local.class <class> تنظیم شود. برای جزئیات بیشتر درباره تنظیم local.class بخش CONFIGURATION را ببینید.

distro_family, f

اگر مقدار با خانواده توزیع مطابقت داشته باشد معتبر است. خانواده توزیع با بررسی خط ID_LIKE در فایل /etc/os-release (یا شناسه ID در صورتی که خط ID_LIKE پیدا نشود) محاسبه می‌شود.

distro, d

اگر مقدار با توزیع مطابقت داشته باشد معتبر است. توزیع با اجرای دستور lsb_release -si یا با بررسی شناسه ID در فایل /etc/os-release محاسبه می‌شود.

os, o

اگر مقدار با سیستم‌عامل مطابقت داشته باشد معتبر است. سیستم‌عامل با اجرای دستور uname -s محاسبه می‌شود.

arch, a

اگر مقدار با معماری مطابقت داشته باشد معتبر است. معماری با اجرای دستور uname -m محاسبه می‌شود.

default

زمانی معتبر است که هیچ جایگزین دیگری معتبر نباشد.

extension, e

یک «شرط» ویژه که تأثیری بر فرایند انتخاب نمی‌گذارد. هدف آن در عوض این است که به فایل جایگزین اجازه دهد با یک پسوند خاص خاتمه یابد، به عنوان مثال تا ویرایشگرها بتوانند نحوه نمایش محتوا را به درستی برجسته (highlight) کنند.

نکته: سیستم‌عامل برای «Windows Subsystem for Linux» با وجود اینکه uname آن را به عنوان «Linux» شناسایی می‌کند، به عنوان «WSL» گزارش می‌شود.

می‌توانید از هر تعداد شرط، با هر ترتیبی استفاده کنید. یک نسخه جایگزین تنها زمانی استفاده خواهد شد که «همه» شرایط معتبر باشند. برای تمام فایل‌هایی که توسط مخزن yadm مدیریت می‌شوند یا در $HOME/.config/yadm/encrypt فهرست شده‌اند، در صورت مطابقت با این شیوه نام‌گذاری، پیوندهای نمادین برای مناسب‌ترین نسخه ایجاد خواهند شد.

نسخه «مناسب‌ترین» با محاسبه یک امتیاز برای هر نسخه از یک فایل تعیین می‌شود. امتیاز یک قالب (template) همواره از هر شرط پیوند نمادین دیگری بالاتر است. تعداد شرایط، بزرگ‌ترین عامل بعدی در امتیازدهی است؛ فایل‌هایی با شرایط بیشتر همواره ترجیح داده می‌شوند. شرایط منفی (با پیشوند «~») تنها نسبت به تعداد شرایط مثبت (نفی‌نشده) امتیازدهی می‌شوند. هر شرط نامعتبر، آن فایل را به‌طور کامل از دور خارج خواهد کرد.

اگر تمایلی ندارید که تمام نسخه‌های جایگزین در همان دایرکتوری پیوند نمادین تولیدشده نگهداری شوند، می‌توانید آن‌ها را در دایرکتوری $HOME/.config/yadm/alt قرار دهید. پیوند نمادین تولیدشده یا قالب پردازش‌شده با استفاده از همان مسیر نسبی ایجاد خواهد شد.

پیونددهی جایگزین‌ها را شاید بتوان با یک مثال بهتر نشان داد. فرض کنید فایل‌های زیر توسط مخزن yadm مدیریت می‌شوند:

- $HOME/path/example.txt##default
- $HOME/path/example.txt##class.Work
- $HOME/path/example.txt##class.Work,~os.Darwin
- $HOME/path/example.txt##os.Darwin
- $HOME/path/example.txt##os.Darwin,hostname.host1
- $HOME/path/example.txt##os.Darwin,hostname.host2
- $HOME/path/example.txt##os.Linux
- $HOME/path/example.txt##os.Linux,hostname.host1
- $HOME/path/example.txt##os.Linux,hostname.host2

اگر روی یک Macbook با نام «host2» اجرا شود، yadm یک پیوند نمادین مشابه زیر ایجاد خواهد کرد:

$HOME/path/example.txt -> $HOME/path/example.txt##os.Darwin,hostname.host2

با این حال، روی یک Macbook دیگر به نام «host3»، yadm پیوند نمادینی مشابه زیر ایجاد خواهد کرد:

$HOME/path/example.txt -> $HOME/path/example.txt##os.Darwin

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

اگر روی یک سرور Linux به نام «host4» اجرا شود، پیوند به صورت زیر خواهد بود:

$HOME/path/example.txt -> $HOME/path/example.txt##os.Linux

اگر روی یک سرور Solaris اجرا شود، پیوند از نسخه پیش‌فرض استفاده خواهد کرد:

$HOME/path/example.txt -> $HOME/path/example.txt##default

اگر روی یک Macbook که class آن روی «Work» تنظیم شده اجرا شود، پیوند به صورت زیر خواهد بود:

$HOME/path/example.txt -> $HOME/path/example.txt##class.Work

از آنجا که class نسبت به os اولویت بالاتری دارد، این نسخه انتخاب می‌شود.

اگر روی سیستمی اجرا شود که class آن بر روی «Work» تنظیم شده باشد، اما در محیط Windows Subsystem for Linux که os به صورت WSL گزارش می‌شود، پیوند به صورت زیر خواهد بود:

$HOME/path/example.txt -> $HOME/path/example.txt##class.Work,~os.Darwin

اگر هیچ نسخه «##default» وجود نداشته باشد و هیچ فایلی نیز شرایط معتبری نداشته باشد، هیچ پیوندی ایجاد نخواهد شد.

پیوندها برای دایرکتوری‌هایی که با این روش نام‌گذاری شده‌اند نیز ایجاد می‌شوند، به شرط آنکه حداقل یک فایل مدیریت‌شده توسط yadm در درون آن‌ها وجود داشته باشد.

ابزار yadm به‌طور پیش‌فرض این پیوندها را خودکار ایجاد می‌کند. این قابلیت را می‌توان با استفاده از پیکربندی yadm.auto-alt غیرفعال کرد. حتی در صورت غیرفعال بودن، پیوندها را می‌توان به‌صورت دستی با اجرای دستور yadm alt ایجاد کرد.

پیوندهای ایجادشده به‌طور خودکار به فایل info/exclude در مخزن اضافه می‌شوند. این عملکرد را می‌توان با استفاده از پیکربندی yadm.auto-exclude غیرفعال کرد.

مقدار Class مقداری ویژه است که به‌صورت محلی روی هر میزبان (درون مخزن محلی) ذخیره می‌شود. برای استفاده از پیوندهای نمادین جایگزین با استفاده از class، باید مقدار class را از طریق پیکربندی local.class تنظیم کنید. این مقدار مانند هر پیکربندی دیگر yadm با دستور yadm config تنظیم می‌شود. دستور زیر مقدار class را برابر «Work» قرار می‌دهد:

yadm config local.class Work

به‌طور مشابه، مقادیر architecture، os، hostname، user، distro و distro_family را می‌توان به‌صورت دستی با استفاده از گزینه‌های پیکربندی local.arch، local.os، local.hostname، local.user، local.distro، و local.distro-family بازنویسی (override) کرد..SH "قالب‌ها (TEMPLATES)"

اگر شرط قالب در پسوند «##» یک فایل جایگزین تعریف شده باشد، و وابستگی‌های لازم برای قالب در دسترس باشند، آنگاه فایل جهت ایجاد یا بازنویسی فایل‌ها پردازش خواهد شد.

پردازشگرهای قالب پشتیبانی‌شده:

default

این پردازشگر قالب توکار yadm است. این پردازشگر بسیار ساده بوده و سینتکسی شبیه به Jinja دارد. مزیت این پردازشگر آن است که تنها به awk وابسته است که در اکثر سیستم‌های *nix در دسترس می‌باشد. برای استفاده از این پردازشگر، مقدار «default» را تعیین کنید یا فقط مقدار را خالی بگذارید (مانند «##template»).

نکته: این پردازشگر قالب، مقایسه‌ها را در عبارات if بدون در نظر گرفتن بزرگی و کوچکی حروف (case-insensitive) انجام می‌دهد.

ESH

ابزار ESH یک پردازشگر قالب است که در شل سازگار با POSIX نوشته شده است. این ابزار اجازه اجرای دستورات شل را درون قالب‌ها می‌دهد. از این قابلیت می‌توان برای ارجاع به پیکربندی‌های خودتان در قالب‌ها استفاده کرد، به عنوان مثال:

<% yadm config mysection.myconfig %>

برای استفاده از پردازشگر قالب ESH، مقدار «esh» را تعیین کنید.

j2cli

برای استفاده از پردازشگر قالب Jinja مربوط به j2cli، مقدار «j2» یا «j2cli» را مشخص کنید.

envtpl

برای استفاده از پردازشگر قالب Jinja مربوط به envtpl، مقدار «j2» یا «envtpl» را مشخص کنید.

نکته: مشخص کردن «j2» به عنوان پردازشگر تلاش خواهد کرد تا از j2cli یا envtpl (هرکدام که در دسترس باشد) استفاده کند.

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

هنگام پردازش، متغیرهای زیر در قالب در دسترس هستند:

Default Jinja or ESH توضیحات
------------- ------------- ----------------------------
yadm.arch YADM_ARCH uname -m
yadm.class YADM_CLASS آخرین کلاس تعریف‌شده محلی
yadm.classes YADM_CLASSES تمام کلاس‌ها
yadm.distro YADM_DISTRO lsb_release -si
yadm.distro_family YADM_DISTRO_FAMILY ID_LIKE از /etc/os-release
yadm.filename نام فایل برای فایل جاری
yadm.hostname YADM_HOSTNAME uname -n (بدون دامنه)
yadm.os YADM_OS uname -s
yadm.source YADM_SOURCE نام فایل قالب
yadm.user YADM_USER id -u -n
env.VAR متغیر محیطی VAR

نکته: سیستم‌عامل برای «Windows Subsystem for Linux» به‌صورت «WSL» گزارش می‌شود، حتی با اینکه uname آن را «Linux» تشخیص می‌دهد.

نکته: اگر lsb_release در دسترس نباشد، مقدار DISTRO برابر با ID مشخص‌شده در /etc/os-release خواهد بود.

مثال‌ها:

whatever##template با محتوای زیر

{% if yadm.user == "harvey" %}
config={{yadm.class}}-{{yadm.os}}
{% else %}
config=dev-whatever
{% include "whatever.extra" %}
{% endif %}

در صورتی که کاربر «harvey» باشد، فایلی به نام whatever با محتوای زیر تولید می‌کند:

config=work-Linux

و در غیر این صورت (اگر whatever.extra شامل admin=false باشد) محتوای زیر را خواهد داشت:

config=dev-whatever
admin=false

یک قالب Jinja معادل با نام whatever##template.j2 به این صورت خواهد بود:

{% if YADM_USER == 'harvey' -%}
config={{YADM_CLASS}}-{{YADM_OS}}
{% else -%}
config=dev-whatever
{% include 'whatever.extra' %}
{% endif -%}

یک قالب ESH معادل با نام whatever##template.esh به این صورت خواهد بود:

<% if [ "$YADM_USER" = "harvey" ]; then -%>
config=<%= $YADM_CLASS %>-<%= $YADM_OS %>
<% else -%>
config=dev-whatever
<%+ whatever.extra %>
<% fi -%>

فایل‌های ایجادشده به‌طور خودکار به فایل info/exclude مخزن اضافه می‌شوند. این رفتار را می‌توان با استفاده از پیکربندی yadm.auto-exclude غیرفعال کرد..SH "رمزنگاری (ENCRYPTION)"

مدیریت فایل‌های محرمانه، مانند کلیدهای SSH یا GPG، میان چندین سیستم می‌تواند بسیار سودمند باشد. با این حال، انجام این کار ممکن است داده‌های متنی ساده (plain text) را وارد مخزن Git کند که اغلب روی یک سیستم عمومی قرار دارد. yadm می‌تواند رمزنگاری و رمزگشایی مجموعه‌ای از فایل‌ها را آسان سازد تا نسخهٔ رمزنگاری‌شده در مخزن Git نگهداری شود. این ویژگی تنها در صورتی کار خواهد کرد که یک ابزار پشتیبانی‌شده در دسترس باشد. هر دو ابزار gpg(1) و openssl(1) پشتیبانی می‌شوند. به‌طور پیش‌فرض از gpg استفاده می‌شود، اما با استفاده از پیکربندی yadm.cipher می‌توان openssl را پیکربندی کرد.

برای استفاده از این ویژگی، باید فهرستی از الگوها (هر کدام در یک خط) ایجاد شده و به عنوان $HOME/.config/yadm/encrypt ذخیره شود. این فهرست الگوها باید نسبت به work-tree (معمولاً $HOME) پیکربندی‌شده باشد. به عنوان مثال:

گسترش‌های استاندارد نام فایل (*، ?، [) پشتیبانی می‌شوند. دو ستارهٔ متوالی "**" می‌تواند برای تطبیق با همهٔ زیرپوشه‌ها استفاده شود. سایر گسترش‌های پوسته مانند آکولاد و تیلدا (tilde) پشتیبانی نمی‌شوند. فاصله‌ها در مسیرها پشتیبانی می‌شوند و نباید داخل کوتیشن قرار گیرند. اگر یک پوشه مشخص شود، محتویات آن گنجانده خواهد شد. مسیرهایی که با «!» آغاز می‌شوند مستثنی خواهند شد.

دستور yadm encrypt همهٔ فایل‌های منطبق با الگوها را می‌یابد و برای دریافت گذرواژه اعلان می‌دهد. پس از تأیید گذرواژه، فایل‌های منطبق رمزنگاری شده و به عنوان $HOME/.local/share/yadm/archive ذخیره خواهند شد. فایل‌های «encrypt» و «archive» باید به مخزن yadm اضافه شوند تا در میان چندین سیستم در دسترس باشند.

برای رمزگشایی بعدی این فایل‌ها، یا در یک سیستم دیگر، دستور yadm decrypt را اجرا کرده و گذرواژهٔ صحیح را وارد کنید. پس از رمزگشایی فایل‌ها، مجوزها به‌طور خودکار همان‌طور که در بخش PERMISSIONS توضیح داده شده به‌روزرسانی می‌شوند.

به‌طور پیش‌فرض رمزنگاری متقارن استفاده می‌شود، اما می‌توان با استفاده از پیکربندی yadm.gpg-recipient رمزنگاری نامتقارن را فعال کرد.

نکته: توصیه می‌شود هنگام نگهداری فایل‌های محرمانه، حتی اگر رمزنگاری شده باشند، از یک مخزن خصوصی استفاده کنید.

الگوهای موجود در $HOME/.config/yadm/encrypt هر بار که yadm encrypt اجرا می‌شود، به‌طور خودکار به فایل info/exclude مخزن افزوده می‌شوند. این کار برای جلوگیری از کامیت تصادفی داده‌های حساس به مخزن است. می‌توان این قابلیت را با استفاده از پیکربندی yadm.auto-exclude غیرفعال کرد.

استفاده از transcrypt یا git-crypt

یک گزینهٔ کاملاً مجزا برای رمزنگاری داده‌ها، نصب و استفاده از transcrypt یا git-crypt است. پس از نصب، می‌توانید با اجرای yadm transcrypt یا yadm git-crypt از این ابزارها استفاده کنید. این ابزارها رمزنگاری و رمزگشایی نامحسوس فایل‌ها را در یک مخزن git ممکن می‌سازند. برای اطلاعات بیشتر وب‌سایت‌های زیر را ببینید:

- https://github.com/elasticdog/transcrypt

- https://github.com/AGWA/git-crypt.SH "مجوزها (PERMISSIONS)"

هنگامی که فایل‌ها از یک مخزن Git واکشی (check out) می‌شوند، مجوزهای اولیه آن‌ها به umask کاربر وابسته است. به همین دلیل، yadm به‌طور خودکار مجوزهای برخی مسیرهای فایل را به‌روزرسانی می‌کند. مجوزهای «گروه» (group) و «دیگران» (others) از فایل‌های زیر حذف خواهند شد:

- $HOME/.local/share/yadm/archive

- تمام فایل‌های منطبق با الگوها در $HOME/.config/yadm/encrypt

- دایرکتوری و فایل‌های SSH، .ssh/*

- دایرکتوری و فایل‌های GPG، .gnupg/*

yadm به‌طور پیش‌فرض مجوزها را به‌طور خودکار به‌روزرسانی می‌کند. این قابلیت را می‌توان با استفاده از پیکربندی yadm.auto-perms غیرفعال کرد. حتی در صورت غیرفعال بودن، مجوزها را می‌توان به‌صورت دستی با اجرای yadm perms به‌روزرسانی نمود. پردازش دایرکتوری .ssh را می‌توان با استفاده از پیکربندی yadm.ssh-perms غیرفعال کرد. پردازش دایرکتوری .gnupg را نیز می‌توان با استفاده از پیکربندی yadm.gpg-perms غیرفعال ساخت.

هنگام clone کردن مخزنی که شامل داده‌هایی در دایرکتوری .ssh یا .gnupg است، چنانچه آن دایرکتوری‌ها در زمان clone کردن وجود نداشته باشند، yadm پیش از ادغام داده‌های واکشی‌شده در work-tree، دایرکتوری‌ها را با ماسک 0700 ایجاد خواهد کرد.

هنگام اجرای یک دستور Git، در صورتی که دایرکتوری‌های .ssh یا .gnupg وجود نداشته باشند، yadm پیش از اجرای دستور Git آن دایرکتوری‌ها را با ماسک 0700 ایجاد خواهد کرد. این قابلیت را می‌توان با استفاده از پیکربندی yadm.auto-private-dirs غیرفعال کرد.

قلاب‌ها (HOOKS)

برای هر دستوری که yadm پشتیبانی می‌کند، می‌توان برنامه‌ای فراهم ساخت تا قبل یا بعد از آن دستور اجرا شود. به این برنامه‌ها «قلاب» (hook) گفته می‌شود. yadm در دایرکتوری $HOME/.config/yadm/hooks به‌دنبال قلاب‌ها می‌گردد. نام هر قلاب با پیشوند pre_ یا post_، به همراه نام دستوری که باید قلاب را فراخوانی کند تعیین می‌شود. برای مثال، جهت ایجاد قلابی که پس از هر دستور yadm pull اجرا شود، قلابی با نام post_pull ایجاد کنید. قلاب‌ها باید دارای مجوز فایل اجرایی باشند.

اگر یک قلاب pre_ تعریف شده باشد و با وضعیت خروج غیرصفر خاتمه یابد، yadm از اجرای دستور yadm خودداری خواهد کرد. برای نمونه، اگر یک قلاب pre_commit تعریف شده باشد اما آن دستور با وضعیت خروج غیرصفر به پایان برسد، دستور yadm commit هرگز اجرا نخواهد شد. این سازوکار امکان متوقف کردن زودهنگام (short-circuit) هر عملیاتی را با استفاده از یک قلاب pre_ فراهم می‌کند.

قلاب‌ها در زمان اجرا به متغیرهای محیطی زیر دسترسی دارند:

YADM_HOOK_COMMAND

دستوری که قلاب را فعال کرده است

YADM_HOOK_DATA

مسیر دایرکتوری داده‌های yadm

YADM_HOOK_DIR

مسیر دایرکتوری yadm

YADM_HOOK_EXIT

وضعیت خروج دستور yadm

YADM_HOOK_FULL_COMMAND

دستور yadm به همراه تمامی آرگومان‌های خط فرمان (پارامترها با فاصله جدا می‌شوند، و هرگونه فاصله، تب یا بک‌اسلش با یک بک‌اسلش اسکیپ می‌شود)

YADM_HOOK_REPO

مسیر مخزن yadm

YADM_HOOK_WORK

مسیر درخت کاری (work-tree).SH "فایل‌ها (FILES)"

تمام پیکربندی‌های yadm نسبت به «دایرکتوری yadm» سنجیده می‌شوند. دستور yadm برای تعیین این دایرکتوری از «XDG Base Directory Specification» استفاده می‌کند. اگر متغیر محیطی $XDG_CONFIG_HOME به‌صورت یک مسیر کامل تعریف شده باشد، این دایرکتوری $XDG_CONFIG_HOME/yadm خواهد بود؛ در غیر این صورت $HOME/.config/yadm خواهد بود.

به همین ترتیب، فایل‌های دادهٔ yadm نسبت به «دایرکتوری دادهٔ yadm» سنجیده می‌شوند. دستور yadm برای تعیین این دایرکتوری از «XDG Base Directory Specification» استفاده می‌کند. اگر متغیر محیطی $XDG_DATA_HOME به‌صورت یک مسیر کامل تعریف شده باشد، این دایرکتوری $XDG_DATA_HOME/yadm خواهد بود؛ در غیر این صورت $HOME/.local/share/yadm خواهد بود.

موارد زیر مسیرهای پیش‌فرضی هستند که yadm برای داده‌های خود استفاده می‌کند. بیشتر این مسیرها را می‌توان با استفاده از گزینه‌های عمومی تغییر داد. برای جزئیات بیشتر بخش «گزینه‌ها (OPTIONS)» را ببینید.

$HOME/.config/yadm

دایرکتوری yadm. به‌طور پیش‌فرض، تمام پیکربندی‌هایی که yadm ذخیره می‌کند نسبت به این دایرکتوری سنجیده می‌شوند.

$HOME/.local/share/yadm

دایرکتوری دادهٔ yadm. به‌طور پیش‌فرض، تمام داده‌هایی که yadm ذخیره می‌کند نسبت به این دایرکتوری سنجیده می‌شوند.

$YADM_DIR/config

فایل پیکربندی برای yadm.

$YADM_DIR/alt

این دایرکتوری برای نگهداری «فایل‌های جایگزین» بدون نیاز به قرار دادن آن‌ها در کنار پیوند نمادین حاصل یا قالب پردازش‌شده است. فایل‌های جایگزین قرارگرفته در این دایرکتوری، در عوض نسبت به $HOME ایجاد خواهند شد.

$YADM_DATA/repo.git

مخزن Git مورد استفاده توسط yadm.

$YADM_DIR/encrypt

فهرستی از الگوها (globs) که برای رمزنگاری/رمزگشایی استفاده می‌شوند.

$YADM_DATA/archive

تمام فایل‌های رمزنگاری‌شده با yadm encrypt در این فایل ذخیره می‌شوند.

مثال‌ها (EXAMPLES)

yadm init

ایجاد یک مخزن خالی برای مدیریت فایل‌ها

yadm add .bash_profile ; yadm commit

افزودن .bash_profile به نمایهٔ Git و ایجاد یک کامیت جدید

yadm remote add origin <url>

افزودن یک ریموت origin به مخزن موجود

yadm push -u origin master

ارسال اولیهٔ (push) شاخهٔ master به origin

echo .ssh/*.key >> $HOME/.config/yadm/encrypt

افزودن یک الگوی جدید به فهرست فایل‌های رمزنگاری‌شده

yadm encrypt ; yadm add ~/.local/share/yadm/archive ; yadm commit

کامیت کردن مجموعه‌ای جدید از فایل‌های رمزنگاری‌شده

گزارش باگ‌ها (REPORTING BUGS)

مشکلات را گزارش دهید یا در GitHub پول‌ریکوئست ایجاد کنید:

https://github.com/yadm-dev/yadm/issues.SH "نویسندگان (AUTHORS)"

Tim Byrne <sultan@locehilios.com>

Erik Flodin <erik@flodin.me>

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

git(1), gpg(1) openssl(1) transcrypt(1) git-crypt(1)

https://yadm.io