git-annex-preferred-content(1) General Commands Manual git-annex-preferred-content(1)

git-annex-preferred-content - تنظیمات محتوای ترجیحی برای مخازن

هر مخزن دارای یک تنظیم محتوای ترجیحی (preferred content) است که مشخص می‌کند مخزن مایل است چه محتوایی در آن موجود باشد. این تنظیمات را می‌توان با استفاده از git annex vicfg یا git annex wanted پیکربندی کرد. این تنظیمات توسط گزینه --auto، توسط git annex sync --content، توسط خوشه‌ها (clusters) و توسط دستیار git-annex استفاده می‌شوند.

اگرچه محتوای ترجیحی بیانگر یک ترجیح است، می‌توان آن را به سادگی با استفاده از git annex drop نادیده گرفت. از سوی دیگر، تنظیمات محتوای الزامی (required content) اجباری هستند؛ git annex drop در صورتی که رها کردن یک فایل ناقض تنظیمات محتوای الزامی آن باشد، از رها کردن آن خودداری می‌کند. محتوای الزامی یک مخزن را می‌توان با استفاده از git annex vicfg یا git annex required پیکربندی کرد.

عبارت‌های محتوای ترجیحی از نحوی مشابه با git-annex-matching-options(1) بدون خط تیره استفاده می‌کنند. برای مثال:

