GIT-LFS-COMPLETION(1)   GIT-LFS-COMPLETION(1)

git-lfs-completion - تولید اسکریپت شل برای تکمیل خودکار دستورهای Git LFS

git lfs completion bash
git lfs completion fish
git lfs completion zsh

اسکریپتی را در خروجی تولید می‌کند که با اجرا در یک نشست از شل مشخص‌شده، تکمیل خودکار با کلید تب (tab-completion) در خط فرمان را برای دستورهای Git LFS پیاده‌سازی می‌نماید.

هر شل برای بارگیری اسکریپت تکمیل، چه برای یک نشست منفرد یا به‌طور خودکار هنگام شروع هر نشست جدید، به مجموعه دستورهای متفاوتی نیاز دارد. برای جزئیات، بخش «مثال‌ها (EXAMPLES)» را ببینید.

اسکریپت مربوط به هر شل، امکان تکمیل کلید تب را برای نام‌ها و فلگ‌های دستورهای Git LFS فراهم می‌کند، اما تکمیل اصطلاحات گیت مانند نام‌های ریموت‌ها، شاخه‌ها یا تگ‌های گیت را ارائه نمی‌دهد. (این مورد ممکن است در نگارش‌های آیندهٔ Git LFS تغییر کند.)

به‌طور پیش‌فرض، اسکریپت هر شل از تکمیل دستور Git LFS هنگام فشردن کلید تب پس از نام برنامهٔ git-lfs پشتیبانی می‌کند. برای نمونه، git-lfs [Tab] دستورهای در دسترس Git LFS مانند fetch، migrate و pull را فهرست می‌کند، و git-lfs pull --[Tab] فلگ‌های ممکن برای دستور git-lfs-pull(1) را فهرست خواهد کرد.

با این حال، بیشتر کاربران به استفاده از Git LFS به عنوان برنامه‌ای که توسط گیت فراخوانی می‌شود عادت دارند، مانند git lfs checkout یا git lfs pull. برای فعال‌سازی تکمیل کلید تب برای دستورهای Git LFS در این حالت، تکمیل کلید تب برای دستورهای معمولی گیت نیز باید فعال باشد. با فرض برقراری این شرط، اسکریپت‌های تولیدشده توسط دستور git lfs completion باید از تکمیل دستورهای Git LFS در صورت وارد شدن نویسهٔ تب پس از git lfs پشتیبانی کنند؛ مانند git lfs [Tab] برای فهرست کردن تمامی دستورهای موجود Git LFS یا git lfs pull --[Tab] برای فهرست کردن فلگ‌های ممکن آن دستور. برای جزئیات مربوط به تکمیل کلید تب گیت در شل‌های پشتیبانی‌شده، بخش «شل‌ها (SHELLS)» را ببینید.

همان‌طور که در تکمیل خودکار کلید تب در شل مرسوم است، پیش از آن‌که نویسهٔ تب باعث اجرای اسکریپت تکمیل Git LFS شود، باید پس از نام دستورهای git-lfs یا git lfs یک فاصله وارد گردد. بدون نویسهٔ فاصله، هر سازوکار فعال تکمیل تب در شل در عوض برنامه‌هایی را جستجو می‌کند که نام آن‌ها دارای پیشوند مطابقی باشد.

اسکریپت‌های تکمیل از دستورهای «پنهان» Git LFS برای درخواست نتایج تکمیل از کلاینت Git LFS استفاده می‌کنند، به‌ویژه دستورهای git lfs __complete و git lfs __completeNoDesc. این دستورها ممکن است در آینده حذف شوند یا عملکرد آن‌ها بدون اطلاع قبلی تغییر کند، بنابراین کاربران نباید آن‌ها را مستقیماً فراخوانی کنند یا آن‌ها را بخشی از رابط خط فرمان رسماً مستندشدهٔ Git LFS در نظر بگیرند.

دستور git lfs completion از سه شل یونیکس پشتیبانی می‌کند: GNU Bash (مخفف Bourne Again SHell)، fish و Zsh (یا Z shell). تکمیل کلید تب در هر یک از آن‌ها به شکل متفاوتی پیکربندی می‌شود، هم به‌طور کلی و هم به‌طور خاص برای گیت و در نتیجه برای Git LFS.

