'\" t
.\"     Title: git-format-rev
.\"    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: راهنمای گیت
.\"    Source: Git 2.55.0
.\"  Language: Persian
.\"
.TH "GIT\-FORMAT\-REV" "1" "2026\-06\-29" "Git 2\&.55\&.0" "دستورات عمومی کاربر"
.\" -----------------------------------------------------------------
.\" * 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-format-rev \- قالب‌بندی شناسه‌های ارجاع و بازبینی گیت
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
(\fBEXPERIMENTAL\fR!) \fBgit\fR \fBformat\-rev\fR \fB\-\-stdin\-mode=\fR\fI<mode>\fR \fB\-\-format=\fR\fI<pretty>\fR [\fB\-\-\fR[\fBno\-\fR]\fBnotes=\fR\fI<ref>\fR] [\fB\-z\fR] [\fB\-\-\fR[\fBno\-\fR]\fBnull\-output\fR] [\fB\-\-\fR[\fBno\-\fR]\fBnull\-input\fR]
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
قالب‌بندی سفارشی بازبینی‌ها (revisions) از ورودی استاندارد\&.
.sp
این دستور آزمایشی است\&. رفتار آن ممکن است در آینده تغییر کند\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
\fB\-\-stdin\-mode=\fR\fI<mode>\fR
.RS 4
نحوه تفسیر داده‌های ورودی استاندارد:
.PP
\fBrevs\fR
.RS 4
هر خط یا رکورد (بخش
قالب ورودی و خروجی
را ببینید) به عنوان یک کامیت تفسیر می‌شود\&. از هر نوع عبارت بازبینی می‌توان استفاده کرد (ببینید
\fBgitrevisions\fR(7))\&.
برچسب‌های حاشیه‌نویسی‌شده پوسته‌گیری (peel) می‌شوند (ببینید
\fBgitglossary\fR(7))\&.
.sp
آرگومان
\fBrev\fR
نیز پذیرفته می‌شود\&.
.RE
.PP
\fBtext\fR
.RS 4
تمام نام‌های اشیای کامیتِ یافت‌شده در متن آزاد را قالب‌بندی می‌کند\&. این‌ها باید نام‌های کامل شیء باشند؛ به این معنی که نام‌های شانزده‌شانزدهی (هگزادسیمال) کوتاه تفسیر نخواهند شد\&.
.sp
هر آنچه که به عنوان یک نام شیء تجزیه شود اما به عنوان شیء کامیت شناخته نشود، دست‌نخورده باقی می‌ماند (عیناً چاپ می‌شود)\&.
.RE
.RE
.PP
\fB\-\-format=\fR\fI<pretty>\fR
.RS 4
رشته قالب‌بندی سفارشی (pretty format)\&.
.RE
.PP
\fB\-\-notes=\fR\fI<ref>\fR, \fB\-\-no\-notes\fR
.RS 4
مرجع یادداشت‌های سفارشی\&. یادداشت‌ها هنگام استفاده از اتوم
\fB%N\fR
نمایش داده می‌شوند\&. ببینید
\fBgit-notes\fR(1)\&.
.RE
.PP
\fB\-z\fR, \fB\-\-null\fR
.RS 4
استفاده از نویسه
\fINUL\fR
برای خاتمه دادن به هر دو ورودی و خروجی به جای خط جدید (newline)\&. این گزینه را نمی‌توان نفی کرد\&.
.sp
این گزینه زمانی مفید است که هم ورودی و هم خروجی بتوانند شامل خط جدید باشند یا ورودی این دستور نیز از نویسه
\fINUL\fR
برای پایان خطوط استفاده کند؛ بخش
قالب ورودی و خروجی
در زیر را ببینید\&.
.sp
حالت
\fB\-\-stdin\-mode=text\fR
می‌تواند از این گزینه در مواردی که نیاز به پردازش ورودی‌هایی مانند
\fBgit\fR
\fBlast\-modified\fR
\fB\-z\fR
دارد استفاده کند؛ بخش
مثال‌ها
در زیر را ببینید\&.
.RE
.PP
\fB\-\-null\-output\fR, \fB\-\-no\-null\-output\fR
.RS 4
استفاده از نویسه
\fINUL\fR
برای پایان دادن به خروجی به جای خط جدید\&. حالت پیش‌فرض
\fB\-\-no\-null\-output\fR
است\&.
.sp
این گزینه زمانی مفید است که خروجی ممکن است شامل خطوط جدید باشد، برای مثال اگر از اتوم
\fB%n\fR
(خط جدید) استفاده شود\&.
.RE
.PP
\fB\-\-null\-input\fR, \fB\-\-no\-null\-input\fR
.RS 4
استفاده از نویسه
\fINUL\fR
برای پایان دادن به ورودی به جای خط جدید\&. حالت پیش‌فرض
\fB\-\-no\-null\-input\fR
است\&.
.sp
این گزینه زمانی کاربرد دارد که عبارت‌های بازبینی در ورودی ممکن است حاوی خطوط جدید باشند\&.
.RE
.SH "قالب ورودی و خروجی (INPUT AND OUTPUT FORMAT)"
.sp
این دستور به‌طور پیش‌فرض از خط جدید برای پایان دادن به ورودی و خروجی استفاده می‌کند\&. برای استفاده از نویسه \fINUL\fR به عنوان پایان‌دهنده، گزینه‌های \fB\-z\fR، \fB\-\-null\-output\fR و \fB\-\-null\-input\fR را ببینید\&.
.sp
حالت \fB\-\-stdin\-mode=revs\fR یک کامیت قالب‌بندی‌شده را به همراه پایان‌دهنده در خروجی درج می‌کند\&. این را می‌توان یک \fIخط\fR یا یک \fIرکورد\fR نامید (در صورتی که واژه «خط» بیش از حد تداعی‌کننده پایان با خط جدید باشد)\&.
.sp
توجه داشته باشید که این بدان معناست که نویسه پایان‌دهنده (خط جدید یا \fINUL\fR) به عنوان یک \fIپایان‌دهنده (terminator)\fR عمل می‌کند، نه یک \fIجداکننده (separator)\fR\&. به عبارت دیگر، آخرین خط یا رکورد نیز با نویسه پایان‌دهنده خاتمه می‌یابد\&.
.sp
حالت \fB\-\-stdin\-mode=text\fR هر نام شیء را با کامیت قالب‌بندی‌شده جایگزین می‌کند؛ به عنوان مثال قالب \fB%s\fR یک نام شیء کامیت را بدون هیچ نویسه پایانی به \fI<subject>\fR تبدیل می‌کند\&. مانند این:
.sp
.if n \{\
.RS 4
.\}
.nf
Did we not fix this in "<subject>"?
.fi
.if n \{\
.RE
.\}
.sp
.sp
خواندن و نوشتن تعاملی با این دستور ایمن است زیرا هر رکورد بلافاصله فلاش و تخلیه (flush) می‌شود\&.
.SH "مثال‌ها (EXAMPLES)"
.sp
دستور \fBgit-last-modified\fR(1) کامیتی را نشان می‌دهد که هر فایل آخرین بار در آن تغییر یافته است\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ git last\-modified \-\- README\&.md Makefile
7798034171030be0909c56377a4e0e10e6d2df93        Makefile
c50fbb2dd225e7e82abba4380423ae105089f4d7        README\&.md
.fi
.if n \{\
.RE
.\}
.sp
.sp
می‌توانیم خروجی را به این دستور هدایت (pipe) کنیم تا نام شیء با نویسنده کامیت جایگزین شود\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ git last\-modified \-\- README\&.md Makefile |
    git format\-rev \-\-stdin\-mode=text \-\-format=%an