exclude=archive/* and (include=*.mp3 or smallerthan=1mb)

ایده کلی این است که عبارتی می‌نویسید که فایل‌ها با آن مطابقت داده می‌شوند. اگر فایلی با آن مطابقت داشته باشد، مخزن تمایل دارد محتوای آن را ذخیره کند. اگر مطابقت نداشته باشد، مخزن مایل است محتوای آن را رها کند (در صورتی که نسخه‌های کافی از آن در جای دیگری وجود داشته باشد که اجازه حذف آن را بدهد).

یک عبارت محتوای ترجیحی خالی مانند عدم پیکربندی محتوای ترجیحی تلقی می‌شود.

تطبیق فایل‌ها برای شامل شدن یا مستثنی شدن.
در حالی که گزینه‌های خط فرمان --include=glob و --exclude=glob فایل‌ها را نسبت به دایرکتوری جاری تطبیق می‌دهند، عبارت‌های محتوای ترجیحی فایل‌ها را نسبت به ریشه اصلی مخزن git تطبیق می‌دهند.
یک glob چیزی شبیه به foo.* یا b?r است. الگوهای glob همچنین می‌توانند شامل رده‌های کاراکتری مانند foo[Bb]ar و همچنین رده‌های کاراکتری اضافی POSIX مانند [[:space:]] باشند. این ویژگی مفید است، زیرا یک glob در عبارت محتوای ترجیحی نمی‌تواند حاوی فاصله باشد. برای اطلاعات بیشتر در مورد globها، به صفحه راهنمای glob(7) مراجعه کنید.
برای مثال، فرض کنید پس از اتمام کار با فایل‌ها، آن‌ها را در دایرکتوری‌های archive قرار می‌دهید. در این صورت می‌توانید لپ‌تاپ خود را به شکلی پیکربندی کنید که ترجیح دهد آن فایل‌ها را نگه ندارد، به این صورت: exclude=*/archive/*
هنگامی که یک زیردایرکتوری به یک ریموت خاص صادر یا از آن وارد می‌شود (به git-annex-export(1) و git-annex-import(1) مراجعه کنید)، این عبارات نسبت به ریشه آن زیردایرکتوری تطبیق داده می‌شوند.
توجه داشته باشید که هنگام اجرای یک دستور با گزینه --all یا در یک مخزن bare، هیچ نام فایلی با یک شیء annex شده مرتبط نیست و بنابراین "include=" و "exclude=" تطبیق نخواهند یافت.
فقط فایل‌هایی را مطابقت می‌دهد که git-annex بر این باور است که تعداد مشخص‌شده نسخه یا بیشتر از آن را دارند. توجه داشته باشید که این عبارت ریموت‌ها را برای تأیید اینکه آیا نسخه‌ها هنوز وجود دارند یا خیر بررسی نمی‌کند.
برای تصمیم‌گیری درباره اینکه آیا محتوا باید رها شود یا خیر، git-annex عبارت محتوای ترجیحی را با این فرض ارزیابی می‌کند که محتوا *قبلاً* رها شده است. اگر محتوا در آن شرایط دیگر مورد نیاز نباشد، عمل رها کردن قابل انجام است. بنابراین، برای مثال، copies=2 در یک عبارت محتوای ترجیحی تنها زمانی اجازه رها شدن محتوا را می‌دهد که در حال حاضر ۳ نسخه از آن وجود داشته باشد، شامل همان مخزنی که محتوا از آن رها می‌شود. این متفاوت با اجرای git annex drop --copies=2 است که فایل‌هایی را که در حال حاضر ۲ نسخه دارند رها خواهد کرد.
فقط فایل‌هایی را مطابقت می‌دهد که git-annex معتقد است تعداد مشخص‌شده نسخه از آن‌ها روی ریموت‌هایی با سطح اعتماد مشخص‌شده وجود دارد. برای مثال، copies=trusted:2
برای تطبیق با هر سطح اعتمادی برابر یا بالاتر از یک سطح معین، از trustlevel+ استفاده کنید؛ برای مثال: copies=semitrusted+:2
فقط فایل‌هایی را مطابقت می‌دهد که git-annex معتقد است تعداد مشخص‌شده نسخه از آن‌ها روی ریموت‌های موجود در گروه مشخص‌شده قرار دارد. برای مثال، copies=archive:2
عبارت‌های محتوای ترجیحی معادلی برای گزینه --in ندارند، اما گروه‌ها می‌توانند کارهای مشابهی انجام دهند. می‌توانید مخازن را به گروه‌ها اضافه کنید، و در عبارت محتوای ترجیحی بر اساس گروه‌ها تطبیق انجام دهید. بنابراین به جای --in=usbdrive، همه درایوهای USB را در یک گروه "transfer" قرار دهید و از copies=transfer:1 استفاده کنید.
فقط فایل‌هایی را مطابقت می‌دهد که git-annex معتقد است برای برآورده کردن تنظیمات numcopies خود، نیاز به ایجاد تعداد مشخص‌شده یا بیشتری نسخه اضافی دارند.
مشابه lackingcopies است، اما تنظیمات annex.numcopies در فایل .gitattributes را بررسی نمی‌کند. این امر آن را به طور قابل‌توجهی سریع‌تر می‌کند.
فقط فایل‌هایی را مطابقت می‌دهد که محتوای آن‌ها با استفاده از بک‌اند کلید-مقدار مشخص‌شده ذخیره شده است.
برای اطلاعات درباره بک‌اندهای موجود، به git-annex-backends(1) مراجعه کنید.
فقط فایل‌هایی را مطابقت می‌دهد که محتوای آن‌ها با استفاده از یک تابع از نظر رمزنگاری امن هش شده باشد.
فقط فایل‌هایی را مطابقت می‌دهد که git-annex معتقد است در تمام مخازن موجود در گروه مشخص‌شده حاضر هستند.
فایل‌هایی را مطابقت می‌دهد که git-annex معتقد است در حداقل یک مخزن از گروه مشخص‌شده وجود دارند و در هیچ مخزنی خارج از آن گروه حضور ندارند.
فقط فایل‌هایی را مطابقت می‌دهد که اندازه محتوای آن‌ها کوچک‌تر یا بزرگ‌تر از اندازه مشخص‌شده باشد.
اندازه را می‌توان با هر یک از واحدهای متداول تعیین کرد؛ برای مثال، "0.5 gb" یا "100 KiloBytes"
فقط فایل‌هایی را مطابقت می‌دهد که دارای فیلد فراداده‌ای متصل‌شده‌ای هستند که مقدار آن با glob مطابقت دارد. مقادیر فیلدهای فراداده بدون حساسیت به حروف کوچک و بزرگ مطابقت داده می‌شوند.
یک glob چیزی شبیه به foo.* یا b?r است. الگوهای glob همچنین می‌توانند شامل رده‌های کاراکتری مانند foo[Bb]ar و همچنین رده‌های کاراکتری اضافی POSIX مانند [[:space:]] باشند. این ویژگی مفید است، زیرا یک glob در عبارت محتوای ترجیحی نمی‌تواند حاوی فاصله باشد. برای اطلاعات بیشتر در مورد globها، به صفحه راهنمای glob(7) مراجعه کنید.
برای تطبیق با برچسب "done"، از metadata=tag=done استفاده کنید.
برای تطبیق با فراداده نویسنده، از metadata=author=*Smith استفاده کنید.
فقط فایل‌هایی را مطابقت می‌دهد که دارای فیلد فراداده متصل‌شده‌ای هستند که مقدار آن یک عدد بوده و کوچک‌تر یا بزرگ‌تر از عدد مشخص‌شده است.
برای تطبیق با فایل‌های PDF که بین ۱۰۰ تا ۲۰۰ صفحه دارند (با این فرض که ابزاری این فراداده را تنظیم کرده باشد)، از عبارت زیر استفاده کنید: metadata=pagecount>=100 and metadata=pagecount<=200
زمانی تطبیق می‌یابد که محتوا به عنوان موجود در یک نشانی وب (URL) که با glob مطابقت دارد ثبت شده باشد.
باعث می‌شود محتوا در صورتی که در حال حاضر موجود باشد مورد نیاز تلقی شود، اما در غیر این صورت خیر.
این کار انتقال دستی محتوا با استفاده از git-annex را بر عهده شما می‌گذارد. می‌توانید از این ویژگی برای جلوگیری از تأثیر تنظیمات محتوای ترجیحی بر یک زیردایرکتوری استفاده کنید. برای مثال: auto/* or (include=ad-hoc/* and present)
توجه داشته باشید که not present عبارت معقولی برای قرار دادن در یک عبارت محتوای ترجیحی نیست. این عبارت می‌گوید محتوایی را که موجود نیست دریافت کن، اما سپس آن را رها کن! اگر چنین چیزی وارد یک عبارت محتوای ترجیحی شود، git-annex تشخیص می‌دهد که عبارت پایدار نیست و ترتیبی می‌دهد که هرگز تطبیق نیابد.
باعث می‌شود اگر محتوا در دایرکتوری با نام مشخصی (واقع در هر کجای درخت دایرکتوری‌ها) باشد، ترجیح داده شود.
نام دایرکتوری را می‌توان با دستور زیر پیکربندی کرد: git annex enableremote $remote preferreddir=$dirname
(اگر هیچ نام دایرکتوری پیکربندی نشده باشد، به طور پیش‌فرض از "public" استفاده می‌شود.)
توجه داشته باشید که هنگام اجرای یک دستور با گزینه --all یا در یک مخزن bare، هیچ نام فایلی با یک شیء annex شده مرتبط نیست و بنابراین "inpreferreddir" مطابقت نخواهد یافت.
نرم‌افزار git-annex با چندین عبارت محتوای ترجیحی توکار ارائه می‌شود که می‌توانند برای مخازن موجود در گروه‌های استاندارد مانند "client" و "transfer" استفاده شوند.
هنگامی که یک مخزن دقیقاً در یکی از این گروه‌ها قرار دارد، می‌توانید از کلمه کلیدی "standard" در عبارت محتوای ترجیحی آن استفاده کنید تا با هر محتوایی که عبارت آن گروه تطبیق می‌دهد، مطابقت یابد.
اغلب، کل عبارت محتوای ترجیحی صرفاً "standard" است. اما می‌توانید کارهای پیچیده‌تری نیز انجام دهید، برای مثال: standard or include=otherdir/*
کلمه کلیدی "groupwanted" می‌تواند برای اشاره به یک عبارت محتوای ترجیحی که با یک گروه مرتبط است استفاده شود، تا زمانی که در میان گروه‌هایی که مخزن در آن‌ها عضو است، دقیقاً یک چنین عبارتی وجود داشته باشد. این کلمه کلیدی مشابه "standard" است، اما می‌توانید عبارت‌های محتوای ترجیحی را با استفاده از git annex groupwanted پیکربندی کنید.
هنگام نوشتن یک عبارت محتوای ترجیحی groupwanted، می‌توانید از تمام کلمات کلیدی مستندشده در اینجا، از جمله "standard" استفاده کنید (اما نه "groupwanted").
برای مثال، جهت ایجاد نسخه‌ای از عبارت محتوای ترجیحی استاندارد client که فایل‌های موجود در دایرکتوری "out" را نمی‌خواهد، می‌توانید دستور زیر را اجرا کنید: git annex groupwanted client "standard and exclude=out/*"
سپس مخازنی که در گروه client هستند و عبارت محتوای ترجیحی آن‌ها روی "groupwanted" تنظیم شده است از آن استفاده خواهند کرد، در حالی که سایر مخازن client که عبارت محتوای ترجیحی آن‌ها روی "standard" تنظیم است از عبارت استاندارد استفاده می‌کنند.
یا می‌توانید گروه جدیدی ایجاد کنید با عبارت محتوای ترجیحی سفارشی خود که بر اساس نیازهای شما تنظیم شده است، و هر مخزنی که در این گروه قرار دهید و محتوای ترجیحی آن را روی "groupwanted" تنظیم کنید از آن استفاده خواهد کرد.
برای مثال، گروه archive تنها می‌خواهد ۱ نسخه از هر فایل را آرشیو کند که میان تمام مخازن موجود در گروه پخش شده است. در اینجا نحوه پیکربندی گروهی به نام redundantarchive آورده شده است که در عوض می‌خواهد شامل ۳ نسخه از هر فایل باشد:
git annex groupwanted redundantarchive "not (copies=redundantarchive:3)"
for repo in foo bar baz; do
	git annex group $repo redundantarchive
	git annex wanted $repo groupwanted
done
فقط کلیدهایی را مطابقت می‌دهد که git annex unused آن‌ها را به عنوان استفاده‌نشده تشخیص داده است.
این کلمه کلیدی با گزینه --unused مرتبط است. با این حال، قرار دادن unused در یک عبارت محتوای ترجیحی باعث نمی‌شود git-annex آن کلیدهای استفاده‌نشده را بررسی کند. بنابراین وقتی git-annex فقط عبارت‌های محتوای ترجیحی را در برابر فایل‌های موجود در مخزن (که بدیهی است در حال استفاده هستند) بررسی می‌کند، unused در یک عبارت محتوای ترجیحی با هیچ چیزی مطابقت نخواهد یافت.
پس چه زمانی unused در یک عبارت محتوای ترجیحی مفید است؟
استفاده از git annex sync --content --all روی تمام فایل‌ها، از جمله فایل‌های استفاده‌نشده، عمل خواهد کرد و unused را در عبارت‌های محتوای ترجیحی در نظر می‌گیرد.
دستیار git-annex به صورت دوره‌ای فایل‌های استفاده‌نشده را پویش می‌کند و آن‌ها را به مخزنی منتقل می‌کند که عبارت محتوای ترجیحی آن بیان می‌کند که آن فایل‌ها را می‌خواهد. (یا اگر annex.expireunused تنظیم شده باشد، ممکن است صرفاً آن‌ها را حذف کند.)
باعث می‌شود محتوا به طور یکنواخت میان مخازن موجود در گروه متعادل شود.
عدد مشخص‌شده، تعداد مخازنی در گروه است که هر فایل را می‌خواهند. در صورت مشخص نشدن، مقدار پیش‌فرض ۱ است.
برای مثال، عبارت "balanced=backup:2"، هنگامی که ۳ عضو در گروه backup وجود دارد، باعث می‌شود هر مخزن پشتیبان دو سوم (۲/۳) فایل‌ها را بخواهد.
استفاده از "lackingcopies" به جای یک عدد باعث می‌شود هر فایل میان به تعداد مخازنی در گروه متعادل شود که برای برآورده کردن پیکربندی numcopies آن نیاز است. برای مثال، "balanced=backup:lackingcopies" هنگامی که numcopies برابر ۳ باشد و ۱ نسخه دیگر نیز وجود داشته باشد، رفتاری مشابه با "balanced=backup:2" خواهد داشت.
برای اینکه متعادل‌سازی کار کند، هر مخزن در گروه باید محتوای ترجیحی خود را روی همان عبارت تنظیم کرده باشد. استفاده از groupwanted روش مناسبی برای این کار است.
اندازه فایل‌ها در نظر گرفته نمی‌شود، بنابراین این امکان وجود دارد که یک مخزن فایل‌هایی بزرگ‌تر از حد معمول دریافت کند و در نتیجه زودتر از سایر مخازن پر شود. اما فایل‌ها فقط توسط مخازنی خواسته می‌شوند که فضای خالی کافی برای نگهداری آن‌ها داشته باشند. بنابراین هنگامی که یک مخزن پر شد، هر فایل اضافی میان مخازن باقی‌مانده متعادل خواهد شد. برای اینکه git-annex بداند چه زمانی یک مخزن پر شده است، باید از git-annex-maxsize(1) برای تعیین اندازه هر مخزن در گروه استفاده کنید.
این معمولاً از جابجایی فایل‌ها بین مخازن جلوگیری می‌کند، حتی اگر به این معنی باشد که موارد به طور بهینه متعادل نشده‌اند. برخی از عواملی که می‌توانند تعادل را بر هم بزنند شامل اضافه شدن یک مخزن جدید به گروه، یا کپی شدن یک فایل در تعداد مخازنی بیش از عدد مشخص‌شده در گروه، یا پر شدن برخی از مخازن است.
اجرای دستورات git-annex با گزینه --rebalance باعث می‌شود این عبارت در عوض مانند عبارت fullybalanced رفتار کند، که باعث می‌شود مخازن در صورت نیاز برای رسیدن به تعادل کامل، فایل‌ها را جابجا کنند.
استفاده از این گزینه در یک عبارت محتوای ترجیحی باعث می‌شود git-annex برای ردیابی میزان پر بودن مخازن نیاز به انجام کارهای اضافی داشته باشد. معمولاً این امر تأثیر چندانی بر کارایی نخواهد داشت. با این حال، نخستین باری که git-annex این عبارت را در یک مخزن گیت مشخص پردازش می‌کند، باید اندازه تمام مخازن را محاسبه کند که در صورت وجود فایل‌های زیاد ممکن است کند باشد. هنگامی که این موضوع باعث انجام کار زیادی توسط git-annex شود، پیام "(calculating repository sizes)" را نمایش می‌دهد.
توجه داشته باشید که not balanced به همان دلایلی که برای not present ذکر شد، مورد معقولی برای استفاده در عبارت محتوای ترجیحی نیست.
مشابه balanced است، اما اجازه می‌دهد محتوا در هر زمان بین مخازن موجود در گروه جابجا شود تا تعادل کامل حفظ گردد.
به طور معمول "balanced=groupname:number" معادل با عبارت زیر است:
"(fullybalanced=groupname:number and not copies=groupname:number) or present"
هنگامی که از گزینه --rebalance استفاده شود، balanced معادل با fullybalanced خواهد بود.
هنگامی که عدد مشخص‌شده بزرگ‌تر از ۱ باشد و مخازن بیش از حدی در گروه بیش از ۹۰٪ پر باشند (طبق تنظیم annex.fullybalancedthreshhold)، این عبارت مانند fullysizebalanced رفتار می‌کند.
برای مثال، fullybalanced=foo:3 هنگامی که گروه foo دارای ۵ مخزن است (دو مخزن ۵۰٪ پر و سه مخزن ۹۹٪ پر)، باعث می‌شود مقداری از محتوا از مخازن پر به سایر مخازن منتقل شود. جابجایی محتوا به این شکل هزینه پردازشی و زمانی بالایی دارد، اما این امکان را فراهم می‌کند که ذخیره فایل‌های جدید روی تعداد مخازن مشخص‌شده ادامه یابد.
محتوا را میان مخازن درون گروه توزیع می‌کند، به طوری که میزان پر بودن مخازن به طور متناسب حفظ شود.
عدد مشخص‌شده، تعداد مخازنی در گروه است که هر فایل را خواهند خواست. در صورت مشخص نشدن، مقدار پیش‌فرض ۱ است.
برای اینکه این سازوکار کار کند، باید از git-annex-maxsize(1) برای تعیین اندازه هر مخزن در گروه استفاده کنید. هنگامی که maxsize یک مخزن مشخص نشده باشد، آن مخزن هیچ فایلی را نخواهد خواست.
برای مثال، اگر یک مخزن در گروه حداکثر اندازه ۱۰۰ گیگابایت با ۶۰ گیگابایت مصرفی داشته باشد و مخزن دیگر دارای حداکثر اندازه ۵۰ گیگابایت با ۲۵ گیگابایت مصرفی باشد، مخزن کوچک‌تر فایل‌ها را خواهد خواست (فایل‌هایی که در آن جا می‌شوند)، و مخزن بزرگ‌تر هیچ فایلی را (که در مخزن کوچک‌تر جا شود) نمی‌خواهد تا زمانی که مخزن کوچک‌تر به همان نسبت پر شود.
توجه داشته باشید هنگامی که یک مخزن شامل فایلی باشد، حتی اگر پرتر از سایر مخازن باشد همچنان به خواستن آن ادامه خواهد داد. این امر برای جلوگیری از آشفتگی ناشی از جابجایی مداوم فایل‌ها است.
احتمال بر هم خوردن تعادل در این حالت نسبت به عبارت balanced= بیشتر است، زیرا git-annex همیشه اطلاعات یکپارچه‌ای از میزان پر بودن مخازن ندارد. به عنوان مثال وضعیتی را در نظر بگیرید که یک لپ‌تاپ و یک رایانه رومیزی هر کدام در حال ارسال یک فایل جدید به گروه هستند. هر دو مخزنی را انتخاب می‌کنند که کمترین میزان پر بودن را دارد، اما این بدان معناست که هر دو فایل به یک مخزن می‌روند، در حالی که شاید راهکار بهتر ارسال فایل کوچک‌تر به مخزنی دیگر بود. هنگام استفاده از balanced= در همان وضعیت، احتمال اینکه یک مخزن هر دو فایل را بخواهد کمتر است.
اجرای دستورات git-annex با گزینه --rebalance باعث می‌شود این عبارت در عوض مانند عبارت fullysizebalanced رفتار کند، که باعث می‌شود مخازن در صورت لزوم برای رسیدن به تعادل کامل، فایل‌ها را جابجا کنند.
توجه داشته باشید که not sizebalanced به همان دلایلی که برای not present ذکر شد، گزینه معقولی برای استفاده در عبارت محتوای ترجیحی نیست.
مشابه sizebalanced است، اما به محتوا اجازه می‌دهد در هر زمانی بین مخازن موجود در گروه جابجا شود تا تعادل کامل حفظ گردد.
به طور معمول "sizebalanced=groupname:number" معادل با عبارت زیر است:
"(fullysizebalanced=groupname:number and not copies=groupname:number) or present"
هنگامی که گزینه --rebalance استفاده شود، sizebalanced مشابه با fullysizebalanced خواهد بود.
همیشه مطابقت دارد.
هرگز مطابقت ندارد. (معادل "not anything")
آنچه را که عبارت مطابقت می‌دهد معکوس می‌کند. برای مثال، not include=archive/* مشابه exclude=archive/* است.
این موارد می‌توانند برای ساخت عبارت‌های پیچیده‌تر استفاده شوند.

برای بررسی در خط فرمان که کدام فایل‌ها با تنظیمات محتوای ترجیحی یک مخزن مطابقت دارند، می‌توانید از گزینه‌های --want-get و --want-drop استفاده کنید.

برای مثال، دستور git annex find --want-get --not --in . تمام فایل‌هایی را که git annex get --auto تمایل به دریافت آن‌ها دارد پیدا می‌کند، و دستور git annex find --want-drop --in . تمام فایل‌هایی را که git annex drop --auto تمایل به رها کردن آن‌ها دارد پیدا خواهد کرد.

گزینه --explain می‌تواند برای درک اینکه چرا یک عبارت محتوای ترجیحی پیچیده مطابقت یافته یا مطابقت نیافته است استفاده شود. عبارت نمایش داده خواهد شد و پس از هر عبارت، برای نشان دادن مقدار، عبارت "[TRUE]" یا "[FALSE]" قرار می‌گیرد. بخش‌های نامربوط از توضیح حذف خواهند شد؛ برای مثال "exclude=* and copies=1" به صورت "exclude=*[FALSE]" نمایش داده خواهد شد.

git-annex(1)

git-annex-vicfg(1)

git-annex-wanted(1)

git-annex-maxsize(1)

https://git-annex.branchable.com/preferred_content

https://git-annex.branchable.com/preferred_content/standard_groups

Joey Hess <id@joeyh.name>

http://git-annex.branchable.com