همکاری از طریق ترمینال

همه‌ی کارهایی که معمولاً در یک رابط وب انجام می‌دهید، یعنی ساختن مخزن، باز کردن issue، بررسی و ادغام pull request و فورک کردن، مستقیماً از خط فرمان zev انجام می‌شود. یک بار وارد می‌شوید و از آن به بعد هیچ دستور سروری به آدرس یا توکن نیاز ندارد. ## یک بار وارد شوید ```bash zev init zev login zaryn.xyz --register alice --email alice@example.com ``` `zev login` یک چالش یک‌باره را با هویت این مخزن (`.zev/identity`) امضا می‌کند، آن را با یک توکن دسترسی شخصی مبادله می‌کند و آدرس سرور و توکن را در `~/.config/zev/credentials` ذخیره می‌کند؛ فایلی که فقط خودتان می‌توانید بخوانید. بار اول، `--register <username> --email <address>` پس از تأیید کدی که ایمیل می‌شود برای این هویت حساب می‌سازد؛ پس از آن `zev login <url>` کافی است. سرور را می‌توان با نشانی وب‌سایتش (`zaryn.xyz`، `example.com`)، به شکل `http://host:port`، یک `host:port` ساده، یا هر نشانی مخزنی روی آن نوشت؛ فقط بخش سرور استفاده می‌شود. ```bash zev whoami zev logout ``` `zev whoami` سرور ذخیره‌شده، کاربر و توکن را به‌صورت پوشیده نشان می‌دهد. `zev logout` اعتبارنامه‌ی ذخیره‌شده را از این دستگاه پاک می‌کند؛ خود توکن تا زمانی که روی سرور باطل نشود معتبر می‌ماند. ### اعتبارنامه‌ها از کجا می‌آیند هر دستور سروری اعتبارنامه‌ها را به این ترتیب پیدا می‌کند: 1. پرچم‌های `--server` و `--token` 2. متغیرهای محیطی `ZEV_SERVER` و `ZEV_TOKEN` 3. ورود ذخیره‌شده با `zev login` بنابراین پرچم‌ها همیشه اولویت دارند، متغیرهای محیطی برای CI و خودکارسازی مناسب‌اند و ورود ذخیره‌شده برای کار روزمره. ## ساختن یک مخزن متصل ```bash zev new ``` یک راهنمای تعاملی نام مخزن، نوع آن (code، model، dataset، agent، topology)، زبان اصلی، سطح دسترسی و مجوز را می‌پرسد. سپس مخزن را روی سرور می‌سازد، یک `.zevignore` متناسب با زبان می‌نویسد و پروژه‌ی محلی را به‌عنوان ریموت `origin` متصل می‌کند. ## چرخه‌ی روزمره ```bash zev add . zev commit "Describe the change" zev push ``` `zev push` بدون آرگومان شاخه‌ی فعلی را به `origin` push می‌کند و `zev pull` شاخه‌ی فعلی را از `origin` pull می‌کند. هر دو در صورت نیاز نام یا آدرس ریموت و نام شاخه را هم می‌پذیرند: ```bash zev push upstream feature-x zev pull alice/project main ``` `zev add .` کل درخت پوشه را به‌صورت بازگشتی مرحله‌بندی می‌کند و از `.zev/` و هر چیزی که با `.zevignore` مطابقت دارد صرف‌نظر می‌کند. ## Issueها ```bash zev issue --title "Login button misaligned" --desc "Overflows on narrow screens" zev issue list zev issue list --all zev issue view 1 zev issue comment 1 --body "Reproduced on a 360px viewport." zev issue close 1 ``` `zev issue` بدون زیردستور یک issue می‌سازد و هر چیزی را که به‌صورت پرچم نداده باشید می‌پرسد. `list` issueهای باز را نشان می‌دهد و `--all` بسته‌شده‌ها را هم شامل می‌شود. `view` توضیحات و کل رشته‌ی نظرها را نشان می‌دهد. `comment` اگر `--body` داده نشود متن را می‌پرسد. `close` پیش از بستن تأیید می‌گیرد، چون هنوز نمی‌توان issueها را از خط فرمان دوباره باز کرد. شماره‌ی issue را می‌توان به شکل `3` یا `#3` نوشت. ## Pull requestها ```bash zev branch fix-login-button zev checkout fix-login-button zev add . zev commit "Fix login button overflow" zev push zev pr ``` `zev pr` شاخه‌ی مبدأ را از checkout فعلی تشخیص می‌دهد و شاخه‌ی مقصد را می‌پرسد (پیش‌فرض `main`). عنوان را از آخرین پیام commit پیش‌نویس می‌کند و اگر شاخه بیش از یک commit داشته باشد، توضیحات را به‌صورت فهرستی از همه‌ی commitهای شاخه‌ی شما که مقصد هنوز ندارد می‌نویسد. برای پذیرفتن هر پیش‌نویس Enter بزنید یا متن خودتان را بنویسید. `zev pr --yes` همه‌ی پیش‌نویس‌ها را بدون پرسش می‌پذیرد. ```bash zev pr list zev pr list --all zev pr view 1 zev pr merge 1 ``` `merge` بررسی می‌کند که pull request هنوز باز باشد، تأیید می‌گیرد و سپس آن را روی سرور ادغام می‌کند. پس از آن نسخه‌ی محلی‌تان را به‌روز کنید: ```bash zev checkout main zev pull ``` ### در وب‌سایت در مخزن، **درخواست‌های ادغام ← درخواست ادغام تازه** را باز کنید. شاخه‌ی تغییرات خود و شاخه‌ی مقصد را انتخاب کنید: صفحه کامیت‌ها و فایل‌هایی را که شاخه‌ی شما تغییر داده نشان می‌دهد، و اینکه آیا مقصد از آن زمان جلو رفته یا نه. عنوان و توضیح بنویسید (یک قالب آماده است)، مسئله‌هایی را که می‌بندد علامت بزنید (با ادغام بسته می‌شوند)، برچسب بگذارید، از مالک یا همکاران بازبینی بخواهید، و آن را آماده یا به‌صورت پیش‌نویس باز کنید. بازبین‌ها تأیید می‌کنند، تغییر می‌خواهند یا نظر می‌دهند. درخواست ادغام وقتی ادغام می‌شود که پیش‌نویس نباشد، درخواست تغییرِ بی‌پاسخی نداشته باشد، و شاخه‌اش همه‌ی کامیت‌های مقصد را داشته باشد؛ پس ادغام هرگز کار کسی را از بین نمی‌برد. ### وقتی شاخه‌ی مقصد جلو رفته است اگر کسی پس از ساختن شاخه‌ی شما چیزی در `main` ادغام کرده، کامیت‌هایش را به شاخه‌ی خود بیاورید و آن را push کنید: ```bash zev pull origin main zev checkout fix-login-button zev merge main zev push ``` `zev merge main` کامیت‌های شما را روی `main` بازپخش می‌کند و هر فایل را خط به خط ترکیب می‌کند. اگر هر دو طرف همان خطوط را تغییر داده باشند، چیزی را تغییر نمی‌دهد و نام فایل‌ها را می‌گوید؛ آن‌گاه `zev merge main --resolve` را اجرا کنید: شاخه‌ی شما روی `main` قرار می‌گیرد و آن فایل‌ها هر دو نسخه را میان نشانه‌های `<<<<<<<` و `>>>>>>>` دارند. آنچه می‌خواهید را نگه دارید، نشانه‌ها را پاک کنید و `zev merge --continue` را اجرا کنید (یا `zev merge --abort` برای بازگشت). ## کار با مخزن‌های دیگر ```bash zev fork-repo alice/project --clone zev clone alice/project project --branch main ``` `zev fork-repo` یک مخزن را با همه‌ی شاخه‌هایش در حساب شما کپی می‌کند؛ `--as <name>` نام دیگری به فورک می‌دهد و `--clone` آن را به‌صورت محلی هم کلون می‌کند. `zev clone` یک مخزن را در پوشه‌ای جدید کلون می‌کند. در هر دو حالت کلون بلافاصله آماده‌ی استفاده است: فایل‌ها checkout شده‌اند و `origin` تنظیم شده، پس `zev pull` و `zev push` بدون آرگومان کار می‌کنند. `list`، `view`، `comment`، `close` و `merge` گزینه‌ی `--repo owner/name` را می‌پذیرند، بنابراین می‌توانید از هر پوشه‌ای، حتی بیرون از هر مخزنی، روی هر مخزنی کار کنید. ## فایل‌های کاری شما امن هستند zev هرگز کار commit‌نشده را بی‌صدا بازنویسی نمی‌کند. - `zev pull` روی شاخه‌ی فعلی فایل‌ها را خودکار به‌روز می‌کند، اما فقط وقتی امن باشد. اگر تغییرات مرحله‌بندی‌شده، فایل‌های ردیابی‌شده‌ی تغییریافته یا حذف‌شده، یا فایل ردیابی‌نشده‌ای دارید که به‌روزرسانی آن را بازنویسی می‌کند، هیچ چیزی تغییر نمی‌کند، فایل مسئول نام برده می‌شود و گفته می‌شود چه کنید. خود شاخه همچنان به‌روز می‌شود، پس چیزی از دست نمی‌رود. - `zev pull` برای شاخه‌ای که روی آن نیستید هرگز به فایل‌های کاری دست نمی‌زند. - `zev checkout` در همین شرایط از تعویض شاخه خودداری می‌کند و در این حالت هیچ چیزی را تغییر نمی‌دهد. `zev checkout --force <branch>` با این حال شاخه را عوض می‌کند و تغییرات محلی شما را دور می‌ریزد. - هنگام تعویض شاخه یا pull، فایل‌هایی که فقط در نسخه‌ی قبلی وجود دارند حذف می‌شوند تا درخت کاری همیشه با شاخه‌ای که روی آن هستید یکی باشد. `zev status` شاخه‌ی فعلی را نشان می‌دهد و فایل‌های مرحله‌بندی‌شده، تغییریافته، حذف‌شده و ردیابی‌نشده را، از جمله داخل زیرپوشه‌ها، فهرست می‌کند.