GIT-CREDENTIAL(1) دستورات عمومی کاربر GIT-CREDENTIAL(1)

git-credential - بازیابی و ذخیره اطلاعات احراز هویت کاربر

'git credential' (fill|approve|reject|capability)

گیت دارای یک رابط داخلی برای ذخیره و بازیابی اطلاعات احراز هویت از برنامه‌های کمکی خاص سیستم، و همچنین درخواست نام کاربری و گذرواژه از کاربر است. دستور git-credential این رابط را در دسترس اسکریپت‌هایی قرار می‌دهد که ممکن است بخواهند اطلاعات احراز هویت را به همان شیوه گیت بازیابی، ذخیره یا از کاربر درخواست کنند. طراحی این رابط قابل اسکریپت‌نویسی، از API داخلی C الگوبرداری شده است؛ برای پیش‌زمینه بیشتر درباره مفاهیم، credential.h را ببینید.

دستور git-credential یک گزینه عملیات ("action") در خط فرمان دریافت می‌کند (یکی از fill، approve یا reject) و شرح اطلاعات احراز هویت را از ورودی استاندارد (stdin) می‌خواند (بخش «قالب ورودی/خروجی» را ببینید).

اگر عملیات برابر با fill باشد، git-credential تلاش خواهد کرد با خواندن فایل‌های پیکربندی، ارتباط با برنامه‌های کمکی پیکربندی‌شده احراز هویت یا درخواست از کاربر، مشخصه‌های «username» و «password» را به شرح اضافه کند. سپس مشخصه‌های نام کاربری و گذرواژه از شرح اطلاعات احراز هویت همراه با مشخصه‌هایی که از پیش ارائه شده‌اند در خروجی استاندارد چاپ می‌شوند.

اگر عملیات برابر با approve باشد، git-credential شرح را برای تمام برنامه‌های کمکی پیکربندی‌شده احراز هویت ارسال می‌کند که ممکن است اطلاعات احراز هویت را برای استفاده‌های بعدی ذخیره کنند.

اگر عملیات برابر با reject باشد، git-credential شرح را برای تمام برنامه‌های کمکی پیکربندی‌شده احراز هویت ارسال می‌کند که ممکن است هرگونه اطلاعات احراز هویت ذخیره‌شده منطبق با این شرح را پاک کنند.

اگر عملیات برابر با capability باشد، git-credential هر قابلیتی را که پشتیبانی می‌کند در خروجی استاندارد اعلام خواهد کرد.

اگر عملیات برابر با approve یا reject باشد، نباید هیچ خروجی تولید شود.

برنامه‌ای که از git-credential استفاده می‌کند، معمولاً با دنبال کردن این مراحل از git credential استفاده خواهد کرد:

1.تولید یک شرح اطلاعات احراز هویت بر اساس زمینه مورد نظر.

برای نمونه، اگر گذرواژه‌ای برای https://example.com/foo.git بخواهیم، ممکن است شرح اطلاعات احراز هویت زیر را تولید کنیم (خط خالی انتهای آن را فراموش نکنید؛ این خط به git credential اعلام می‌کند که برنامه، ارائه تمام اطلاعات موجود خود را به پایان رسانده است):

protocol=https
host=example.com
path=foo.git
2.درخواست از git-credential برای ارائه نام کاربری و گذرواژه مربوط به این شرح. این کار با اجرای دستور git credential fill و ارسال شرح مرحله (۱) به ورودی استاندارد آن انجام می‌شود. شرح کامل اطلاعات احراز هویت (از جمله خود اعتبارنامه، یعنی شناسه ورود و گذرواژه) در خروجی استاندارد تولید خواهد شد، مانند: 
protocol=https
host=example.com
username=bob
password=secr3t

در بیشتر موارد، این بدان معناست که مشخصه‌های ارائه‌شده در ورودی، در خروجی تکرار خواهند شد، اما گیت ممکن است شرح اطلاعات احراز هویت را نیز تغییر دهد؛ برای نمونه، با حذف مشخصه path هنگامی که پروتکل HTTP(s) بوده و مقدار credential.useHttpPath برابر با false باشد.

اگر git credential از گذرواژه مطلع بود، این مرحله پیش از بازگرداندن password=secr3t ممکن است نیازی به تایپ واقعی این گذرواژه توسط کاربر نداشته باشد (کاربر ممکن است در عوض گذرواژه‌ای برای باز کردن قفل دسته‌کلید (keychain) وارد کرده باشد، یا در صورتی که قفل دسته‌کلید از قبل باز بوده، هیچ تعاملی با کاربر انجام نشده باشد).