در ویندوز، کاربرانی که Git LFS را به عنوان بخشی از پروژهٔ Git for Windows نصب کرده‌اند، به یک شبیه‌ساز شل Bash که همراه با Git for Windows عرضه می‌شود دسترسی دارند.

•Bash:

اگرچه Bash به‌طور پیش‌فرض تکمیل کلید تب را برای گیت ارائه نمی‌دهد، یک اسکریپت تکمیل از سوی پروژهٔ گیت در دسترس است، همان‌طور که در مستندات شرح داده شده است:

https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Bash

اسکریپت بازگردانده‌شده توسط دستور git lfs completion bash باید با این اسکریپت تکمیل گیت سازگار باشد و امکان تکمیل کلید تب دستورهای Git LFS واردشده با هر یک از قالب‌های دستوری git lfs یا git-lfs را فراهم آورد.

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

$ source git-completion.bash

برای بارگیری اسکریپت در تمام نشست‌های آینده، این دستور را به فایل‌های راه‌اندازی شل Bash خود اضافه کنید، یا فایل را در یکی از مکان‌هایی که توسط ابزارهای کمکی بستهٔ bash-completion جستجو می‌شود قرار دهید.

پروژهٔ bash-completion که از خود شل GNU Bash مجزاست، شامل تعداد زیادی اسکریپت تکمیل دستور و ابزارهای کمکی برای بارگیری خودکار آن‌ها هنگام شروع نشست جدید است:

https://github.com/scop/bash-completion

اسکریپت تکمیل Git LFS برای Bash به چند تابع ارائه‌شده توسط بستهٔ bash-completion وابسته است، و بنابراین آن بسته باید نصب شده باشد تا بتوان از تکمیل کلید تب با دستورهای Git LFS استفاده کرد. (با این حال، وجود آن برای اسکریپت تکمیل گیت در Bash الزامی نیست.)

با فرض نصب بودن بستهٔ bash-completion، برای بارگیری اسکریپت تکمیل گیت در تمام نشست‌های آینده که توسط کاربر فعلی آغاز می‌شوند (و نه همهٔ کاربران)، اسکریپت git-completion.bash را در دایرکتوری bash-completion/completions درون مکانی که با متغیر محیطی XDG_DATA_HOME تعریف شده است، یا اگر این متغیر تعریف نشده باشد، در دایرکتوری ~/.local/share قرار دهید. برای نمونه:

$ cp git-completion.bash ~/.local/share/bash-completion/completions/git

برای این‌که ابزارهای کمکی bash-completion اسکریپت تکمیل گیت را برای همهٔ کاربران بارگیری کنند، اسکریپت تکمیل گیت را در دایرکتوری سیستمی مناسب قرار دهید. در لینوکس این مسیر ممکن است /usr/share/bash-completion/completions باشد، و در macOS هنگامی که bash-completion با استفاده از Homebrew نصب شده باشد، ممکن است دایرکتوری share/bash-completion/completions درون مکانی باشد که با دستور brew --prefix بازگردانده می‌شود. با این حال، این مکان‌ها بسته به نحوهٔ نصب بستهٔ bash-completion متفاوت خواهد بود.

•fish:

شل fish پیاده‌سازی اختصاصی خود را از تکمیل کلید تب دستورهای گیت ارائه می‌دهد که در یک فایل git.fish تعریف شده و احتمالاً به‌طور پیش‌فرض در فهرست مکان‌هایی که شل برای اسکریپت‌های تکمیل جستجو می‌کند وجود دارد.

اسکریپت بازگردانده‌شده توسط دستور git lfs completion fish باید با این پیاده‌سازی سازگار باشد و امکان تکمیل کلید تب دستورهای Git LFS واردشده با هر یک از قالب‌های دستوری git lfs یا git-lfs را فراهم آورد.

•Zsh:

برای فعال‌سازی تکمیل کلید تب در Zsh برای هر دستوری، تابع compinit باید ابتدا با دستوری شبیه به زیر بارگیری شود:

% autoload -Uz compinit && compinit

این کار می‌تواند به‌طور جداگانه برای هر نشست انجام شود، یا به یک فایل راه‌اندازی مانند ~/.zshrc یا /etc/zshrc اضافه شود تا برای همهٔ نشست‌های آینده اعمال گردد، چه برای کاربر فعلی یا برای همهٔ کاربران.

