GIT-UPDATE-REF(1)                 Git Manual                 GIT-UPDATE-REF(1)

نام (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
           تنظیم <ref> به <new-oid> پس از اعتبارسنجی <old-oid> (در صورت
           ارائه). برای اطمینان از اینکه ارجاع پس از به‌روزرسانی وجود نداشته
           باشد مقدار صفر را برای <new-oid> و/یا برای اطمینان از اینکه ارجاع
           پیش از به‌روزرسانی وجود نداشته مقدار صفر را برای <old-oid> مشخص
           کنید.

       create
           ایجاد <ref> با مقدار <new-oid> پس از اطمینان از اینکه وجود ندارد.
           مقدار <new-oid> ارائه‌شده نباید صفر باشد.

       delete
           حذف <ref> پس از اطمینان از اینکه با <old-oid> (در صورت ارائه) وجود
           دارد. در صورت ارائه، مقدار <old-oid> نباید صفر باشد.

       symref-update
           تنظیم <ref> به <new-target> پس از اعتبارسنجی <old-target> یا
           <old-oid> (در صورت ارائه). یک مقدار صفر برای <old-oid> تعیین کنید
           تا مطمئن شوید ارجاع پیش از به‌روزرسانی وجود نداشته باشد.

       verify
           اعتبارسنجی <ref> در برابر <old-oid> بدون تغییر دادن آن. اگر
           <old-oid> صفر یا ناموجود باشد، ارجاع نباید وجود داشته باشد.

       symref-create
           ایجاد ارجاع نمادین <ref> با <new-target> پس از اطمینان از عدم وجود
           آن.

       symref-delete
           حذف <ref> پس از اطمینان از اینکه با <old-target> (در صورت ارائه)
           وجود دارد.

       symref-verify
           اعتبارسنجی ارجاع نمادین <ref> در برابر <old-target> بدون تغییر آن.
           اگر <old-target> ناموجود باشد، ارجاع نباید وجود داشته باشد. این
           دستور تنها در حالت no-deref قابل استفاده است.

       option
           تغییر رفتار دستور بعدی که نام یک <ref> را می‌برد. تنها گزینه معتبر
           no-deref برای جلوگیری از ارجاع‌زدایی یک ارجاع نمادین است.

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

       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)

Git 2.55.0                        2026-06-29                 GIT-UPDATE-REF(1)