3.استفاده از اطلاعات احراز هویت (برای نمونه، دسترسی به نشانی وب با نام کاربری و گذرواژه مرحله (۲))، و بررسی اینکه آیا پذیرفته شده است یا خیر.
4.گزارش موفقیت یا عدم موفقیت گذرواژه. اگر اطلاعات احراز هویت اجازه داد عملیات با موفقیت تکمیل شود، می‌توان آن را با عملیات «approve» علامت‌گذاری کرد تا به git credential اعلام شود در فراخوانی بعدی آن را دوباره استفاده کند. اگر اطلاعات احراز هویت در حین عملیات رد شد، از عملیات «reject» استفاده کنید تا git credential در فراخوانی بعدی گذرواژه جدیدی درخواست کند. در هر دو حالت، باید شرح اطلاعات احراز هویت به‌دست‌آمده از مرحله (۲) (که شامل فیلدهای ارائه‌شده در مرحله (۱) نیز هست) به git credential ارائه شود.

دستور git credential (بسته به عملیات استفاده‌شده) اطلاعات احراز هویت را در ورودی/خروجی استاندارد خود می‌خواند و/یا می‌نویسد. این اطلاعات می‌توانند مربوط به کلیدهایی باشند که git credential برای آن‌ها اطلاعات ورود را به دست می‌آورد (برای نمونه host، protocol، path)، یا داده‌های واقعی اطلاعات احراز هویت باشند که باید به دست آیند (username/password).

اطلاعات احراز هویت به مجموعه‌ای از مشخصه‌های نام‌گذاری‌شده تقسیم می‌شود، به طوری که در هر خط یک مشخصه قرار دارد. هر مشخصه با یک جفت کلید-مقدار مشخص می‌شود که با یک علامت مساوی (=) از هم جدا شده و در انتهای آن یک خط جدید قرار می‌گیرد.

کلید می‌تواند شامل هر بایتی به جز =، خط جدید یا NUL باشد. مقدار می‌تواند شامل هر بایتی به جز خط جدید یا NUL باشد. برای اینکه پیاده‌سازی‌ها بتوانند پردازش را به صورت کارآمد انجام دهند، یک خط، شامل خط جدید انتهایی، نباید از ۶۵۵۳۵ بایت تجاوز کند.

مشخصه‌هایی با کلیدهایی که به براکت‌های آرایه‌ای به سبک زبان C یعنی [] ختم می‌شوند می‌توانند مقادیر متعددی داشته باشند. هر نمونه از یک مشخصه چندمقداری، یک فهرست مرتب از مقادیر را تشکیل می‌دهد - ترتیب مشخصه‌های تکرارشده، ترتیب مقادیر را مشخص می‌کند. یک مشخصه چندمقداری خالی (key[]=\n) برای پاک کردن ورودی‌های قبلی و بازنشانی فهرست عمل می‌کند.

در تمام موارد، با همه بایت‌ها به‌صورت همان‌گونه که هستند رفتار می‌شود (یعنی هیچ نقل‌قولی وجود ندارد، و نمی‌توان مقداری با خط جدید یا NUL در آن ارسال کرد). فهرست مشخصه‌ها با یک خط خالی یا پایان فایل خاتمه می‌یابد.

گیت مشخصه‌های زیر را درک می‌کند:

protocol

پروتکلی که اطلاعات احراز هویت روی آن استفاده خواهد شد (برای نمونه، https).

host

نام میزبان راه دور برای یک اطلاعات احراز هویت شبکه. در صورتی که شماره پورت مشخص شده باشد، این مورد شامل شماره پورت نیز می‌شود (برای نمونه، "example.com:8088").

path

مسیری که اطلاعات احراز هویت با آن استفاده خواهد شد. برای نمونه، جهت دسترسی به یک مخزن راه دور https، این مقدار مسیر مخزن بر روی سرور خواهد بود.

username

نام کاربری اطلاعات احراز هویت، در صورتی که از قبل آن را داشته باشیم (برای نمونه، از یک نشانی اینترنتی، پیکربندی، کاربر، یا از یک برنامه کمکی که پیش‌تر اجرا شده است).

password

گذرواژه اطلاعات احراز هویت، در صورتی که درخواست ذخیره آن را داریم.

password_expiry_utc

گذرواژه‌های تولیدشده مانند توکن دسترسی OAuth ممکن است تاریخ انقضا داشته باشند. هنگام خواندن اطلاعات احراز هویت از برنامه‌های کمکی، git credential fill گذرواژه‌های منقضی‌شده را نادیده می‌گیرد. این مقدار به صورت زمان یونیکس UTC، به ثانیه‌ها از سال ۱۹۷۰ نمایش داده می‌شود.

