.\" generated with Ronn-NG/v0.9.1
.\" http://github.com/apjanke/ronn-ng/tree/0.9.1
.TH "VCSH" "1" "April 2024" ""
.SH "نام (NAME)"
\fBvcsh\fR \- سامانه کنترل نسخه برای $HOME \- چندین مخزن Git در $HOME
.SH "خلاصه دستور (SYNOPSIS)"
\fBvcsh\fR [\fIoptions\fR] \fIcommand\fR
.P
\fBvcsh\fR clone [\-b \fIbranch\fR] \fIurl\fR [\fIrepo\fR]
.P
\fBvcsh\fR delete \fIrepo\fR
.P
\fBvcsh\fR enter \fIrepo\fR
.P
\fBvcsh\fR foreach [\-g] \fIgit command\fR
.P
\fBvcsh\fR help
.P
\fBvcsh\fR init \fIrepo\fR
.P
\fBvcsh\fR list
.P
\fBvcsh\fR list\-tracked [\fIrepo\fR]
.P
\fBvcsh\fR list\-untracked [\fI\-a\fR] [\fI\-r\fR] [\fIrepo\fR]
.P
\fBvcsh\fR pull
.P
\fBvcsh\fR push
.P
\fBvcsh\fR rename \fIrepo\fR \fInewname\fR
.P
\fBvcsh\fR run \fIrepo\fR \fIshell command\fR
.P
\fBvcsh\fR status [\fIrepo\fR]
.P
\fBvcsh\fR upgrade \fIrepo\fR
.P
\fBvcsh\fR version
.P
\fBvcsh\fR which \fIsubstring\fR
.P
\fBvcsh\fR write\-gitignore [\fIrepo\fR]
.P
\fBvcsh\fR \fIrepo\fR \fIgitcommand\fR
.P
\fBvcsh\fR \fIrepo\fR
.SH "توضیحات (DESCRIPTION)"
برنامه \fBvcsh\fR به شما امکان می‌دهد چندین مخزن \fBgit\fR(1) داشته باشید که همگی درخت کاری (working tree) خود را در \fI$HOME\fR نگهداری می‌کنند بدون آنکه با یکدیگر تداخل داشته باشند یا یکدیگر را بازنویسی کنند\. این ویژگی بدان معناست که می‌توانید برای هر مجموعه پیکربندی (مانند zsh، vim، ssh و غیره) یک مخزن جداگانه داشته باشید و به دلخواه مشخص کنید کدام پیکربندی‌ها روی کدام رایانه استفاده شوند\.
.P
برنامه \fBvcsh\fR از روشی به نام مخازن ساختگیِ خالص گیت (fake bare Git repositories) استفاده می‌کند که در آن \fI$GIT_DIR\fR در دایرکتوری متفاوتی نسبت به \fI$GIT_WORK_TREE\fR که به \fI$HOME\fR اشاره دارد نگهداری می‌شود\.
.P
در این ساختار نیازی به استفاده از پیوندهای نمادین (symlinks) نیست، که موجب تمیزتر شدن پیکربندی می‌شود\.
.P
برنامه \fBvcsh\fR با در نظر گرفتن ابزار \fBmr\fR(1) طراحی شده است؛ بنابراین شاید تمایل داشته باشید آن را در کنار vcsh نصب کنید\. با این حال، در صورت تمایل می‌توانید به آسانی از \fBvcsh\fR بدون \fBmr\fR نیز استفاده نمایید\.
.P
یک نمونه پیکربندی برای \fBvcsh\fR و \fBmr\fR در نشانی \fIhttps://github\.com/RichiH/vcsh_mr_template\fR موجود است و می‌توان آن را با دستور \fBvcsh clone https://github\.com/RichiH/vcsh_mr_template mr\fR استفاده کرد\.
.P
لطفاً توجه داشته باشید که همیشه می‌توانید به جای نام، یک مسیر را برای \fIrepo\fR وارد کنید\. این موضوع برای پشتیبانی صحیح از mr و دیگر اسکریپت‌ها الزامی است و برای کاربران تعاملی اهمیتی ندارد\.
.SH "گزینه‌ها (OPTIONS)"
.TP
\-c
بارگذاری و فراخوانی (\fIsource\fR) فایل \fIfile\fR پیش از سایر فایل‌های پیکربندی\.
.TP
\-d
فعال‌سازی حالت اشکال‌زدایی (debug)\.
.TP
\-v
فعال‌سازی حالت پرگو (verbose)\.
.SH "دستورها (COMMANDS)"
.TP
clone
شبیه‌سازی (clone) یک مخزن موجود\.
.IP
اگر نیاز دارید مجموعه‌ای از مخازن را کلون کنید، قلاب \fBpost\-clone\-retired\fR را بررسی نمایید\.
.IP
همچنین می‌توانید از یک مخزن گیت واحد با چندین شاخه استفاده کنید\. با استفاده از گزینه \fB\-b\fR شاخه مورد نظر را در هنگام کلون تعیین کنید؛ شاخه پیش‌فرض \fBmaster\fR است\.
.TP
commit
ثبت تغییرات (commit) در تمام مخازن\.
.TP
delete
حذف یک مخزن موجود\.
.TP
enter
ورود به مخزن؛ اجرای یک \fI$SHELL\fR جدید در حالی که متغیر \fI$GIT_DIR\fR تنظیم شده است\.
.TP
foreach
اجرای دستور git برای تک‌تک مخازن vcsh\.
.IP
\fB\-g\fR: اجرا در بافت عمومی (general context)\.
.TP
help
نمایش راهنما\.
.TP
init
مقداردهی اولیه یک مخزن خالی\.
.TP
list
فهرست کردن تمام مخازن محلی vcsh\.
.TP
list\-tracked
فهرست کردن تمام فایل‌های ردیابی‌شده توسط vcsh\.
.IP
اگر می‌خواهید فایل‌های ردیابی‌شده توسط یک مخزن خاص را مشاهده کنید، کافی است نام مخزن را در پایان دستور اضافه نمایید\.
.TP
list\-tracked\-by
فهرست کردن فایل‌های ردیابی‌شده توسط یک مخزن\.
.IP
این یک دستور قدیمی و منسوخ است؛ باید به جای آن از \fBlist\-tracked <repo>\fR استفاده کنید\.
.TP
list\-untracked
فهرست کردن تمام فایل‌هایی که توسط vcsh ردیابی \fBنشده‌اند\fR\.
.IP
\fB\-a\fR: نمایش تمام فایل‌ها\. به صورت پیش‌فرض دستور \fBgit ls\-files \-\-exclude\-standard\fR فراخوانی می‌شود\.
.IP
\fB\-r\fR: حالت بازگشتی (recursive)\. به صورت پیش‌فرض، فهرست فایل‌ها سطحی است و تا جای ممکن در سطح دایرکتوری متوقف می‌شود\.
.IP
\fB$repo\fR: فهرست کردن فایل‌هایی که توسط این مخزن به‌خصوص ردیابی نشده‌اند\.
.TP
pull
دریافت تغییرات (pull) از تمام ریموت‌های vcsh\.
.TP
push
ارسال تغییرات (push) به تمام ریموت‌های vcsh\.
.TP
rename
تغییر نام یک مخزن\.
.TP
run
اجرای دستور با تنظیم متغیرهای \fI$GIT_DIR\fR و \fI$GIT_WORK_TREE\fR\. این دستور به شما اجازه می‌دهد هر دستوری را بدون هیچ محدودیتی اجرا کنید\. با احتیاط استفاده شود\.
.IP
توجه داشته باشید که یک ویژگی ویژه برای دستور run وجود دارد: علاوه بر \fIrepo\fR، یک \fIpath\fR (مسیر) را نیز می‌پذیرد\. هر مقداری که دارای خط مورب (slash) باشد، مسیر در نظر گرفته می‌شود\. سپس \fBvcsh run\fR به جای دایرکتوری‌ای که طبق روال معمول از نام مخزن به دست می‌آید، روی این دایرکتوری عمل می‌کند\. این سازوکار برای پشتیبانی مناسب از mr و سایر اسکریپت‌ها ضروری بوده و به کاربر تعاملی ارتباطی ندارد\.
.TP
status
نمایش وضعیت تمام مخازن vcsh یا یکی از آن‌ها\.
.TP
upgrade
ارتقای مخزن به تنظیمات توصیه‌شده فعلی\.
.TP
version
چاپ اطلاعات نسخه\.
.TP
which \fIsubstring\fR
یافتن \fIsubstring\fR در نام تمام فایل‌های ردیابی‌شده\.
.TP
write\-gitignore
نوشتن \.gitignore\.d/\fIrepo\fR از طریق \fBgit ls\-files\fR\. اگر \fIrepo\fR مشخص نشده باشد اما در داخل یک مخزن vcsh باشیم، از همان مخزن استفاده می‌شود\.
.TP
\fIrepo\fR \fIgitcommand\fR
میان‌بری برای اجرای دستورات \fBgit\fR روی یک مخزن\. عبارت \fBgit\fR را قبل از \fIgitcommand\fR اضافه می‌کند\.
.TP
\fIrepo\fR
میان‌بری برای اجرای دستور \fBvcsh enter <repo>\fR\.
.SH "محیط (ENVIRONMENT)"
همان‌طور که پیش‌تر گفته شد، \fBvcsh\fR مقادیر متغیرهای \fI$GIT_DIR\fR و \fI$GIT_WORK_TREE\fR را برای مخازن ساختگی خالص Git به مقادیر مناسب تنظیم می‌کند\.
.SH "پیکربندی (CONFIG)"
چندین راه برای تنظیم گزینه‌های مختلف در \fBvcsh\fR وجود دارد\. این روش‌ها به ترتیب صعودی اولویت عبارتند از:
.IP "\[ci]" 4
\fBVARIABLE=foo vcsh\fR
.IP "\[ci]" 4
</etc/vcsh/config>
.IP "\[ci]" 4
<$XDG_CONFIG_HOME/vcsh/config>
.IP "\[ci]" 4
\fBvcsh \-c <file>\fR
.IP "" 0
.P
لطفاً توجه داشته باشید که این فایل‌ها فراخوانی (source) می‌شوند؛ تمام دستورات در بافتار پوسته شما اجرا خواهند شد\.
.P
متغیرهای مهمی که می‌توانید تنظیم کنید:
.TP
\fI$VCSH_GITATTRIBUTES\fR
می‌تواند \fInone\fR یا هر مقدار دیگری باشد\.
.IP
مقدار \fInone\fR مشخصات گیت را در مکان ویژه‌ای نگهداری نمی‌کند\.
.IP
اگر روی مقدار دیگری تنظیم شود، فایل‌های gitattributes مختص هر مخزن مدیریت خواهند شد\.
.IP
پیش‌فرض آن \fInone\fR است\.
.TP
\fI$VCSH_GITIGNORE\fR
می‌تواند \fIexact\fR، \fInone\fR یا \fIrecursive\fR باشد\.
.IP
مقدار \fIexact\fR فایل ignore مختص مخزن را با تمام نام‌های فایل و دایرکتوری حاصل از \fBgit ls\-files\fR پر می‌کند\.
.IP
مقدار \fInone\fR هیچ فایل چشم‌پوشی‌ای ایجاد نمی‌کند\.
.IP
مقدار \fIrecursive\fR علاوه بر حالت بالا، به صورت بازگشتی در تمام دایرکتوری‌ها پیمایش می‌کند\.
.IP
پیش‌فرض آن \fIexact\fR است\.
.TP
\fI$VCSH_WORKTREE\fR
می‌تواند \fIabsolute\fR یا \fIrelative\fR باشد\.
.IP
مقدار \fIabsolute\fR یک مسیر مطلق تنظیم می‌کند؛ که پیش‌فرض آن \fI$HOME\fR است\.
.IP
مقدار \fIrelative\fR یک مسیر نسبی به \fI$GIT_DIR\fR تنظیم می‌کند\.
.IP
پیش‌فرض آن \fIabsolute\fR است\.
.P
متغیرهای کم‌کاربردتری که می‌توانید تنظیم کنید:
.TP
\fI$VCSH_DEBUG\fR
ورود به حالت اشکال‌زدایی (debug)\.
.TP
\fI$XDG_CONFIG_HOME\fR
همان‌طور که در «مشخصات دایرکتوری پایه XDG» تعیین شده است، ببینید: \fIhttp://standards\.freedesktop\.org/basedir\-spec/basedir\-spec\-latest\.html\fR
.IP
پیش‌فرض آن <$HOME/\.config> است\.
.TP
\fI$VCSH_REPO_D\fR
دایرکتوری‌ای که مخازن از آن خوانده شده و در آن ذخیره می‌شوند\.
.IP
پیش‌فرض آن <$XDG_CONFIG_HOME/vcsh/repo\.d> است\.
.TP
\fI$VCSH_HOOK_D\fR
دایرکتوری‌ای که قلاب‌ها از آن فراخوانی می‌شوند\.
.IP
پیش‌فرض آن <$XDG_CONFIG_HOME/vcsh/hooks\-enabled> است\.
.TP
\fI$VCSH_BASE\fR
دایرکتوری‌ای که مخازن در آن تحویل گرفته (checked out) می‌شوند\.
.IP
پیش‌فرض آن \fI$HOME\fR است\.
.SH "سامانه قلاب‌ها (HOOK SYSTEM)"
برنامه \fBvcsh\fR سامانه‌ای برای قلاب‌ها (hooks) فراهم می‌کند\. اسکریپت‌های قلاب باید قابل اجرا (executable) باشند و در مسیر <$XDG_CONFIG_HOME/vcsh/hooks\-available> قرار گیرند\. از آنجا می‌توان آن‌ها را به <$XDG_CONFIG_HOME/vcsh/hooks\-enabled> پیوند نمادین (soft-link) داد؛ \fBvcsh\fR تنها قلاب‌هایی را که در این دایرکتوری قرار دارند اجرا خواهد کرد\.
.P
قلاب‌ها از قالب ساده‌ای پیروی می‌کنند\. اسکریپت \fIpre\-run\fR پیش از اجرای هر کاری فراخوانی می‌شود\. اگر می‌خواهید برای یک قلاب خاص چندین اسکریپت داشته باشید، تنها کافی است هر نوع رشته‌ای را برای ترتیب‌بندی به انتهای آن بیافزایید\. ساختاری مانند \fIpre\-run\fR، <pre\-run\.10>، <pre\-run\.20> و غیره پیشنهاد می‌شود؛ انتخاب‌های دیگر \fIpre\-run\-10\fR یا <pre\-run\.sh> هستند\. گذاشتن نقطه پس از نام قلاب اختیاری است\.
.P
اگر قصد دارید قلاب‌هایی برای یک مخزن خاص \fIvcsh\fR بسازید، کافی است نام مخزن و سپس یک نقطه را در ابتدای نام قلاب قرار دهید، مانند <zsh\.pre\-run>\. در غیر این صورت، همان قواعد بالا صادق است\. با این حال، درج نقطه میان نام مخزن و نام قلاب الزامی است\.
.P
قلاب‌های در دسترس عبارتند از: \fIpre\-clone\fR، \fIpost\-clone\fR، \fIpost\-clone\-retired\fR، \fIpre\-command\fR، \fIpost\-command\fR، \fIpre\-enter\fR، \fIpost\-enter\fR، \fIpre\-init\fR، \fIpost\-init\fR، \fIpre\-pull\fR، \fIpost\-pull\fR، \fIpre\-push\fR، \fIpost\-push\fR، \fIpre\-run\fR، \fIpost\-run\fR، \fIpre\-upgrade\fR و \fIpost\-upgrade\fR\. اگر به قلاب‌های بیشتری نیاز دارید، پچ کردن vcsh بسیار ساده است، اما لطفاً به پروژه بالادست گزارش دهید تا بتوانیم آن‌ها را به صورت پیش‌فرض اضافه کنیم\.
.SH "سامانه همپوشانی (OVERLAY SYSTEM)"
برنامه \fBvcsh\fR همچنین یک سامانه همپوشانی (overlay) فراهم می‌کند\. همانند قلاب‌ها، مسیرهای توصیه‌شده برای این بخش <$XDG_CONFIG_HOME/vcsh/overlays\-available> و <$XDG_CONFIG_HOME/vcsh/overlays\-enabled> هستند\.
.P
همپوشانی‌ها از همان قوانین قلاب‌ها پیروی می‌کنند و شما می‌توانید هر تابعی را بازنویسی کنید\. درست مانند قلاب‌ها، می‌توانید با استفاده از <$VCSH_OVERLAY_D/$VCSH_COMMAND> یا <$VCSH_OVERLAY_D/$VCSH_REPO_NAME\.$VCSH_COMMAND> از همپوشانی‌های سراسری یا ویژه یک مخزن استفاده کنید\.
.P
لطفاً توجه داشته باشید که هیچ مانعی برای مثال برای بازنویسی \fBstatus()\fR در <$VCSH_OVERLAY_D/commit> وجود ندارد\. از آنجا که همپوشانی‌ها فراخوانی (source) می‌شوند و شما توابع دلخواه را جایگزین می‌کنید، ممکن است هر یک از قابلیت‌ها از کار بیفتد یا حتی داده‌هایتان از دست برود\.
.P
مسئولیت عواقب آن بر عهده خودتان است\.
.SH "راهنمای تفصیلی و مطالعه بیشتر (DETAILED HOWTO AND FURTHER READING)"
صفحات راهنما (man pages) معمولاً مختصرند و گاهی برای یادگیری بهترین شیوه‌ها کاربردی ندارند\. هرچند نویسنده در این مورد تلاش کرده تا از این مسأله پرهیز کند، اما صفحات راهنما نمی‌توانند تمام آموزش‌های گام‌به‌گام را پوشش دهند\.
.P
این نرم‌افزار همچنین همراه با فایلی به نام <README\.md> عرضه می‌شود\. این فایل شامل روش‌های گوناگونی برای راه‌اندازی و استفاده از vcsh است\. می‌توانید این فایل را به صورت متن ساده مشاهده کنید یا از طریق Markdown به فرمت‌های دیگر تبدیل نمایید\.
.P
در توزیع‌های مبتنی بر دبیان، این فایل را می‌توان در </usr/share/doc/vcsh> پیدا کرد\.
.SH "ملاحظات امنیتی (SECURITY CONSIDERATIONS)"
برنامه \fBvcsh\fR به شما اجازه می‌دهد از طریق \fBvcsh run\fR دستورات دلخواه را اجرا کنید\. برای نمونه، افزودن یک قاعده \fBsudo\fR(8) برای \fBvcsh\fR کار کاملاً اشتباهی خواهد بود\.
.P
علاوه بر این، vcsh تمام فایل‌های فهرست‌شده در بخش \fICONFIG\fR را فراخوانی (source)، یعنی اجرا می‌کند\. می‌توانید هر دستوری را درون این فایل‌های پیکربندی قرار دهید و آن‌ها اجرا خواهند شد\.
.SH "گزارش باگ‌ها (BUGS)"
در حال حاضر هیچ باگی شناخته نشده است، اما از گزارش‌ها و پچ‌ها به گرمی استقبال می‌شود\.
.SH "سازگاری و تعامل‌پذیری (INTEROPERABILITY)"
اگر به \fBgit submodule\fR اتکا دارید، از \fBgit\fR نسخه 1\.7\.12 یا بالاتر استفاده کنید\. نسخه‌های قدیمی‌تر متغیرهای داخلی را پیش از ورود به زیرماژول‌ها به درستی پاکسازی نمی‌کنند، که منجر به بروز مشکل برای کاربران خواهد شد\.
.SH "تاریخچه (HISTORY)"
همانند بیشتر افراد، نویسنده در ابتدا کار خود را با یک مخزن واحد برای تمام فایل‌های پیکربندی پیش می‌برد که همگی آن‌ها به \fI$HOME\fR پیوند نمادین شده بودند\.
.P
مارتین اف\. کرافت (Martin F. Krafft) ملقب به madduck ایده مخازن ساختگی خالص گیت (fake bare Git repositories) را مطرح کرد\.
.P
برنامه vcsh در ابتدا توسط madduck نوشته شد\. نسخه حاضر یک بازپیاده‌سازی کامل از ابتدا با قابلیت‌های بسیار بیشتر است\. madduck با بزرگواری اجازه داد تا نویسنده نام این پروژه را ادامه دهد\.
.SH "نویسندگان (AUTHORS)"
این صفحه راهنما و خود \fBvcsh\fR توسط ریچارد «RichiH» هارتمن (Richard Hartmann) نوشته شده‌اند\.
.SH "کپی‌رایت و تکثیر (COPYRIGHT)"
حق نشر ۲۰۱۱\-۲۰۱۵ ریچارد هارتمن \fIrichih@debian\.org\fR
.P
تحت مجوز GNU GPL نسخه ۲ یا بالاتر منتشر شده است\.
.P
https://github\.com/RichiH/vcsh
.SH "همچنین ببینید (SEE ALSO)"
\fBgit\fR(1), \fBmr\fR(1)