راهنمای کامل گرَب (grb)

۱ — گرَب دقیقاً چه کار می‌کند؟

• با دستورهایی مثل commit و pull همان نقش یک کلاینت سادهٔ «نسخه و فایل» را برای مخزن شما روی Gitrabbit بازی می‌کند.
• فایل‌های متنی را در پروژه اسکن می‌کند؛ باینری‌ها و مسیرهای بزرگ در تنظیمات پیش‌فرض یا طبق .grbignore کنار گذاشته می‌شوند.
• اولین بار معمولاً کل درخت ضبط می‌شود؛ بارهای بعد هم‌زمان با سرور تنها«دلتا» ذخیره می‌شود و در شبکهٔ شما هم اندازهٔ ارسالی کوچک‌تر خواهد بود.

۲ — پیش‌نیاز قبل از هر دستوری

1. نصب Node.js؛ لانچِر گرَب آخرین نسخهٔ اسکریپت JS را با node - از stdin اجرا می‌کند؛ بدون Node خطای در اجرای اسکریپت CLI ظاهر می‌شود (مثل «گرَب نشد بیاید بیرون از اینترنت»).
2. حتماً مسیر نصب در PATH باشد: مک/لینوکس ~/.local/bin — ویندوز %USERPROFILE%\.grb\bin. در غیر این صورت دستور grb یافت نمی‌شود.
3. دسترسی به اینترنت برای سرور با آدرس https://gitrabbit.ir و APIهای HTTPS.

۳ — نصب لانچِر گرَب (یک‌بار روی هر ماشین)

لانچِر یک فایل shell کوچک است که CLI اصلی را از سرور می‌گیرد و هر بار با نسخهٔ تازه اجرا می‌کند. به‌همین دلیل اسم فایلی روی سیستم شما مانند irangit-cli.js در ریشهٔ پروژه لازم نیست.

مک یا لینوکس

اسکریپت رسمی ابتدا در فایل موقت دانلود و بعد اجرا می‌شود؛ اگر هر مرحله شکست بخورد دستور قطع می‌شود.

# macOS / Linux — one-time install (PATH persisted permanently)
curl -fsSL "https://gitrabbit.ir/install-grb.sh?v=1.1.3" | sed 's/\r$//' | sh

ویندوز — PowerShell (پیشنهادی)

نصب در %USERPROFILE%\.grb\bin و افزودن به PATH کاربر. از certutil استفاده نکنید — توسط آنتی‌ویروس مسدود می‌شود.

# Windows — PowerShell (TLS 1.2, recommended):
$ProgressPreference = 'SilentlyContinue'
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$url = "https://gitrabbit.ir/install-grb.ps1?v=1.1.3"
$file = Join-Path $env:TEMP "install-grb.ps1"
Invoke-WebRequest -UseBasicParsing -Uri $url -OutFile $file
& $file

ویندوز (CMD)

CDN آروان گاهی SSL renegotiation انجام می‌دهد؛ Windows 10 ممکن است خطای SEC_E_ILLEGAL_MESSAGE بدهد — در این حالت از مرورگر یا Git for Windows (curl با OpenSSL) استفاده کنید.

# Windows — CMD (curl.exe + PowerShell; no certutil)
curl.exe -fsSL "https://gitrabbit.ir/install-grb.ps1?v=1.1.3" -o "%TEMP%\install-grb.ps1" && powershell -NoProfile -ExecutionPolicy Bypass -File "%TEMP%\install-grb.ps1"

ویندوز — دانلود با مرورگر (همیشه کار می‌کند)

اگر curl یا PowerShell خطای SSL داد: در Chrome/Edge فایل را Save As کنید، سپس اجرا کنید:

# 1. Save in Chrome/Edge:
https://gitrabbit.ir/install-grb.ps1?v=1.1.3

# 2. Run:
powershell -NoProfile -ExecutionPolicy Bypass -File "%TEMP%\install-grb.ps1"

بررسی نصب

grb --version

بعد از نصب

ویندوز: یک ترمینال جدید باز کنید؛ سپس grb --version. مک/لینوکس: اگر grb پیدا نشد، در همین ترمینال . ~/.bashrc یا . ~/.zshrc را اجرا کنید.

۴ — متصل کردن همین پوشهٔ فعلی به مخزن: grb init

هر پروژهٔ روی دستگاه تنظیم خودش را داخل پوشهٔ مخفی .irangit/config.json نگه می‌دارد (محتوی اش آدرس نمونهٔ زیر نیست واقعی شما؛ توکن فقط مخزنی که در داشبورد ساخته‌اید). دربارهٔ ساخت این فایل و قرار گرفتنش در Gitالزاماً روی صفحهٔ فایل‌ها توضیح داده شده است.