Junio C Hamano  Makefile
Todd Zullinger  README\&.md
.fi
.if n \{\
.RE
.\}
.sp
.sp
مثال دیگر \fIقالب‌بندی کامیت‌ها در پیام‌های کامیت\fR است\&. با فرض داشتن این پیام کامیت:
.sp
.if n \{\
.RS 4
.\}
.nf
Fix off\-by\-one error

Fix off\-by\-one error introduced in
e83c5163316f89bfbde7d9ab23ca2e25604af290\&.

We thought we fixed this in 5569bf9bbedd63a00780fc5c110e0cfab3aa97b9 but
that only covered 1/3 of the faulty cases\&.
.fi
.if n \{\
.RE
.\}
.sp
.sp
می‌توانیم کامیت‌ها را قالب‌بندی کرده و از par(1) برای بازآرایی متن استفاده کنیم، مثلاً در یک قلاب \fBcommit\-msg\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git config set hook\&.reference\-commits\&.event commit\-msg
$ git config set hook\&.reference\-commits\&.command reference\-commits
$ cat $(which reference\-commits)
#/bin/sh

msg="$1"
rewritten=$(mktemp)
git format\-rev \-\-stdin\-mode=text \-\-format=reference <"$msg" |
    par >"$rewritten"
mv "$rewritten" "$msg"
.fi
.if n \{\
.RE
.\}
.sp
.sp
که نتیجه‌ای شبیه به این تولید خواهد کرد:
.sp
.if n \{\
.RS 4
.\}
.nf
Fix off\-by\-one error

