VCSH(1) General Commands Manual VCSH(1)

vcsh - سامانه کنترل نسخه برای $HOME - چندین مخزن Git در $HOME

vcsh [options] command

vcsh clone [-b branch] url [repo]

vcsh delete repo

vcsh enter repo

vcsh foreach [-g] git command

vcsh help

vcsh init repo

vcsh list

vcsh list-tracked [repo]

vcsh list-untracked [-a] [-r] [repo]

vcsh pull

vcsh push

vcsh rename repo newname

vcsh run repo shell command

vcsh status [repo]

vcsh upgrade repo

vcsh version

vcsh which substring

vcsh write-gitignore [repo]

vcsh repo gitcommand

vcsh repo

برنامه vcsh به شما امکان می‌دهد چندین مخزن git(1) داشته باشید که همگی درخت کاری (working tree) خود را در $HOME نگهداری می‌کنند بدون آنکه با یکدیگر تداخل داشته باشند یا یکدیگر را بازنویسی کنند. این ویژگی بدان معناست که می‌توانید برای هر مجموعه پیکربندی (مانند zsh، vim، ssh و غیره) یک مخزن جداگانه داشته باشید و به دلخواه مشخص کنید کدام پیکربندی‌ها روی کدام رایانه استفاده شوند.

برنامه vcsh از روشی به نام مخازن ساختگیِ خالص گیت (fake bare Git repositories) استفاده می‌کند که در آن $GIT_DIR در دایرکتوری متفاوتی نسبت به $GIT_WORK_TREE که به $HOME اشاره دارد نگهداری می‌شود.

در این ساختار نیازی به استفاده از پیوندهای نمادین (symlinks) نیست، که موجب تمیزتر شدن پیکربندی می‌شود.

برنامه vcsh با در نظر گرفتن ابزار mr(1) طراحی شده است؛ بنابراین شاید تمایل داشته باشید آن را در کنار vcsh نصب کنید. با این حال، در صورت تمایل می‌توانید به آسانی از vcsh بدون mr نیز استفاده نمایید.

یک نمونه پیکربندی برای vcsh و mr در نشانی https://github.com/RichiH/vcsh_mr_template موجود است و می‌توان آن را با دستور vcsh clone https://github.com/RichiH/vcsh_mr_template mr استفاده کرد.

لطفاً توجه داشته باشید که همیشه می‌توانید به جای نام، یک مسیر را برای repo وارد کنید. این موضوع برای پشتیبانی صحیح از mr و دیگر اسکریپت‌ها الزامی است و برای کاربران تعاملی اهمیتی ندارد.

بارگذاری و فراخوانی (source) فایل file پیش از سایر فایل‌های پیکربندی.
فعال‌سازی حالت اشکال‌زدایی (debug).
فعال‌سازی حالت پرگو (verbose).