oauth_refresh_token

یک توکن تازه‌سازی OAuth ممکن است همراه با گذرواژه‌ای باشد که خود یک توکن دسترسی OAuth است. برنامه‌های کمکی باید با این مشخصه مانند مشخصه گذرواژه به صورت محرمانه رفتار کنند. خود گیت رفتار خاصی برای این مشخصه ندارد.

url

هنگامی که این مشخصه ویژه توسط git credential خوانده می‌شود، مقدار آن به عنوان یک نشانی اینترنتی (URL) تجزیه شده و طوری با آن رفتار می‌شود که گویی اجزای تشکیل‌دهنده آن خوانده شده‌اند (برای نمونه، url=https://example.com طوری عمل خواهد کرد که گویی protocol=https و host=example.com ارائه شده‌اند). این می‌تواند به فراخواننده‌ها کمک کند تا از تجزیه نشانی‌های اینترنتی توسط خودشان بی‌نیاز شوند.

توجه داشته باشید که تعیین پروتکل اجباری است و اگر نشانی اینترنتی نام میزبان را مشخص نکند (برای نمونه، "cert:///path/to/file")، اطلاعات احراز هویت شامل یک مشخصه نام میزبان خواهد بود که مقدار آن یک رشته خالی است.

اجزایی که در نشانی اینترنتی وجود ندارند (برای نمونه، در مثال بالا نام کاربری وجود ندارد) بدون مقدار رها خواهند شد.

authtype

این مشخصه نشان می‌دهد که باید از طرح احراز هویت مورد نظر استفاده شود. مقادیر متداول برای HTTP و HTTPS شامل basic، bearer، و digest است، گرچه مورد آخر ناامن بوده و نباید استفاده شود. اگر credential استفاده شود، ممکن است این مشخصه روی یک رشته دلخواه و مناسب برای پروتکل مورد نظر (معمولاً HTTP) تنظیم شود.

این مقدار نباید ارسال شود مگر اینکه قابلیت مناسب (زیر را ببینید) در ورودی ارائه شده باشد.

credential

اطلاعات احراز هویت از پیش کدگذاری‌شده، مناسب برای پروتکل مورد نظر (معمولاً HTTP). اگر این کلید ارسال شود، authtype اجباری است و از username و password استفاده نمی‌شود. برای HTTP، گیت مقدار authtype و این مقدار را با یک فاصله ادغام می‌کند تا سرآیند Authorization را تعیین نماید.

این مقدار نباید ارسال شود مگر اینکه قابلیت مناسب (زیر را ببینید) در ورودی ارائه شده باشد.

ephemeral

این مقدار بولی در صورت true بودن نشان می‌دهد که مقدار موجود در فیلد credential نباید توسط برنامه کمکی احراز هویت ذخیره شود، زیرا سودمندی آن از نظر زمانی محدود است. برای نمونه، یک مقدار credential از نوع HTTP Digest با استفاده از یک نانس (nonce) محاسبه می‌شود و استفاده مجدد از آن منجر به احراز هویت موفق نخواهد شد. همچنین این ممکن است برای شرایطی با اطلاعات احراز هویت کوتاه‌مدت (مانند ۲۴ ساعته) استفاده شود. مقدار پیش‌فرض false است.

برنامه کمکی احراز هویت همچنان با store یا erase فراخوانی می‌شود تا بتواند تعیین کند که آیا عملیات موفقیت‌آمیز بوده است یا خیر.

این مقدار نباید ارسال شود مگر اینکه قابلیت مناسب (زیر را ببینید) در ورودی ارائه شده باشد.

state[]

این مقدار یک وضعیت مات (opaque) ارائه می‌دهد که در صورت فراخوانی مجدد این برنامه کمکی، به آن بازگردانده خواهد شد. هر برنامه کمکی احراز هویت مختلف ممکن است این مورد را یک بار مشخص کند. این مقدار باید شامل یک پیشوند منحصربه‌فرد برای برنامه کمکی احراز هویت باشد و باید مقادیری را که با پیشوند آن مطابقت ندارند نادیده بگیرد.

این مقدار نباید ارسال شود مگر اینکه قابلیت مناسب (زیر را ببینید) در ورودی ارائه شده باشد.

continue

این یک مقدار بولی است که در صورت فعال بودن نشان می‌دهد که این احراز هویت یک بخش غیرنهایی از یک مرحله احراز هویت چندمرحله‌ای است. این در پروتکل‌هایی مانند NTLM و Kerberos رایج است، جایی که دو دور احراز هویت کلاینت لازم است، و تنظیم این فلگ به برنامه کمکی احراز هویت اجازه می‌دهد مرحله احراز هویت چندمرحله‌ای را پیاده‌سازی کند. این فلگ فقط باید در صورتی ارسال شود که مرحله بعدی لازم باشد؛ یعنی اگر دور دیگری از احراز هویت انتظار می‌رود.

این مقدار نباید ارسال شود مگر اینکه قابلیت مناسب (زیر را ببینید) در ورودی ارائه شده باشد. این مشخصه یک‌طرفه از طرف یک برنامه کمکی احراز هویت است تا اطلاعات را به گیت (یا سایر برنامه‌هایی که git credential را فراخوانی می‌کنند) منتقل کند.

wwwauth[]

هنگامی که یک پاسخ HTTP توسط گیت دریافت می‌شود که شامل یک یا چند سرآیند احراز هویت WWW-Authenticate است، این سرآیندها توسط گیت به برنامه‌های کمکی احراز هویت منتقل می‌شوند.

هر مقدار سرآیند WWW-Authenticate به عنوان یک مشخصه چندمقداری wwwauth[] ارسال می‌شود، جایی که ترتیب مشخصه‌ها همان ترتیبی است که در پاسخ HTTP ظاهر می‌شوند. این مشخصه یک‌طرفه از طرف گیت است تا اطلاعات اضافی را به برنامه‌های کمکی احراز هویت منتقل کند.

capability[]

این مشخصه نشان می‌دهد که گیت یا برنامه کمکی، حسب مورد، از قابلیت مورد نظر پشتیبانی می‌کنند. این می‌تواند برای ارائه داده‌های بهتر و مشخص‌تر به عنوان بخشی از پروتکل استفاده شود. دستورالعمل capability[] باید پیش از هر مقداری که به آن وابسته است قرار گیرد و این دستورالعمل‌ها باید اولین موردی باشند که در پروتکل اعلام می‌شوند.

در حال حاضر دو قابلیت پشتیبانی می‌شوند. اولی authtype است که نشان می‌دهد مقادیر authtype، credential، و ephemeral درک می‌شوند. دومی state است که نشان می‌دهد مقادیر state[] و continue درک می‌شوند.

الزامی نیست که فقط به دلیل پشتیبانی از یک قابلیت از ویژگی‌های اضافی استفاده شود، اما آن‌ها نباید بدون وجود آن قابلیت ارائه شوند.

مشخصه‌ها و قابلیت‌های ناشناخته بدون سر و صدا نادیده گرفته می‌شوند.

برای دستور git credential capability، قالب کمی متفاوت است. نخست، یک اعلان version 0 برای نشان دادن نسخه فعلی پروتکل انجام می‌شود، و سپس هر قابلیت با خطی مانند capability authtype اعلام می‌گردد. برنامه‌های کمکی احراز هویت نیز می‌توانند این قالب را پیاده‌سازی کنند، باز هم با آرگومان capability. ممکن است در آینده خطوط دیگری اضافه شوند؛ فراخواننده‌ها باید خطوطی را که متوجه نمی‌شوند نادیده بگیرند.

از آنجا که این یک بخش جدید از پروتکل برنامه‌های کمکی احراز هویت است، نسخه‌های قدیمی‌تر گیت و همچنین برخی از برنامه‌های کمکی ممکن است از آن پشتیبانی نکنند. اگر وضعیت خروج غیر صفر دریافت شود، یا اگر خط نخست با کلمه version و یک فاصله شروع نشود، فراخواننده‌ها باید فرض کنند که هیچ قابلیتی پشتیبانی نمی‌شود.

هدف از این قالب، متمایز ساختن آن از خروجی اطلاعات احراز هویت به شیوه‌ای بدون ابهام است. استفاده از برنامه‌های کمکی بسیار ساده احراز هویت (برای نمونه، اسکریپت‌های پوسته درون‌خطی) که همیشه خروجی یکسانی تولید می‌کنند ممکن است. استفاده از یک قالب متمایز به کاربران امکان می‌دهد بدون نگرانی در مورد پیاده‌سازی صحیح اعلان قابلیت‌ها یا سردرگم کردن تصادفی فراخوانندگانی که برای قابلیت‌ها پرس‌وجو می‌کنند، همچنان از این نحو استفاده نمایند.

بخشی از مجموعه git(1)

2026-06-29 Git 2.55.0