نام (NAME)

git-update-ref - به‌روزرسانی ایمن نام شیء ذخیره‌شده در یک ارجاع

خلاصه دستور (SYNOPSIS)

git update-ref [-m <reason>] [--no-deref] -d <ref> [<old-oid>]
git update-ref [-m <reason>] [--no-deref] [--create-reflog] <ref> <new-oid> [<old-oid>]
git update-ref [-m <reason>] [--no-deref] --stdin [-z] [--batch-updates]

توضیحات (DESCRIPTION)

با دریافت دو آرگومان، مقدار <new-oid> را در <ref> ذخیره می‌کند، و در صورت نیاز ارجاع‌های نمادین (symbolic refs) را ارجاع‌زدایی (dereference) می‌نماید. برای مثال، دستور git update-ref HEAD <new-oid> اشاره‌گر نوک شاخه فعلی را به شیء جدید به‌روزرسانی می‌کند.

با دریافت سه آرگومان، پس از اطمینان از اینکه مقدار فعلی <ref> با <old-oid> مطابقت دارد، مقدار <new-oid> را در <ref> ذخیره می‌کند (با ارجاع‌زدایی احتمالی ارجاع‌های نمادین). به عنوان مثال، دستور git update-ref refs/heads/master <new-oid> <old-oid> نوک شاخه master را تنها زمانی به <new-oid> به‌روزرسانی می‌کند که مقدار فعلی آن برابر با <old-oid> باشد. می‌توانید ۴۰ نویسه "0" یا یک رشته خالی را به عنوان <old-oid> مشخص کنید تا مطمئن شوید ارجاعی که می‌سازید از قبل وجود نداشته باشد.

آرگومان‌های نهایی نام اشیاء هستند؛ این دستور بدون هیچ گزینه‌ای از به‌روزرسانی یک ارجاع نمادین برای اشاره به ارجاعی دیگر پشتیبانی نمی‌کند (به git-symbolic-ref(1) مراجعه کنید). اما دستور git update-ref --stdin دارای دستورات symref-* است تا ارجاع‌های معمولی و ارجاع‌های نمادین بتوانند در قالب یک تراکنش یکسان کامیت شوند.

اگر گزینه --no-deref مشخص شود، خود <ref> رونویسی می‌شود، نه مقداری که با دنبال کردن اشاره‌گرهای نمادین به دست می‌آید.

با گزینه -d، پس از بررسی و اطمینان از اینکه <ref> نام‌برده هنوز حاوی <old-oid> است، آن را حذف می‌کند.

با گزینه --stdin، دستور update-ref دستورالعمل‌ها را از ورودی استاندارد می‌خواند و تمام تغییرات را با یکدیگر اعمال می‌کند. دستورات را به شکل‌های زیر مشخص کنید:

update SP <ref> SP <new-oid> [SP <old-oid>] LF
create SP <ref> SP <new-oid> LF
delete SP <ref> [SP <old-oid>] LF
verify SP <ref> [SP <old-oid>] LF
symref-update SP <ref> SP <new-target> [SP (ref SP <old-target> | oid SP <old-oid>)] LF
symref-create SP <ref> SP <new-target> LF
symref-delete SP <ref> [SP <old-target>] LF
symref-verify SP <ref> [SP <old-target>] LF
option SP <opt> LF
start LF
prepare LF
commit LF
abort LF

با گزینه --create-reflog، دستور update-ref برای هر ارجاع یک reflog ایجاد خواهد کرد حتی اگر در حالت عادی ایجاد نمی‌شد.

با گزینه --batch-updates، دستور update-ref به‌روزرسانی‌ها را در یک دسته (batch) اجرا می‌کند اما اجازه می‌دهد به‌روزرسانی‌های منفرد به دلیل ورودی نادرست یا نامعتبر کاربر با خطا مواجه شوند، و تنها به‌روزرسانی‌های موفق اعمال خواهند شد. با این حال، خطاهای مربوط به سیستم —مانند خطاهای I/O یا مشکلات حافظه— منجر به شکست کامل تمام به‌روزرسانی‌های دسته‌ای خواهد شد. هر به‌روزرسانی ناموفق با ساختار زیر گزارش می‌شود:

rejected SP (<old-oid> | <old-target>) SP (<new-oid> | <new-target>) SP <rejection-reason> LF