شبیه‌سازی (clone) یک مخزن موجود.
اگر نیاز دارید مجموعه‌ای از مخازن را کلون کنید، قلاب post-clone-retired را بررسی نمایید.
همچنین می‌توانید از یک مخزن گیت واحد با چندین شاخه استفاده کنید. با استفاده از گزینه -b شاخه مورد نظر را در هنگام کلون تعیین کنید؛ شاخه پیش‌فرض master است.
ثبت تغییرات (commit) در تمام مخازن.
حذف یک مخزن موجود.
ورود به مخزن؛ اجرای یک $SHELL جدید در حالی که متغیر $GIT_DIR تنظیم شده است.
اجرای دستور git برای تک‌تک مخازن vcsh.
-g: اجرا در بافت عمومی (general context).
نمایش راهنما.
مقداردهی اولیه یک مخزن خالی.
فهرست کردن تمام مخازن محلی vcsh.
list-tracked
فهرست کردن تمام فایل‌های ردیابی‌شده توسط vcsh.
اگر می‌خواهید فایل‌های ردیابی‌شده توسط یک مخزن خاص را مشاهده کنید، کافی است نام مخزن را در پایان دستور اضافه نمایید.
list-tracked-by
فهرست کردن فایل‌های ردیابی‌شده توسط یک مخزن.
این یک دستور قدیمی و منسوخ است؛ باید به جای آن از list-tracked <repo> استفاده کنید.
list-untracked
فهرست کردن تمام فایل‌هایی که توسط vcsh ردیابی نشده‌اند.
-a: نمایش تمام فایل‌ها. به صورت پیش‌فرض دستور git ls-files --exclude-standard فراخوانی می‌شود.
-r: حالت بازگشتی (recursive). به صورت پیش‌فرض، فهرست فایل‌ها سطحی است و تا جای ممکن در سطح دایرکتوری متوقف می‌شود.
$repo: فهرست کردن فایل‌هایی که توسط این مخزن به‌خصوص ردیابی نشده‌اند.
دریافت تغییرات (pull) از تمام ریموت‌های vcsh.
ارسال تغییرات (push) به تمام ریموت‌های vcsh.
تغییر نام یک مخزن.
اجرای دستور با تنظیم متغیرهای $GIT_DIR و $GIT_WORK_TREE. این دستور به شما اجازه می‌دهد هر دستوری را بدون هیچ محدودیتی اجرا کنید. با احتیاط استفاده شود.
توجه داشته باشید که یک ویژگی ویژه برای دستور run وجود دارد: علاوه بر repo، یک path (مسیر) را نیز می‌پذیرد. هر مقداری که دارای خط مورب (slash) باشد، مسیر در نظر گرفته می‌شود. سپس vcsh run به جای دایرکتوری‌ای که طبق روال معمول از نام مخزن به دست می‌آید، روی این دایرکتوری عمل می‌کند. این سازوکار برای پشتیبانی مناسب از mr و سایر اسکریپت‌ها ضروری بوده و به کاربر تعاملی ارتباطی ندارد.
نمایش وضعیت تمام مخازن vcsh یا یکی از آن‌ها.
ارتقای مخزن به تنظیمات توصیه‌شده فعلی.
چاپ اطلاعات نسخه.
یافتن substring در نام تمام فایل‌های ردیابی‌شده.
نوشتن .gitignore.d/repo از طریق git ls-files. اگر repo مشخص نشده باشد اما در داخل یک مخزن vcsh باشیم، از همان مخزن استفاده می‌شود.
میان‌بری برای اجرای دستورات git روی یک مخزن. عبارت git را قبل از gitcommand اضافه می‌کند.
میان‌بری برای اجرای دستور vcsh enter <repo>.

همان‌طور که پیش‌تر گفته شد، vcsh مقادیر متغیرهای $GIT_DIR و $GIT_WORK_TREE را برای مخازن ساختگی خالص Git به مقادیر مناسب تنظیم می‌کند.

چندین راه برای تنظیم گزینه‌های مختلف در vcsh وجود دارد. این روش‌ها به ترتیب صعودی اولویت عبارتند از:

○
VARIABLE=foo vcsh
○
</etc/vcsh/config>
○
<$XDG_CONFIG_HOME/vcsh/config>
○
vcsh -c <file>

لطفاً توجه داشته باشید که این فایل‌ها فراخوانی (source) می‌شوند؛ تمام دستورات در بافتار پوسته شما اجرا خواهند شد.

متغیرهای مهمی که می‌توانید تنظیم کنید:

$VCSH_GITATTRIBUTES
می‌تواند none یا هر مقدار دیگری باشد.
مقدار none مشخصات گیت را در مکان ویژه‌ای نگهداری نمی‌کند.
اگر روی مقدار دیگری تنظیم شود، فایل‌های gitattributes مختص هر مخزن مدیریت خواهند شد.
پیش‌فرض آن none است.
$VCSH_GITIGNORE
می‌تواند exact، none یا recursive باشد.
مقدار exact فایل ignore مختص مخزن را با تمام نام‌های فایل و دایرکتوری حاصل از git ls-files پر می‌کند.
مقدار none هیچ فایل چشم‌پوشی‌ای ایجاد نمی‌کند.
مقدار recursive علاوه بر حالت بالا، به صورت بازگشتی در تمام دایرکتوری‌ها پیمایش می‌کند.
پیش‌فرض آن exact است.
$VCSH_WORKTREE
می‌تواند absolute یا relative باشد.
مقدار absolute یک مسیر مطلق تنظیم می‌کند؛ که پیش‌فرض آن $HOME است.
مقدار relative یک مسیر نسبی به $GIT_DIR تنظیم می‌کند.
پیش‌فرض آن absolute است.

