GIST(1) راهنمای Gist GIST(1)

gist - بارگذاری و مدیریت Gistهای گیت‌هاب از خط فرمان

جم gist دستوری با نام gist در اختیارتان می‌گذارد که با آن می‌توانید از خط فرمان خود، محتوا را در https://gist.github.com بارگذاری کنید.

•
اگر روبی (Ruby) را نصب دارید:
gem install gist
•
اگر از Bundler استفاده می‌کنید:
source :rubygems gem 'gist'
•
در سیستم‌عامل OS X، ابزار gist در Homebrew موجود است:
brew install gist
•
در سیستم‌عامل FreeBSD، ابزار gist در مخزن ports موجود است:
pkg install gist
•
برای اوبونتو و دبیان:
apt install gist

نکته: دبیان برای جلوگیری از تداخل نام، نام فایل اجرایی را به gist-paste تغییر داده است.

•
برای بارگذاری محتوای فایل a.rb کافی است اجرا کنید:
gist a.rb
•
بارگذاری چند فایل:
gist a b c gist *.rb
•
به‌طور پیش‌فرض محتوا از ورودی استاندارد (STDIN) خوانده می‌شود و می‌توانید با گزینه -f نام فایلی برای آن تعیین کنید:
gist -f test.rb <a.rb
•
همچنین می‌توانید مستقیماً محتوای کلیپ‌بورد (Clipboard) را الصاق و بارگذاری کنید:
gist -P
•
استفاده از -p برای خصوصی کردن Gist:
gist -p a.rb
•
استفاده از -d برای افزودن توضیحات:
gist -d "Random rbx bug" a.rb
•
می‌توانید Gistهای موجود را با گزینه -u به‌روزرسانی کنید:
gist -u GIST_ID FILE_NAME gist -u 42f2c239d2eb57299408 test.txt
•
اگر می‌خواهید نشانی اینترنتی (URL) حاصل در کلیپ‌بورد کپی شود، از -c استفاده کنید:
gist -c <a.rb
•
اگر می‌خواهید نشانی جاسازی‌شدنی (Embeddable) در کلیپ‌بورد کپی شود، از -e استفاده کنید:
gist -e <a.rb
•
برای باز کردن مستقیم نشانی در پنجره مرورگر، از -o استفاده کنید:
gist -o <a.rb
•
برای فهرست کردن Gistهای یک کاربر (Gistهای عمومی یا تمام Gistهای کاربر احرازهویت‌شده):
gist -l : all gists for authed user gist -l defunkt : list defunkt's public gists

برای خواندن یک Gist و چاپ آن در خروجی استاندارد (STDOUT):

gist -r GIST_ID
gist -r 374130
•
برای مشاهده جزئیات بیشتر، خروجی gist --help را ببینید.

پیش از آنکه برای نخستین بار از gist استفاده کنید، باید وارد سیستم شوید. دو روش ورود پشتیبانی می‌شود:

1.
روش احراز هویت OAuth بر اساس کد دستگاه (Device-code flow) گیت‌هاب. این شیوه پیش‌فرض برای ورود به github.com است و می‌توان با ایجاد یک برنامه OAuth و مقداردهی متغیر محیطی GIST_CLIENT_ID با شناسه کلاینت (client id) آن برنامه، این شیوه را برای GitHub Enterprise نیز فعال کرد.
2.
روش تبادل توکن با نام کاربری و گذرواژه (منسوخ‌شده). این شیوه پیش‌فرض برای GitHub Enterprise است و می‌توان با مقداردهی متغیر محیطی GIST_USE_USERNAME_AND_PASSWORD از آن برای ورود به github.com نیز استفاده کرد.

این روش به شما امکان می‌دهد با ورود به گیت‌هاب در مرورگر و وارد کردن یک کد تایید، توکن دسترسی دریافت کنید. این روش توصیه می‌شود.

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

توکن دسترسی (access_token) دریافت‌شده در مسیر ~/.gist ذخیره شده و برای تمام عملیات‌های بعدی ارسال Gist استفاده می‌شود. در صورت نیاز می‌توانید دسترسی را از نشانی https://github.com/settings/connections/applications/4f7ec0d4eab38e74384e لغو کنید.

این روش نام کاربری، گذرواژه و در صورت وجود، کد تایید دومرحله‌ای (2FA) گیت‌هاب شما را درخواست می‌کند و آن‌ها را با یک توکن دارای مجوز «gist» مبادله می‌کند (نام کاربری و گذرواژه شما ذخیره نمی‌شوند). این سازوکار از سوی گیت‌هاب منسوخ شده است، اما ممکن است همچنان در نسخه‌های GitHub Enterprise کار کند.

gist --login
Obtaining OAuth2 access_token from GitHub.
GitHub username: ConradIrwin
GitHub password:
2-factor auth code:
Success! https://github.com/settings/tokens

این توکن در مسیر ~/.gist ذخیره شده و برای تمام ارسال‌های بعدی استفاده می‌شود. در صورت نیاز می‌توانید آن را از نشانی https://github.com/settings/tokens لغو کنید یا فایل مذکور را حذف نمایید.

اگر نیازمندی‌های احراز هویت پیچیده‌تری دارید، می‌توانید با الصاق یک توکن گیت‌هاب دارای محدوده دسترسی (scope) gist (و احتمالاً user:email برای GitHub Enterprise) درون فایلی به نام ~/.gist، فایل توکن را به‌صورت دستی ایجاد کنید. می‌توانید چنین توکنی را از نشانی https://github.com/settings/tokens بسازید.

