'\" t
.\"     Title: git-update-ref
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net>
.\"      Date: 2026-06-29
.\"    Manual: Git Manual
.\"    Source: Git 2.55.0
.\"  Language: English
.\"
.TH "GIT\-UPDATE\-REF" "1" "2026\-06\-29" "Git 2\&.55\&.0" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
git-update-ref \- به‌روزرسانی ایمن نام شیء ذخیره‌شده در یک ارجاع
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fBgit\fR \fBupdate\-ref\fR [\fB\-m\fR \fI<reason>\fR] [\fB\-\-no\-deref\fR] \fB\-d\fR \fI<ref>\fR [\fI<old\-oid>\fR]
\fBgit\fR \fBupdate\-ref\fR [\fB\-m\fR \fI<reason>\fR] [\fB\-\-no\-deref\fR] [\fB\-\-create\-reflog\fR] \fI<ref>\fR \fI<new\-oid>\fR [\fI<old\-oid>\fR]
\fBgit\fR \fBupdate\-ref\fR [\fB\-m\fR \fI<reason>\fR] [\fB\-\-no\-deref\fR] \fB\-\-stdin\fR [\fB\-z\fR] [\fB\-\-batch\-updates\fR]
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
با دریافت دو آرگومان، مقدار <new\-oid> را در <ref> ذخیره می‌کند، و در صورت نیاز ارجاع‌های نمادین (symbolic refs) را ارجاع‌زدایی (dereference) می‌نماید. برای مثال، دستور \fBgit\fR \fBupdate\-ref\fR \fBHEAD\fR \fI<new\-oid>\fR اشاره‌گر نوک شاخه فعلی را به شیء جدید به‌روزرسانی می‌کند.
.sp
با دریافت سه آرگومان، پس از اطمینان از اینکه مقدار فعلی <ref> با <old\-oid> مطابقت دارد، مقدار <new\-oid> را در <ref> ذخیره می‌کند (با ارجاع‌زدایی احتمالی ارجاع‌های نمادین). به عنوان مثال، دستور \fBgit\fR \fBupdate\-ref\fR \fBrefs/heads/master\fR \fI<new\-oid>\fR \fI<old\-oid>\fR نوک شاخه master را تنها زمانی به <new\-oid> به‌روزرسانی می‌کند که مقدار فعلی آن برابر با <old\-oid> باشد. می‌توانید ۴۰ نویسه "0" یا یک رشته خالی را به عنوان <old\-oid> مشخص کنید تا مطمئن شوید ارجاعی که می‌سازید از قبل وجود نداشته باشد.
.sp
آرگومان‌های نهایی نام اشیاء هستند؛ این دستور بدون هیچ گزینه‌ای از به‌روزرسانی یک ارجاع نمادین برای اشاره به ارجاعی دیگر پشتیبانی نمی‌کند (به \fBgit-symbolic-ref\fR(1) مراجعه کنید). اما دستور \fBgit\fR \fBupdate\-ref\fR \fB\-\-stdin\fR دارای دستورات \fBsymref\-*\fR است تا ارجاع‌های معمولی و ارجاع‌های نمادین بتوانند در قالب یک تراکنش یکسان کامیت شوند.
.sp
اگر گزینه \-\-no\-deref مشخص شود، خود <ref> رونویسی می‌شود، نه مقداری که با دنبال کردن اشاره‌گرهای نمادین به دست می‌آید.
.sp
با گزینه \fB\-d\fR، پس از بررسی و اطمینان از اینکه <ref> نام‌برده هنوز حاوی <old\-oid> است، آن را حذف می‌کند.
.sp
با گزینه \fB\-\-stdin\fR، دستور update\-ref دستورالعمل‌ها را از ورودی استاندارد می‌خواند و تمام تغییرات را با یکدیگر اعمال می‌کند. دستورات را به شکل‌های زیر مشخص کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.sp
با گزینه \fB\-\-create\-reflog\fR، دستور update\-ref برای هر ارجاع یک reflog ایجاد خواهد کرد حتی اگر در حالت عادی ایجاد نمی‌شد.
.sp
با گزینه \fB\-\-batch\-updates\fR، دستور update\-ref به‌روزرسانی‌ها را در یک دسته (batch) اجرا می‌کند اما اجازه می‌دهد به‌روزرسانی‌های منفرد به دلیل ورودی نادرست یا نامعتبر کاربر با خطا مواجه شوند، و تنها به‌روزرسانی‌های موفق اعمال خواهند شد. با این حال، خطاهای مربوط به سیستم \(emمانند خطاهای I/O یا مشکلات حافظه\(em منجر به شکست کامل تمام به‌روزرسانی‌های دسته‌ای خواهد شد. هر به‌روزرسانی ناموفق با ساختار زیر گزارش می‌شود:
.sp
.if n \{\
.RS 4
.\}
.nf
rejected SP (<old\-oid> | <old\-target>) SP (<new\-oid> | <new\-target>) SP <rejection\-reason> LF
.fi
.if n \{\
.RE
.\}
.sp
فیلدهای حاوی فاصله خالی را همانند رشته‌ها در کد منبع C درون گیومه قرار دهید؛ یعنی محصور در نقل‌قول دوتایی و با کاراکترهای اسکیپ بک‌اسلش. از ۴۰ نویسه "0" یا رشته خالی برای مشخص کردن مقدار صفر استفاده کنید. برای تعیین یک مقدار حذف‌شده یا وجودنداشته، مقدار و فاصله قبل از آن (SP) را کاملاً حذف کنید.
.sp
به عنوان روش جایگزین، از \fB\-z\fR برای مشخص کردن مقادیر با فرمت خاتمه‌یافته با NUL و بدون نقل‌قول استفاده نمایید:
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.sp
در این قالب، از ۴۰ نویسه "0" برای مشخص کردن مقدار صفر، و از یک رشته خالی برای مشخص کردن مقدار ناموجود استفاده کنید.
.sp
در هر دو قالب، مقادیر می‌توانند به هر شکلی که گیت به عنوان یک نام شیء به رسمیت می‌شناسد مشخص شوند. دستورات در هر قالب دیگر یا یک <ref> تکراری باعث تولید خطا خواهند شد. معانی دستورات به شرح زیر است:
.PP
update
.RS 4
تنظیم <ref> به <new\-oid> پس از اعتبارسنجی <old\-oid> (در صورت ارائه). برای اطمینان از اینکه ارجاع پس از به‌روزرسانی وجود نداشته باشد مقدار صفر را برای <new\-oid> و/یا برای اطمینان از اینکه ارجاع پیش از به‌روزرسانی وجود نداشته مقدار صفر را برای <old\-oid> مشخص کنید.
.RE
.PP
create
.RS 4
ایجاد <ref> با مقدار <new\-oid> پس از اطمینان از اینکه وجود ندارد. مقدار <new\-oid> ارائه‌شده نباید صفر باشد.
.RE
.PP
delete
.RS 4
حذف <ref> پس از اطمینان از اینکه با <old\-oid> (در صورت ارائه) وجود دارد. در صورت ارائه، مقدار <old\-oid> نباید صفر باشد.
.RE
.PP
symref\-update
.RS 4
تنظیم <ref> به <new\-target> پس از اعتبارسنجی <old\-target> یا <old\-oid> (در صورت ارائه). یک مقدار صفر برای <old\-oid> تعیین کنید تا مطمئن شوید ارجاع پیش از به‌روزرسانی وجود نداشته باشد.
.RE
.PP
verify
.RS 4
اعتبارسنجی <ref> در برابر <old\-oid> بدون تغییر دادن آن. اگر <old\-oid> صفر یا ناموجود باشد، ارجاع نباید وجود داشته باشد.
.RE
.PP
symref\-create
.RS 4
ایجاد ارجاع نمادین <ref> با <new\-target> پس از اطمینان از عدم وجود آن.
.RE
.PP
symref\-delete
.RS 4
حذف <ref> پس از اطمینان از اینکه با <old\-target> (در صورت ارائه) وجود دارد.
.RE
.PP
symref\-verify
.RS 4
اعتبارسنجی ارجاع نمادین <ref> در برابر <old\-target> بدون تغییر آن. اگر <old\-target> ناموجود باشد، ارجاع نباید وجود داشته باشد. این دستور تنها در حالت
\fBno\-deref\fR
قابل استفاده است.
.RE
.PP
option
.RS 4
تغییر رفتار دستور بعدی که نام یک <ref> را می‌برد. تنها گزینه معتبر
\fBno\-deref\fR
برای جلوگیری از ارجاع‌زدایی یک ارجاع نمادین است.
.RE
.PP
start
.RS 4
شروع یک تراکنش. بر خلاف یک نشست غیرتراکنشی، در صورتی که نشست بدون یک کامیت صریح پایان یابد، یک تراکنش به طور خودکار لغو (abort) می‌شود. این دستور ممکن است در زمانی که تراکنش فعلی قبلاً کامیت یا لغو شده است، یک تراکنش خالی جدید ایجاد کند.
.RE
.PP
prepare
.RS 4
آماده‌سازی برای کامیت تراکنش. این کار فایل‌های قفل را برای همه به‌روزرسانی‌های ارجاع در صف ایجاد خواهد کرد. اگر یکی از ارجاع‌ها نتواند قفل شود، تراکنش لغو می‌شود.
.RE
.PP
commit
.RS 4
کامیت کردن تمام به‌روزرسانی‌های ارجاع در صف این تراکنش، که باعث پایان تراکنش می‌شود.
.RE
.PP
abort
.RS 4
لغو تراکنش، و آزادسازی تمام قفل‌ها در صورتی که تراکنش در حالت آماده‌سازی باشد.
.RE
.sp
اگر تمام <ref>ها بتوانند با مقادیر منطبق <old\-oid> به طور همزمان قفل شوند، تمام تغییرات اعمال می‌گردند. در غیر این صورت، هیچ تغییری اعمال نخواهد شد. توجه داشته باشید در حالی که هر <ref> به صورت منفرد و اتمیک به‌روزرسانی یا حذف می‌شود، یک خواننده همزمان ممکن است همچنان زیرمجموعه‌ای از این تغییرات را مشاهده کند.
.SH "ثبت وقایع به‌روزرسانی‌ها (LOGGING UPDATES)"
.sp
اگر پارامتر پیکربندی "core\&.logAllRefUpdates" برابر با true باشد و ارجاع یکی از موارد زیر "refs/heads/"، "refs/remotes/"، "refs/notes/"، یا یک شبه‌ارجاع مانند HEAD یا ORIG_HEAD باشد؛ یا فایل "$GIT_DIR/logs/<ref>" وجود داشته باشد، آنگاه \fBgit\fR \fBupdate\-ref\fR خطی را به فایل لاگ "$GIT_DIR/logs/<ref>" اضافه خواهد کرد (با ارجاع‌زدایی از همه ارجاع‌های نمادین قبل از ایجاد نام لاگ) که تغییر مقدار ارجاع را شرح می‌دهد. خطوط لاگ به این قالب هستند:
.sp
.if n \{\
.RS 4
.\}
.nf
oldsha1 SP newsha1 SP committer LF
.fi
.if n \{\
.RE
.\}
.sp
که در آن "oldsha1" مقدار هگزادسیمال ۴۰ نویسه‌ای ذخیره‌شده قبلی در <ref> است، "newsha1" مقدار هگزادسیمال ۴۰ نویسه‌ای <new\-oid> بوده و "committer" نام، نشانی رایانامه و تاریخ کامیت‌کننده در قالب استاندارد شناسه کامیت‌کننده گیت است.
.sp
به صورت اختیاری با گزینه \-m:
.sp
.if n \{\
.RS 4
.\}
.nf
oldsha1 SP newsha1 SP committer TAB message LF
.fi
.if n \{\
.RE
.\}
.sp
که در آن همه فیلدها همانند توضیحات بالا هستند و "message" مقداری است که به گزینه \-m داده شده است.
.sp
در صورتی که کاربر جاری قادر به ایجاد یک فایل لاگ جدید نباشد، نتواند به فایل لاگ موجود اضافه کند، یا اطلاعات کامیت‌کننده در دسترس نباشد، به‌روزرسانی با خطا مواجه خواهد شد (بدون ایجاد تغییر در <ref>).
.SH "نکات (NOTES)"
.sp
ارجاع‌های نمادین در ابتدا با استفاده از پیوندهای نمادین پیاده‌سازی شده بودند. این روش اکنون منسوخ شده است زیرا همه سیستم‌های فایل از پیوندهای نمادین پشتیبانی نمی‌کنند.
.sp
این دستور پیوندهای نمادین \fBواقعی\fR را تنها در صورتی دنبال می‌کند که با "refs/" شروع شوند؛ در غیر این صورت فقط تلاش می‌کند آن‌ها را بخواند و به عنوان یک فایل معمولی به‌روزرسانی کند (یعنی به سیستم فایل اجازه می‌دهد آن‌ها را دنبال کند، اما چنین پیوند نمادینی به جای دیگر را با یک نام فایل معمولی رونویسی خواهد کرد).
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgit-symbolic-ref\fR(1)
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)