شل Zsh توابع تکمیل را از مکان‌های مشخص‌شده در متغیر محیطی FPATH می‌خواند، به‌طوری که مسیرهای فهرست‌شده در ابتدا اولویت دارند. این فهرست همچنین به عنوان یک آرایه در متغیر fpath در دسترس است؛ شل به‌طور خودکار FPATH و fpath را همگام‌سازی می‌کند.

شل Z پیاده‌سازی اختصاصی خود را از تکمیل کلید تب دستورهای گیت ارائه می‌دهد که در یک فایل _git تعریف شده و احتمالاً در یکی از مکان‌های مشخص‌شده در fpath حضور دارد.

اسکریپت بازگردانده‌شده توسط دستور git lfs completion zsh باید با این پیاده‌سازی سازگار باشد و امکان تکمیل کلید تب دستورهای Git LFS واردشده با هر یک از قالب‌های دستوری git lfs یا git-lfs را فراهم آورد.

پروژهٔ گیت همچنین اسکریپت‌های تکمیلی را برای Zsh در قالب همان اسکریپت git-completion.bash مورد استفاده برای شل Bash، به همراه یک اسکریپت git-completion.zsh ارائه می‌دهد که قرار است نام آن به _git تغییر داده شده و در یکی از مکان‌های فهرست‌شده در fpath قرار داده شود. این اسکریپت‌ها با اسکریپت بازگردانده‌شده توسط دستور git lfs completion zsh سازگار نیستند، و در صورت استفاده در کنار آن اسکریپت، تکمیل کلید تب دستورهای Git LFS هنگامی که با قالب دستوری git lfs شروع شود به‌درستی کار نخواهد کرد.

در macOS، چنانچه گیت با استفاده از Homebrew نصب شده باشد، اسکریپت‌های تکمیل Zsh متعلق به پروژهٔ گیت ممکن است در مکانی نصب شوند که نسبت به پیاده‌سازی ارائه‌شده توسط Zsh اولویت پیدا کنند. در این حالت، برای استفادهٔ کامل از اسکریپت بازگردانده‌شده توسط git lfs completion zsh، فایل اسکریپت تکمیل _git که توسط Homebrew برای گیت نصب شده است باید جابه‌جا یا حذف شود تا در ترتیب مسیرهای مشخص‌شده توسط fpath جلوتر از اسکریپت تکمیل گیت خودِ شل Z قرار نگیرد.

برای بارگیری تکمیل دستورهای Git LFS صرفاً برای نشست فعلی شل، اسکریپت تولیدشده توسط git lfs completion را مستقیماً اجرا کنید.

•Bash: 
$ source <(git lfs completion bash)

توجه داشته باشید که در Bash 3.2، دستور داخلی source خروجی جایگزینی فرآیند (process substitution) را به‌درستی اجرا نمی‌کند، بنابراین لازم است در عوض از یک فایل موقت استفاده شود:

$ git lfs completion bash >git-lfs-completion.bash
$ source git-lfs-completion.bash
•fish: 
> git lfs completion fish | source
•zsh:

توجه داشته باشید که همان‌طور که در بخش «شل‌ها (SHELLS)» توضیح داده شد، تابع compinit نیز باید برای فعال‌سازی تکمیل کلید تب اجرا شود.

% source <(git lfs completion zsh)

برای بارگیری تکمیل‌های دستور Git LFS در تمامی نشست‌های آیندهٔ شل، اسکریپت تولیدشده توسط git lfs completion را در مکانی ذخیره کنید که هنگام راه‌اندازی نشست توسط شل شما خوانده شود.

•Bash:

همان‌طور که در بخش «شل‌ها (SHELLS)» اشاره شد، بستهٔ bash-completion برای اسکریپت‌های تکمیل Git LFS در Bash الزامی است، و همچنین ابزارهای کمکی مناسبی فراهم می‌کند که اسکریپت‌های تکمیل را در مجموعه‌ای از مکان‌های تعریف‌شده جستجو کرده و در زمان راه‌اندازی نشست اجرا می‌کنند.

برای بارگیری اسکریپت تکمیل Git LFS در تمام نشست‌های آینده که توسط کاربر فعلی آغاز می‌شوند (اما نه سایر کاربران)، اسکریپت را در دایرکتوری bash-completion/completions درون مکانی که با متغیر محیطی XDG_DATA_HOME تعریف شده است، یا در صورت تعریف نشدن این متغیر، در دایرکتوری ~/.local/share ذخیره کنید. برای نمونه:

