.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "GIST" "1" "July 2026" "" "راهنمای Gist"
.SH "نام (NAME)"
gist \- بارگذاری و مدیریت Gistهای گیت‌هاب از خط فرمان
.SH "خلاصه دستور (SYNOPSIS)"
جم \fBgist\fR دستوری با نام \fBgist\fR در اختیارتان می‌گذارد که با آن می‌توانید از خط فرمان خود، محتوا را در https://gist\.github\.com بارگذاری کنید.
.SH "نصب (INSTALLATION)"
.IP "\(bu" 4
اگر روبی (Ruby) را نصب دارید:
.IP
gem install gist
.IP "\(bu" 4
اگر از Bundler استفاده می‌کنید:
.IP
source :rubygems gem 'gist'
.IP "\(bu" 4
در سیستم‌عامل OS X، ابزار gist در Homebrew موجود است:
.IP
brew install gist
.IP "\(bu" 4
در سیستم‌عامل FreeBSD، ابزار gist در مخزن ports موجود است:
.IP
pkg install gist
.IP "\(bu" 4
برای اوبونتو و دبیان:
.IP
apt install gist
.IP "" 0
.P
نکته: دبیان برای جلوگیری از تداخل نام، نام فایل اجرایی را به \fBgist\-paste\fR تغییر داده است.
.SH "دستورات و کاربرد (COMMAND)"
.IP "\(bu" 4
برای بارگذاری محتوای فایل \fBa\.rb\fR کافی است اجرا کنید:
.IP
gist a\.rb
.IP "\(bu" 4
بارگذاری چند فایل:
.IP
gist a b c gist *\.rb
.IP "\(bu" 4
به‌طور پیش‌فرض محتوا از ورودی استاندارد (STDIN) خوانده می‌شود و می‌توانید با گزینه \fB\-f\fR نام فایلی برای آن تعیین کنید:
.IP
gist \-f test\.rb <a\.rb
.IP "\(bu" 4
همچنین می‌توانید مستقیماً محتوای کلیپ‌بورد (Clipboard) را الصاق و بارگذاری کنید:
.IP
gist \-P
.IP "\(bu" 4
استفاده از \fB\-p\fR برای خصوصی کردن Gist:
.IP
gist \-p a\.rb
.IP "\(bu" 4
استفاده از \fB\-d\fR برای افزودن توضیحات:
.IP
gist \-d "Random rbx bug" a\.rb
.IP "\(bu" 4
می‌توانید Gistهای موجود را با گزینه \fB\-u\fR به‌روزرسانی کنید:
.IP
gist \-u GIST_ID FILE_NAME gist \-u 42f2c239d2eb57299408 test\.txt
.IP "\(bu" 4
اگر می‌خواهید نشانی اینترنتی (URL) حاصل در کلیپ‌بورد کپی شود، از \fB\-c\fR استفاده کنید:
.IP
gist \-c <a\.rb
.IP "\(bu" 4
اگر می‌خواهید نشانی جاسازی‌شدنی (Embeddable) در کلیپ‌بورد کپی شود، از \fB\-e\fR استفاده کنید:
.IP
gist \-e <a\.rb
.IP "\(bu" 4
برای باز کردن مستقیم نشانی در پنجره مرورگر، از \fB\-o\fR استفاده کنید:
.IP
gist \-o <a\.rb
.IP "\(bu" 4
برای فهرست کردن Gistهای یک کاربر (Gistهای عمومی یا تمام Gistهای کاربر احرازهویت‌شده):
.IP
gist \-l : all gists for authed user gist \-l defunkt : list defunkt's public gists
.IP "" 0
.P
برای خواندن یک Gist و چاپ آن در خروجی استاندارد (STDOUT):
.IP "" 4
.nf
gist \-r GIST_ID
gist \-r 374130
.fi
.IP "" 0
.IP "\(bu" 4
برای مشاهده جزئیات بیشتر، خروجی \fBgist \-\-help\fR را ببینید.
.IP "" 0
.SH "ورود به سیستم و احراز هویت (LOGIN)"
پیش از آنکه برای نخستین بار از \fBgist\fR استفاده کنید، باید وارد سیستم شوید. دو روش ورود پشتیبانی می‌شود:
.IP "1." 4
روش احراز هویت OAuth بر اساس کد دستگاه (Device-code flow) گیت‌هاب. این شیوه پیش‌فرض برای ورود به github.com است و می‌توان با ایجاد یک برنامه OAuth و مقداردهی متغیر محیطی \fBGIST_CLIENT_ID\fR با شناسه کلاینت (client id) آن برنامه، این شیوه را برای GitHub Enterprise نیز فعال کرد.
.IP "2." 4
روش تبادل توکن با نام کاربری و گذرواژه (منسوخ‌شده). این شیوه پیش‌فرض برای GitHub Enterprise است و می‌توان با مقداردهی متغیر محیطی \fBGIST_USE_USERNAME_AND_PASSWORD\fR از آن برای ورود به github.com نیز استفاده کرد.
.IP "" 0
.SS "روش کد دستگاه (Device-code flow)"
این روش به شما امکان می‌دهد با ورود به گیت‌هاب در مرورگر و وارد کردن یک کد تایید، توکن دسترسی دریافت کنید. این روش توصیه می‌شود.
.IP "" 4
.nf
gist \-\-login
Requesting login parameters\|\.\|\.\|\.
Please sign in at https://github\.com/login/device
  and enter code: XXXX\-XXXX