متغیرهای کم‌کاربردتری که می‌توانید تنظیم کنید:

$VCSH_DEBUG
ورود به حالت اشکال‌زدایی (debug).
$XDG_CONFIG_HOME
همان‌طور که در «مشخصات دایرکتوری پایه XDG» تعیین شده است، ببینید: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
پیش‌فرض آن <$HOME/.config> است.
$VCSH_REPO_D
دایرکتوری‌ای که مخازن از آن خوانده شده و در آن ذخیره می‌شوند.
پیش‌فرض آن <$XDG_CONFIG_HOME/vcsh/repo.d> است.
$VCSH_HOOK_D
دایرکتوری‌ای که قلاب‌ها از آن فراخوانی می‌شوند.
پیش‌فرض آن <$XDG_CONFIG_HOME/vcsh/hooks-enabled> است.
$VCSH_BASE
دایرکتوری‌ای که مخازن در آن تحویل گرفته (checked out) می‌شوند.
پیش‌فرض آن $HOME است.

برنامه vcsh سامانه‌ای برای قلاب‌ها (hooks) فراهم می‌کند. اسکریپت‌های قلاب باید قابل اجرا (executable) باشند و در مسیر <$XDG_CONFIG_HOME/vcsh/hooks-available> قرار گیرند. از آنجا می‌توان آن‌ها را به <$XDG_CONFIG_HOME/vcsh/hooks-enabled> پیوند نمادین (soft-link) داد؛ vcsh تنها قلاب‌هایی را که در این دایرکتوری قرار دارند اجرا خواهد کرد.

قلاب‌ها از قالب ساده‌ای پیروی می‌کنند. اسکریپت pre-run پیش از اجرای هر کاری فراخوانی می‌شود. اگر می‌خواهید برای یک قلاب خاص چندین اسکریپت داشته باشید، تنها کافی است هر نوع رشته‌ای را برای ترتیب‌بندی به انتهای آن بیافزایید. ساختاری مانند pre-run، <pre-run.10>، <pre-run.20> و غیره پیشنهاد می‌شود؛ انتخاب‌های دیگر pre-run-10 یا <pre-run.sh> هستند. گذاشتن نقطه پس از نام قلاب اختیاری است.

اگر قصد دارید قلاب‌هایی برای یک مخزن خاص vcsh بسازید، کافی است نام مخزن و سپس یک نقطه را در ابتدای نام قلاب قرار دهید، مانند <zsh.pre-run>. در غیر این صورت، همان قواعد بالا صادق است. با این حال، درج نقطه میان نام مخزن و نام قلاب الزامی است.

قلاب‌های در دسترس عبارتند از: pre-clone، post-clone، post-clone-retired، pre-command، post-command، pre-enter، post-enter، pre-init، post-init، pre-pull، post-pull، pre-push، post-push، pre-run، post-run، pre-upgrade و post-upgrade. اگر به قلاب‌های بیشتری نیاز دارید، پچ کردن vcsh بسیار ساده است، اما لطفاً به پروژه بالادست گزارش دهید تا بتوانیم آن‌ها را به صورت پیش‌فرض اضافه کنیم.

برنامه vcsh همچنین یک سامانه همپوشانی (overlay) فراهم می‌کند. همانند قلاب‌ها، مسیرهای توصیه‌شده برای این بخش <$XDG_CONFIG_HOME/vcsh/overlays-available> و <$XDG_CONFIG_HOME/vcsh/overlays-enabled> هستند.