این فایل باید تنها حاوی توکن (حدود ۴۰ نویسه هگزادسیمال) باشد و برای ویرایش آسان‌تر، می‌تواند در انتها یک خط جدید (\n یا \r\n) داشته باشد.

برای مثال، یک روش برای ساخت این فایل اجرای دستور زیر است:

(umask 0077 && echo MY_SECRET_TOKEN > ~/.gist)

استفاده از umask تضمین می‌کند که این فایل تنها از طریق حساب کاربری خود شما قابل دسترسی است.

اگر می‌خواهید gist از نسخه محلی GitHub Enterprise نصب‌شده شما در https://enterprise.github.com استفاده کند، باید متغیر محیطی GITHUB_URL را صادر (export) کنید (معمولاً در فایل ~/.bashrc شما انجام می‌شود).

export GITHUB_URL=http://github.internal.example.com/

پس از انجام این کار و راه‌اندازی مجدد ترمینال (یا اجرای source ~/.bashrc)، ابزار gist به‌طور خودکار به جای github.com عمومی از GitHub Enterprise استفاده خواهد کرد.

توکن شما برای GitHub Enterprise به جای ~/.gist در مسیری مانند .gist.<protocol>.<server.name>[.<port>] (برای مثال ~/.gist.http.github.internal.example.com برای متغیر GITHUB_URL بالا) ذخیره خواهد شد.

اگر چندین سرور دارید یا به تناوب از نسخه سازمانی و گیت‌هاب عمومی استفاده می‌کنید، می‌توانید با ساخت اسکریپت‌هایی که متغیر محیطی را تنظیم کرده و سپس gist را اجرا می‌کنند این کار را مدیریت کنید. به یاد داشته باشید که برای استفاده از گیت‌هاب عمومی باید مقدار این متغیر محیطی را پاک کنید. صرفاً تنظیم آن روی نشانی عمومی کار نخواهد کرد؛ از دستور unset GITHUB_URL استفاده کنید.

اگر نمی‌توانید از گذرواژه استفاده کنید (همانند اغلب نسخه‌های Enterprise)، می‌توانید توکن را از طریق رابط وب ایجاد کرده و سپس رشته آن را در فایل مربوطه ذخیره کنید. از قرار دادن شکست‌های خطی اضافه خودداری کنید، در غیر این صورت ممکن است با خطای زیر روبرو شوید:

$ gist -l
Error: Bad credentials
همچنین می‌توانید از Gist به‌عنوان یک کتابخانه در داخل کدهای روبی (Ruby) خود استفاده کنید:

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

  • :access_token برای احراز هویت با استفاده از OAuth2 (پیش‌فرض مقدار `File.read("~/.gist")) است).
  • :filename برای تغییر برجسته‌سازی نحوی (Syntax Highlighting) فایل (پیش‌فرض a.rb است).
  • :public اگر می‌خواهید Gist شما دارای نشانی قابل حدس زدن (عمومی) باشد.
  • :description برای افزودن توضیحات به Gist شما.
  • :update برای به‌روزرسانی یک Gist موجود (می‌تواند یک URL یا یک شناسه باشد).
  • :copy برای کپی کردن نشانی اینترنتی حاصل در کلیپ‌بورد (پیش‌فرض false است).
  • :open برای باز کردن نشانی اینترنتی حاصل در یک مرورگر (پیش‌فرض false است).

نکته: مقدار access_token باید دارای محدوده دسترسی (scope) gist باشد و همچنین ممکن است به محدوده user:email نیاز داشته باشد.

•
اگر می‌خواهید چند فایل را درون یک Gist بارگذاری کنید:
Gist.multi_gist("a.rb" => "Foo.bar", "a.py" => "Foo.bar")
•
اگر ترجیح می‌دهید از access_token داخلی gist استفاده کنید، می‌توانید با فراخوانی دستور زیر کاربر را وادار به دریافت توکن کنید:
Gist.login!
•
این کار کاربر را از طریق فرآیند دریافت توکن OAuth2 هدایت کرده و آن را در ~/.gist ذخیره می‌کند؛ جایی که بعداً توسط Gist.gist قابل خواندن خواهد بود.

•
اگر می‌خواهید گزینه‌های -o یا -c هنگام اجرای برنامه gist به‌طور پیش‌فرض فعال باشند، یک نام مستعار (alias) به فایل ~/.bashrc (یا معادل آن) اضافه کنید. برای نمونه:
alias gist='gist -c'
•
اگر ترجیح می‌دهید gist مرورگر متفاوتی را باز کند، می‌توانید متغیر محیطی BROWSER را صادر کنید:
export BROWSER=google-chrome

اگر یکپارچه‌سازی کلیپ‌بورد یا مرورگر در پلتفرم شما به درستی کار نمی‌کند، لطفاً یک گزارش باگ یا ترجیحاً یک Pull Request ارسال کنید.

اگر برای دسترسی به اینترنت نیاز به استفاده از یک پروکسی HTTP دارید، متغیر محیطی HTTP_PROXY یا http_proxy را صادر (export) کنید تا gist از آن استفاده کند.

با تشکر از @defunkt و @indirect برای نگارش و نگهداری نسخه‌های ۱ تا ۳. با تشکر از @rking و @ConradIrwin برای نگهداری نسخه ۴.

تحت مجوز MIT منتشر شده است. گزارش اشکالات و دریافت Pull Requestها با استقبال پذیرفته می‌شود.

July 2026