Fix off\-by\-one error introduced in e83c5163316 (Implement better memory
allocator, 2005\-04\-07)\&.

We thought we fixed this in 5569bf9bbed (Fix memory allocator,
2005\-06\-22) but that only covered 1/3 of the faulty cases\&.
.fi
.if n \{\
.RE
.\}
.sp
.SH "بحث و بررسی (DISCUSSION)"
.sp
این دستور به شما امکان می‌دهد هر تعداد بازبینی را با هر ترتیبی تنها با یک بار اجرای دستور قالب‌بندی کنید\&. مورد \fBgit-last-modified\fR(1) در بخش مثال‌های بالا را در نظر بگیرید:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
ممکن است صدها فایل وجود داشته باشد
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
کامیت‌ها ممکن است تکراری باشند؛ یعنی دو یا چند فایل آخرین بار در یک کامیت یکسان تغییر کرده باشند
.RE
.sp
دو دستور پرکاربرد که کامیت‌ها را به شکل سفارشی قالب‌بندی می‌کنند \fBgit-log\fR(1) و \fBgit-show\fR(1) هستند\&. مشخص شده است که آن‌ها برای مورد کاربرد بالا چندان مناسب نیستند\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
خروجی
\fBgit-last-modified\fR(1)
باید در چند مرحله پردازش شود، زیرا لازم است ستون اول را به صورت جداگانه تبدیل کرده و سپس نویسنده را به نام فایل پیوند دهید\&. اما این مشکل قابل حل است\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
می‌توانید هر کامیت را به
\fBgit\fR
\fBshow\fR
یا
\fBgit\fR
\fBlog\fR
\fB\-\-no\-walk\fR
\fB\-1\fR
بفرستید\&. اما این بدان معناست که باید برای هر خط یک فرآیند ایجاد کنید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
فرض کنید می‌خواهید تنها از یک فرآیند استفاده کنید و نه یک فرآیند به ازای هر خط\&. بنابراین مایلید تمام کامیت‌ها را به دستور بفرستید\&. اکنون با این مشکل روبرو می‌شوید که قبل از دریافت هرگونه خروجی، باید تمامی کامیت‌ها را به دستورها وارد کنید (این حالت در مورد حالت‌های
\fB\-\-stdin\fR
نیز صدق می‌کند)\&. به عبارت دیگر، نمی‌توانید روی هر خط پیمایش کرده، نویسنده را برای آن کامیت به دست آورید و نام نویسنده و نام فایل را در خروجی بنویسید\&. لازم است تمامی کامیت‌ها را تغذیه کرده، تمام خروجی را دریافت نمایید و خروجی را با نام فایل تطبیق دهید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
اما مشکل بعدی این است که دستورها داده‌های تکراری ورودی را حذف می‌کنند و هر کامیت را تنها یک بار در خروجی قرار می‌دهند\&. بنابراین نمی‌توانید ترتیب خروجی را با ترتیب ورودی مطابقت دهید، زیرا یک کامیت ممکن است در ورودی اصلی تکرار شده باشد\&.
.RE
.sp
به طور خلاصه، استفاده از این دو دستور در صورتی که برای هر خط از یک فرآیند استفاده کنید سرراست است\&. در صورتی که بخواهید تنها از یک فرآیند استفاده کنید کار بسیار بیشتری می‌طلبد، هرچند همچنان امکان‌پذیر است\&. در مقابل، این مشکل با استفاده از این دستور تنها با یک خط‌لوله ساده دیگر در پوسته حل می‌شود\&.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgit-name-rev\fR(1), \fBgit-log\fR(1)\&.
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)