همپوشانی‌ها از همان قوانین قلاب‌ها پیروی می‌کنند و شما می‌توانید هر تابعی را بازنویسی کنید. درست مانند قلاب‌ها، می‌توانید با استفاده از <$VCSH_OVERLAY_D/$VCSH_COMMAND> یا <$VCSH_OVERLAY_D/$VCSH_REPO_NAME.$VCSH_COMMAND> از همپوشانی‌های سراسری یا ویژه یک مخزن استفاده کنید.

لطفاً توجه داشته باشید که هیچ مانعی برای مثال برای بازنویسی status() در <$VCSH_OVERLAY_D/commit> وجود ندارد. از آنجا که همپوشانی‌ها فراخوانی (source) می‌شوند و شما توابع دلخواه را جایگزین می‌کنید، ممکن است هر یک از قابلیت‌ها از کار بیفتد یا حتی داده‌هایتان از دست برود.

مسئولیت عواقب آن بر عهده خودتان است.

صفحات راهنما (man pages) معمولاً مختصرند و گاهی برای یادگیری بهترین شیوه‌ها کاربردی ندارند. هرچند نویسنده در این مورد تلاش کرده تا از این مسأله پرهیز کند، اما صفحات راهنما نمی‌توانند تمام آموزش‌های گام‌به‌گام را پوشش دهند.

این نرم‌افزار همچنین همراه با فایلی به نام <README.md> عرضه می‌شود. این فایل شامل روش‌های گوناگونی برای راه‌اندازی و استفاده از vcsh است. می‌توانید این فایل را به صورت متن ساده مشاهده کنید یا از طریق Markdown به فرمت‌های دیگر تبدیل نمایید.

در توزیع‌های مبتنی بر دبیان، این فایل را می‌توان در </usr/share/doc/vcsh> پیدا کرد.

برنامه vcsh به شما اجازه می‌دهد از طریق vcsh run دستورات دلخواه را اجرا کنید. برای نمونه، افزودن یک قاعده sudo(8) برای vcsh کار کاملاً اشتباهی خواهد بود.

علاوه بر این، vcsh تمام فایل‌های فهرست‌شده در بخش CONFIG را فراخوانی (source)، یعنی اجرا می‌کند. می‌توانید هر دستوری را درون این فایل‌های پیکربندی قرار دهید و آن‌ها اجرا خواهند شد.

در حال حاضر هیچ باگی شناخته نشده است، اما از گزارش‌ها و پچ‌ها به گرمی استقبال می‌شود.

اگر به git submodule اتکا دارید، از git نسخه 1.7.12 یا بالاتر استفاده کنید. نسخه‌های قدیمی‌تر متغیرهای داخلی را پیش از ورود به زیرماژول‌ها به درستی پاکسازی نمی‌کنند، که منجر به بروز مشکل برای کاربران خواهد شد.

همانند بیشتر افراد، نویسنده در ابتدا کار خود را با یک مخزن واحد برای تمام فایل‌های پیکربندی پیش می‌برد که همگی آن‌ها به $HOME پیوند نمادین شده بودند.

مارتین اف. کرافت (Martin F. Krafft) ملقب به madduck ایده مخازن ساختگی خالص گیت (fake bare Git repositories) را مطرح کرد.

برنامه vcsh در ابتدا توسط madduck نوشته شد. نسخه حاضر یک بازپیاده‌سازی کامل از ابتدا با قابلیت‌های بسیار بیشتر است. madduck با بزرگواری اجازه داد تا نویسنده نام این پروژه را ادامه دهد.

این صفحه راهنما و خود vcsh توسط ریچارد «RichiH» هارتمن (Richard Hartmann) نوشته شده‌اند.

حق نشر ۲۰۱۱-۲۰۱۵ ریچارد هارتمن richih@debian.org

تحت مجوز GNU GPL نسخه ۲ یا بالاتر منتشر شده است.

https://github.com/RichiH/vcsh

git(1), mr(1)

April 2024