grb init \
  --url https://gitrabbit.ir \
  --repo <repo_id_from_dashboard> \
  --token <token_created_for_this_repo> \
  --branch main

جایگاه فعلیٔ ترمینال باید ریشهٔ همان مخزنی باشد که می‌خواهید آپلود کنید؛ grb هر چیزی از این مسیر با قواعد خودش جمع می‌کند و به سرور می‌فرستد. آرگومان --branch شاخهٔ پیش‌فرض محلی را در پیکربندی می‌نویسد؛ اگر حذفش کنید همان main فرض می‌شود.

۵ — شاخه‌ها (Branches)

شاخهٔ پیش‌فرض سرور معمولاً main است؛ کامیت‌های قدیمی بدون برچسب شاخه پس از به‌روزرسانی سرور همگی در همین تایم‌لاین دیده می‌شوند. برای کار روی یک شاخهٔ جدید، ابتدا باید آن را روی سرور ثبت کنید، سپس نامش را در config.json و در نتیجه در همهٔ درخواست‌های گرَب منعکس کنید.

# Register the branch on the server (before committing to a name other than main)
grb branch create feat-sso --from main

# Then set the "branch" key in .irangit/config.json to the branch name and run pull.
# Every pull/commit/push targets that branch via the X-GRB-Branch header.

grb pull
grb commit -m "your commit message"
grb push

اگر محتوای .irangit/sync.json برای شاخهٔ دیگری بوده گرَب هشدار هم‌خوان نبودن با config نشان می‌دهد؛ در آن حالت یا شاخه را در config هماهنگ کنید یا sync را بعد از هماهنگی دوباره با جفت pull بسازید.

جزئیات کامل مدل داده، API و وب: مستندات شاخه‌ها.

۶ — کار روزمره: همگام شدن با سرور، کامیت و انتشار

pull آخرین وضعیتی را که هم‌کاران قبلاً منتشر کرده‌اند می‌آورد و فایل .irangit/sync.json را آمادهٔ مقایسهٔ بعدی نگه می‌دارد؛ commit بستهٔ دلتا یا کل اسکن را آمادهٔ ارسال می‌کند؛ push همان‌ها را رسماً منتشر می‌کند.

# Uses the branch set in .irangit/config.json (default: main)
grb pull
grb commit -m "your commit message"
grb push

# When SemVer is enabled on the repo:
# Option 1 — pass bump type as a flag:
grb commit -m "fix bug" --semver patch
grb commit -m "add feature" --semver minor
grb commit -m "breaking change" --semver major

# Option 2 — omit --semver flag; grb will prompt interactively:
#   SemVer enabled for this repo. Current version: 1.2.3
#   Select bump type:
#     1) patch   bug fixes, small improvements
#     2) minor   new features, no breaking changes
#     3) major   breaking changes
#   Enter 1/2/3 or patch/minor/major:

جزئیات SemVer (bump، rollback، API): مستندات SemVer.

۷ — دستورهای دیگر (آرشیو زیپ، تاریخچه، به‌روزرسانی خود ابزار)

# Show commit history (command is named "log" in the CLI)
grb log

# Pull the latest published state from the server into this folder
grb pull

# Download the full published tree as a ZIP archive
grb download
# or with an explicit output path:
grb download -o ./backup.zip

آرگومان -o ./path.zip را هرگز برابر - نذارید چون اسم فایل عجیبی در پوشه می‌سازد.

# All three commands update the grb launcher binary on disk:
grb self-update     # recommended
grb update-self     # alias
grb update          # also works (equivalent to self-update when using the launcher)

# The CLI JavaScript (irangit-cli.js) is ALWAYS fetched fresh from the server on
# every grb run, so it is always up to date automatically.
# Running self-update / update only needs to be done when the launcher binary
# itself (grb / grb.ps1 / grb.cmd) has been updated on the server.

۸ — متغیرهای محیطی پیشرفته

# Example reset when a URL is incorrectly cached or you are switching server:

# Unix terminal (bash / zsh) — before running grb:
export GRB_BASE_URL="https://gitrabbit.ir"
unset GRB_CLI_BASE_URL GRB_CLI_URL GRB_CLI_VERSION

# Windows CMD — clear variables:
set GRB_BASE_URL=
set GRB_CLI_BASE_URL=
set GRB_CLI_URL=
set GRB_CLI_VERSION=

۹ — توکن مخزن و Git

توکن داخل تنظیمات محلی ست می‌شود؛ اگر مخزنتان را عمومی کنید هرگز کل پوشهٔ .irangit/ یا شاخهٔ خصوصی دیگری نیاز دارد؛ قفل پیشنهادی همچنان خط .irangit/ در .gitignore هم‌پروژه است. در هر صورت به‌ اشتراک‌گذاشتن snapshot زندهٔ گرَب در چت عمومی مانند آپلود دستی رمزعبور حساب‌هاست.