$ mkdir -p ~/.local/share/bash-completion/completions
$ git lfs completion bash >~/.local/share/bash-completion/completions/git-lfs

برای بارگیری اسکریپت تکمیل در نشست‌های آیندهٔ همهٔ کاربران، اسکریپت را در دایرکتوری سیستمی مناسب ذخیره کنید، که در لینوکس ممکن است /usr/share/bash-completion/completions باشد، یا در macOS در صورتی که bash-completion با استفاده از Homebrew نصب شده باشد، ممکن است دایرکتوری share/bash-completion/completions درون مکانی باشد که با دستور brew --prefix بازگردانده می‌شود. با این حال، این مکان‌ها بسته به نحوهٔ نصب و پیکربندی بستهٔ bash-completion متفاوت خواهد بود. برای جزئیات، مستندات مربوط به بستهٔ bash-completion سیستم خود را بررسی کنید.

•fish:

شل fish مکان‌های متعددی را برای اسکریپت‌های تکمیل جستجو می‌کند، همان‌گونه که در مستندات شرح داده شده است:

https://fishshell.com/docs/current/completions.html#where-to-put-completions

برای بارگیری اسکریپت تکمیل Git LFS در تمامی نشست‌های آغازشده توسط کاربر فعلی (اما نه سایر کاربران)، اسکریپت را در دایرکتوری fish/completions درون مکانی که با متغیر محیطی XDG_CONFIG_HOME تعریف شده است، یا در صورت تعریف نشدن آن متغیر، در دایرکتوری ~/.config ذخیره کنید. برای نمونه:

> mkdir -p ~/.config/fish/completions
> git lfs completion fish >~/.config/fish/completions/git-lfs.fish

برای بارگیری اسکریپت تکمیل در نشست‌های آیندهٔ همهٔ کاربران، اسکریپت را در یکی دیگر از مکان‌هایی که شل جستجو می‌کند، مانند زیرشاخهٔ fish/completions درون دایرکتوری پیکربندی سیستمی شل ذخیره کنید. در لینوکس این مسیر معمولاً /etc/fish/completions است. در macOS هنگامی که شل fish با استفاده از Homebrew نصب شده باشد، این مسیر معمولاً دایرکتوری etc/fish/completions درون مکانی است که با دستور brew --prefix بازگردانده می‌شود.

•zsh:

توجه داشته باشید که همان‌طور که در بخش «شل‌ها (SHELLS)» توضیح داده شد، تابع compinit نیز باید برای فعال‌سازی تکمیل کلید تب اجرا شود.

برای بارگیری اسکریپت تکمیل Git LFS در همهٔ نشست‌ها، اسکریپت را به عنوان فایلی با نام _git-lfs در یکی از مکان‌های فهرست‌شده در متغیر fpath ذخیره کنید. مکان خاص انتخاب‌شده، بسته به نحوهٔ ساخته شدن مجموعه مسیرها در آرایهٔ fpath، ممکن است بر این‌که اسکریپت تکمیل فقط برای نشست‌های آغازشده توسط کاربر جاری یا برای نشست‌های همهٔ کاربران بارگیری شود، تأثیر بگذارد.

دستور زیر اسکریپت را در نخستین مکان تعریف‌شده در fpath ذخیره می‌کند:

% git lfs completion zsh >"${fpath[1]}/_git-lfs"

همچنین ممکن است ترجیح دهید فایل را در مکان دیگری که در fpath تعریف شده است ذخیره کنید، برای نمونه در آخرین مکان، که در این حالت باید در عوض از ${fpath[-1]} استفاده شود.

همچنین این امکان وجود دارد که یک مکان سفارشی به فهرست fpath افزوده شده و اسکریپت تکمیل Git LFS در آن‌جا ذخیره شود. برای انجام این کار، دستوراتی را که متغیر fpath را به‌روز می‌کنند به یک فایل راه‌اندازی مانند ~/.zshrc یا /etc/zshrc بیفزایید تا برای تمامی نشست‌های آینده اعمال شوند، چه برای کاربر فعلی یا برای همهٔ کاربران.

بخشی از مجموعهٔ git-lfs(1).