Success! https://github\.com/settings/connections/applications/4f7ec0d4eab38e74384e
.fi
.IP "" 0
.P
توکن دسترسی (access_token) دریافت‌شده در مسیر \fB~/\.gist\fR ذخیره شده و برای تمام عملیات‌های بعدی ارسال Gist استفاده می‌شود. در صورت نیاز می‌توانید دسترسی را از نشانی https://github\.com/settings/connections/applications/4f7ec0d4eab38e74384e لغو کنید.
.SS "روش نام کاربری و گذرواژه (Username-password flow)"
این روش نام کاربری، گذرواژه و در صورت وجود، کد تایید دومرحله‌ای (2FA) گیت‌هاب شما را درخواست می‌کند و آن‌ها را با یک توکن دارای مجوز «gist» مبادله می‌کند (نام کاربری و گذرواژه شما ذخیره نمی‌شوند). این سازوکار از سوی گیت‌هاب منسوخ شده است، اما ممکن است همچنان در نسخه‌های GitHub Enterprise کار کند.
.IP "" 4
.nf
gist \-\-login
Obtaining OAuth2 access_token from GitHub\.
GitHub username: ConradIrwin
GitHub password:
2\-factor auth code:
Success! https://github\.com/settings/tokens
.fi
.IP "" 0
.P
این توکن در مسیر \fB~/\.gist\fR ذخیره شده و برای تمام ارسال‌های بعدی استفاده می‌شود. در صورت نیاز می‌توانید آن را از نشانی https://github\.com/settings/tokens لغو کنید یا فایل مذکور را حذف نمایید.
.SS "ورود بدون گذرواژه (Password-less login)"
.P
اگر نیازمندی‌های احراز هویت پیچیده‌تری دارید، می‌توانید با الصاق یک توکن گیت‌هاب دارای محدوده دسترسی (scope) \fBgist\fR (و احتمالاً \fBuser:email\fR برای GitHub Enterprise) درون فایلی به نام \fB~/\.gist\fR، فایل توکن را به‌صورت دستی ایجاد کنید. می‌توانید چنین توکنی را از نشانی https://github\.com/settings/tokens بسازید.
.P
این فایل باید تنها حاوی توکن (حدود ۴۰ نویسه هگزادسیمال) باشد و برای ویرایش آسان‌تر، می‌تواند در انتها یک خط جدید (\fB\en\fR یا \fB\er\en\fR) داشته باشد.
.P
برای مثال، یک روش برای ساخت این فایل اجرای دستور زیر است:
.IP "" 4
.nf
(umask 0077 && echo MY_SECRET_TOKEN > ~/\.gist)
.fi
.IP "" 0
.P
استفاده از \fBumask\fR تضمین می‌کند که این فایل تنها از طریق حساب کاربری خود شما قابل دسترسی است.
.SS "گیت‌هاب سازمانی (GitHub Enterprise)"
اگر می‌خواهید \fBgist\fR از نسخه محلی GitHub Enterprise نصب‌شده شما در \fIhttps://enterprise\.github\.com\fR استفاده کند، باید متغیر محیطی \fBGITHUB_URL\fR را صادر (export) کنید (معمولاً در فایل \fB~/\.bashrc\fR شما انجام می‌شود).
.IP "" 4
.nf
export GITHUB_URL=http://github\.internal\.example\.com/
.fi
.IP "" 0
.P
پس از انجام این کار و راه‌اندازی مجدد ترمینال (یا اجرای \fBsource ~/\.bashrc\fR)، ابزار gist به‌طور خودکار به جای github.com عمومی از GitHub Enterprise استفاده خواهد کرد.
.P
توکن شما برای GitHub Enterprise به جای \fB~/\.gist\fR در مسیری مانند \fB\.gist\.<protocol>\.<server\.name>[\.<port>]\fR (برای مثال \fB~/\.gist\.http\.github\.internal\.example\.com\fR برای متغیر GITHUB_URL بالا) ذخیره خواهد شد.
.P
اگر چندین سرور دارید یا به تناوب از نسخه سازمانی و گیت‌هاب عمومی استفاده می‌کنید، می‌توانید با ساخت اسکریپت‌هایی که متغیر محیطی را تنظیم کرده و سپس \fBgist\fR را اجرا می‌کنند این کار را مدیریت کنید. به یاد داشته باشید که برای استفاده از گیت‌هاب عمومی باید مقدار این متغیر محیطی را پاک کنید. صرفاً تنظیم آن روی نشانی عمومی کار نخواهد کرد؛ از دستور \fBunset GITHUB_URL\fR استفاده کنید.
.SS "قالب فایل توکن (Token file format)"
اگر نمی‌توانید از گذرواژه استفاده کنید (همانند اغلب نسخه‌های Enterprise)، می‌توانید توکن را از طریق رابط وب ایجاد کرده و سپس رشته آن را در فایل مربوطه ذخیره کنید. از قرار دادن شکست‌های خطی اضافه خودداری کنید، در غیر این صورت ممکن است با خطای زیر روبرو شوید:
.IP "" 4
.nf
$ gist \-l
Error: Bad credentials
.fi
.IP "" 0
.TP
همچنین می‌توانید از Gist به‌عنوان یک کتابخانه در داخل کدهای روبی (Ruby) خود استفاده کنید:

.P
اگر به قابلیت‌های پیشرفته‌تری نیاز دارید، می‌توانید این پارامترها را نیز ارسال کنید:
.IP "\(bu" 4
\fB:access_token\fR برای احراز هویت با استفاده از OAuth2 (پیش‌فرض مقدار `File\.read("~/\.gist")) است).
.IP "\(bu" 4
\fB:filename\fR برای تغییر برجسته‌سازی نحوی (Syntax Highlighting) فایل (پیش‌فرض \fBa\.rb\fR است).
.IP "\(bu" 4
\fB:public\fR اگر می‌خواهید Gist شما دارای نشانی قابل حدس زدن (عمومی) باشد.
.IP "\(bu" 4
\fB:description\fR برای افزودن توضیحات به Gist شما.
.IP "\(bu" 4
\fB:update\fR برای به‌روزرسانی یک Gist موجود (می‌تواند یک URL یا یک شناسه باشد).
.IP "\(bu" 4
\fB:copy\fR برای کپی کردن نشانی اینترنتی حاصل در کلیپ‌بورد (پیش‌فرض false است).
.IP "\(bu" 4
\fB:open\fR برای باز کردن نشانی اینترنتی حاصل در یک مرورگر (پیش‌فرض false است).
.IP "" 0
.P
نکته: مقدار access_token باید دارای محدوده دسترسی (scope) \fBgist\fR باشد و همچنین ممکن است به محدوده \fBuser:email\fR نیاز داشته باشد.
.IP "\(bu" 4
اگر می‌خواهید چند فایل را درون یک Gist بارگذاری کنید:
.IP
Gist\.multi_gist("a\.rb" => "Foo\.bar", "a\.py" => "Foo\.bar")
.IP "\(bu" 4
اگر ترجیح می‌دهید از access_token داخلی gist استفاده کنید، می‌توانید با فراخوانی دستور زیر کاربر را وادار به دریافت توکن کنید:
.IP
Gist\.login!
.IP "\(bu" 4
این کار کاربر را از طریق فرآیند دریافت توکن OAuth2 هدایت کرده و آن را در \fB~/\.gist\fR ذخیره می‌کند؛ جایی که بعداً توسط \fBGist\.gist\fR قابل خواندن خواهد بود.
.IP "" 0
.SH "پیکربندی (CONFIGURATION)"
.IP "\(bu" 4
اگر می‌خواهید گزینه‌های \fB\-o\fR یا \fB\-c\fR هنگام اجرای برنامه gist به‌طور پیش‌فرض فعال باشند، یک نام مستعار (alias) به فایل \fB~/\.bashrc\fR (یا معادل آن) اضافه کنید. برای نمونه:
.IP
alias gist='gist \-c'
.IP "\(bu" 4
اگر ترجیح می‌دهید gist مرورگر متفاوتی را باز کند، می‌توانید متغیر محیطی BROWSER را صادر کنید:
.IP
export BROWSER=google\-chrome
.IP "" 0
.P
اگر یکپارچه‌سازی کلیپ‌بورد یا مرورگر در پلتفرم شما به درستی کار نمی‌کند، لطفاً یک گزارش باگ یا ترجیحاً یک Pull Request ارسال کنید.
.P
اگر برای دسترسی به اینترنت نیاز به استفاده از یک پروکسی HTTP دارید، متغیر محیطی \fBHTTP_PROXY\fR یا \fBhttp_proxy\fR را صادر (export) کنید تا gist از آن استفاده کند.
.SH "درباره و نویسندگان (AUTHORS)"
با تشکر از @defunkt و @indirect برای نگارش و نگهداری نسخه‌های ۱ تا ۳. با تشکر از @rking و @ConradIrwin برای نگهداری نسخه ۴.
.P
تحت مجوز MIT منتشر شده است. گزارش اشکالات و دریافت Pull Requestها با استقبال پذیرفته می‌شود.