فیلدهای حاوی فاصله خالی را همانند رشته‌ها در کد منبع C درون گیومه قرار دهید؛ یعنی محصور در نقل‌قول دوتایی و با کاراکترهای اسکیپ بک‌اسلش. از ۴۰ نویسه "0" یا رشته خالی برای مشخص کردن مقدار صفر استفاده کنید. برای تعیین یک مقدار حذف‌شده یا وجودنداشته، مقدار و فاصله قبل از آن (SP) را کاملاً حذف کنید.

به عنوان روش جایگزین، از -z برای مشخص کردن مقادیر با فرمت خاتمه‌یافته با NUL و بدون نقل‌قول استفاده نمایید:

update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL
create SP <ref> NUL <new-oid> NUL
delete SP <ref> NUL [<old-oid>] NUL
verify SP <ref> NUL [<old-oid>] NUL
symref-update SP <ref> NUL <new-target> [NUL (ref NUL <old-target> | oid NUL <old-oid>)] NUL
symref-create SP <ref> NUL <new-target> NUL
symref-delete SP <ref> [NUL <old-target>] NUL
symref-verify SP <ref> [NUL <old-target>] NUL
option SP <opt> NUL
start NUL
prepare NUL
commit NUL
abort NUL

در این قالب، از ۴۰ نویسه "0" برای مشخص کردن مقدار صفر، و از یک رشته خالی برای مشخص کردن مقدار ناموجود استفاده کنید.

در هر دو قالب، مقادیر می‌توانند به هر شکلی که گیت به عنوان یک نام شیء به رسمیت می‌شناسد مشخص شوند. دستورات در هر قالب دیگر یا یک <ref> تکراری باعث تولید خطا خواهند شد. معانی دستورات به شرح زیر است:

update

create

delete

symref-update

verify

symref-create

symref-delete

symref-verify

option

start

prepare

commit

abort

اگر تمام <ref>ها بتوانند با مقادیر منطبق <old-oid> به طور همزمان قفل شوند، تمام تغییرات اعمال می‌گردند. در غیر این صورت، هیچ تغییری اعمال نخواهد شد. توجه داشته باشید در حالی که هر <ref> به صورت منفرد و اتمیک به‌روزرسانی یا حذف می‌شود، یک خواننده همزمان ممکن است همچنان زیرمجموعه‌ای از این تغییرات را مشاهده کند.

ثبت وقایع به‌روزرسانی‌ها (LOGGING UPDATES)

اگر پارامتر پیکربندی "core.logAllRefUpdates" برابر با true باشد و ارجاع یکی از موارد زیر "refs/heads/"، "refs/remotes/"، "refs/notes/"، یا یک شبه‌ارجاع مانند HEAD یا ORIG_HEAD باشد؛ یا فایل "$GIT_DIR/logs/<ref>" وجود داشته باشد، آنگاه git update-ref خطی را به فایل لاگ "$GIT_DIR/logs/<ref>" اضافه خواهد کرد (با ارجاع‌زدایی از همه ارجاع‌های نمادین قبل از ایجاد نام لاگ) که تغییر مقدار ارجاع را شرح می‌دهد. خطوط لاگ به این قالب هستند:

oldsha1 SP newsha1 SP committer LF

که در آن "oldsha1" مقدار هگزادسیمال ۴۰ نویسه‌ای ذخیره‌شده قبلی در <ref> است، "newsha1" مقدار هگزادسیمال ۴۰ نویسه‌ای <new-oid> بوده و "committer" نام، نشانی رایانامه و تاریخ کامیت‌کننده در قالب استاندارد شناسه کامیت‌کننده گیت است.

به صورت اختیاری با گزینه -m:

oldsha1 SP newsha1 SP committer TAB message LF

که در آن همه فیلدها همانند توضیحات بالا هستند و "message" مقداری است که به گزینه -m داده شده است.

در صورتی که کاربر جاری قادر به ایجاد یک فایل لاگ جدید نباشد، نتواند به فایل لاگ موجود اضافه کند، یا اطلاعات کامیت‌کننده در دسترس نباشد، به‌روزرسانی با خطا مواجه خواهد شد (بدون ایجاد تغییر در <ref>).

نکات (NOTES)

ارجاع‌های نمادین در ابتدا با استفاده از پیوندهای نمادین پیاده‌سازی شده بودند. این روش اکنون منسوخ شده است زیرا همه سیستم‌های فایل از پیوندهای نمادین پشتیبانی نمی‌کنند.

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

همچنین ببینید (SEE ALSO)

git-symbolic-ref(1)

گیت (GIT)

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