'\" t
.\"     Title: git-describe
.\"    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\-DESCRIBE" "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-describe \- نام‌گذاری کامیت بر اساس نزدیک‌ترین تگ قابل دسترسی
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fBgit\fR \fBdescribe\fR [\fB\-\-all\fR] [\fB\-\-tags\fR] [\fB\-\-contains\fR] [\fB\-\-abbrev=\fR\fI<n>\fR] [\fI<commit\-ish>\fR\&...]
\fBgit\fR \fBdescribe\fR [\fB\-\-all\fR] [\fB\-\-tags\fR] [\fB\-\-contains\fR] [\fB\-\-abbrev=\fR\fI<n>\fR] \fB\-\-dirty\fR[\fB=\fR\fI<mark>\fR]
\fBgit\fR \fBdescribe\fR \fI<blob>\fR
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
این دستور جدیدترین تگی را که از یک کامیت قابل دسترسی است پیدا می‌کند\&. اگر تگ به خود کامیت اشاره کند، فقط نام تگ نمایش داده می‌شود\&. در غیر این صورت، تعداد کامیت‌های اضافی پس از شیء تگ‌شده و نام اختصاری شیء مربوط به جدیدترین کامیت را به انتهای نام تگ اضافه (پسوند) می‌کند\&. نتیجه کار یک نام شیء «خوانا برای انسان» است که می‌تواند برای شناسایی کامیت به سایر دستورات گیت نیز استفاده شود\&.
.sp
به‌طور پیش‌فرض (بدون گزینه‌های \fB\-\-all\fR یا \fB\-\-tags\fR)، دستور \fBgit\fR \fBdescribe\fR تنها تگ‌های یادداشت‌دار (annotated tags) را نمایش می‌دهد\&. برای اطلاعات بیشتر درباره ایجاد تگ‌های یادداشت‌دار، گزینه‌های \fB\-a\fR و \fB\-s\fR در \fBgit-tag\fR(1) را ببینید\&.
.sp
اگر شیء داده‌شده به یک blob اشاره داشته باشد، به صورت \fI<commit\-ish>\fR\fB:\fR\fI<path>\fR توصیف می‌شود؛ به گونه‌ای که blob را می‌توان در مسیر \fI<path>\fR در \fI<commit\-ish>\fR پیدا کرد، که خود نشان‌دهنده نخستین کامیتی است که این blob در یک پیمایش معکوس بازنگری‌ها از \fBHEAD\fR در آن رخ می‌دهد\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
\fI<commit\-ish>\fR\&.\&.\&.
.RS 4
نام‌های شیء شبیه کامیت (commit\-ish) برای توصیف\&. در صورت حذف شدن، به طور پیش‌فرض روی
\fBHEAD\fR
قرار می‌گیرد\&.
.RE
.PP
\fB\-\-dirty\fR[\fB=\fR\fI<mark>\fR], \fB\-\-broken\fR[\fB=\fR\fI<mark>\fR]
.RS 4
وضعیت درخت کاری را توصیف می‌کند\&. هنگامی که درخت کاری با
\fBHEAD\fR
مطابقت داشته باشد، خروجی مشابه اجرای
\fBgit\fR
\fBdescribe\fR
\fBHEAD\fR
خواهد بود\&. اگر درخت کاری دارای تغییرات محلی باشد، پسوند
\fB\-dirty\fR
به آن اضافه می‌شود\&. اگر مخزن خراب (فاسد) شده باشد و گیت نتواند تشخیص دهد که آیا تغییر محلی وجود دارد یا خیر، گیت خطا می‌دهد، مگر اینکه
\fB\-\-broken\fR
داده شده باشد، که در این صورت به جای آن پسوند
\fB\-broken\fR
را اضافه می‌کند\&.
.RE
.PP
\fB\-\-all\fR
.RS 4
به جای استفاده تنها از تگ‌های یادداشت‌دار، از هر ارجاع (ref) موجود در فضای نام
\fBrefs/\fR
استفاده می‌کند\&. این گزینه تطابق با هر شاخه شناخته‌شده، شاخه ردگیری دوردست یا تگ سبک‌وزن (lightweight) را امکان‌پذیر می‌سازد\&.
.RE
.PP
\fB\-\-tags\fR
.RS 4
به جای استفاده تنها از تگ‌های یادداشت‌دار، از هر تگ موجود در فضای نام
\fBrefs/tags\fR
استفاده می‌کند\&. این گزینه تطابق با تگ‌های سبک‌وزن (بدون یادداشت) را امکان‌پذیر می‌سازد\&.
.RE
.PP
\fB\-\-contains\fR
.RS 4
به جای یافتن تگی که پیش از کامیت آمده است، تگی را پیدا می‌کند که پس از کامیت آمده و بنابراین آن را در بر دارد\&. به طور خودکار شامل گزینه
\fB\-\-tags\fR
می‌شود\&.
.RE
.PP
\fB\-\-abbrev=\fR\fI<n>\fR
.RS 4
به جای استفاده از تعداد پیش‌فرض ارقام هگزادسیمال نام شیء اختصاری (که بسته به تعداد اشیاء موجود در مخزن متغیر است و به طور پیش‌فرض ۷ است)، از
\fI<n>\fR
رقم، یا به تعداد ارقامی که برای ایجاد یک نام شیء یکتا لازم است استفاده می‌کند\&. مقدار
\fI<n>\fR
برابر با ۰ قالب طولانی را غیرفعال کرده و تنها نزدیک‌ترین تگ را نمایش می‌دهد\&.
.RE
.PP
\fB\-\-candidates=\fR\fI<n>\fR
.RS 4
به جای در نظر گرفتن تنها ۱۰ تگ اخیر به عنوان کاندیدای توصیف کامیت ورودی، تا
\fI<n>\fR
کاندیدا را در نظر می‌گیرد\&. افزایش
\fI<n>\fR
به بیش از ۱۰ اندکی بیشتر زمان می‌برد اما ممکن است نتیجه دقیق‌تری تولید کند\&. مقدار
\fI<n>\fR
برابر با ۰ باعث می‌شود تنها تطابق‌های دقیق خروجی داده شوند\&.
.RE
.PP
\fB\-\-exact\-match\fR
.RS 4
تنها تطابق‌های دقیق را خروجی می‌دهد (تگی که مستقیماً به کامیت ارائه‌شده ارجاع می‌دهد)\&. این گزینه مترادف
\fB\-\-candidates=0\fR
است\&.
.RE
.PP
\fB\-\-debug\fR
.RS 4
اطلاعات مربوط به راهبرد جستجوی به‌کار گرفته‌شده را با جزئیات کامل در خروجی خطای استاندارد نمایش می‌دهد\&. نام تگ همچنان در خروجی استاندارد چاپ خواهد شد\&.
.RE
.PP
\fB\-\-long\fR
.RS 4
همیشه قالب طولانی (نام تگ، تعداد کامیت‌ها و نام اختصاری کامیت) را حتی در صورتی که با یک تگ مطابقت داشته باشد خروجی می‌دهد\&. این گزینه زمانی مفید است که می‌خواهید بخش‌هایی از نام شیء کامیت را در خروجی «describe» مشاهده کنید، حتی زمانی که کامیت مورد نظر تصادفاً یک نسخه تگ‌شده باشد\&. به جای چاپ صرف نام تگ، چنین کامیتی را به صورت v1\&.2\-0\-gdeadbee (کامیت صفرم پس از تگ v1\&.2 که به شیء deadbee\&...\&. اشاره دارد) توصیف می‌کند\&.
.RE
.PP
\fB\-\-match\fR \fI<pattern>\fR
.RS 4
تنها تگ‌هایی را در نظر می‌گیرد که با الگوی داده‌شده
\fBglob\fR(7)
مطابقت داشته باشند، به استثنای پیشوند «refs/tags/»\&. اگر همراه با
\fB\-\-all\fR
استفاده شود، شاخه‌های محلی و مراجع ردگیری دوردست مطابق با الگو را نیز در نظر می‌گیرد، به ترتیب بدون پیشوندهای «refs/heads/» و «refs/remotes/»؛ مراجع از انواع دیگر هرگز در نظر گرفته نمی‌شوند\&. در صورت ارائه چندباره، فهرستی از الگوها تجمیع می‌شود و تگ‌های مطابق با هر یک از الگوها در نظر گرفته خواهند شد\&. برای پاک کردن و بازنشانی فهرست الگوها از
\fB\-\-no\-match\fR
استفاده کنید\&.
.RE
.PP
\fB\-\-exclude\fR \fI<pattern>\fR
.RS 4
تگ‌های مطابق با الگوی داده‌شده
\fBglob\fR(7)
را در نظر نمی‌گیرد، به استثنای پیشوند «refs/tags/»\&. اگر همراه با
\fB\-\-all\fR
استفاده شود، شاخه‌های محلی و ارجاعات ردگیری دوردست مطابق با الگو را نیز در نظر نمی‌گیرد، به ترتیب بدون پیشوندهای «\fBrefs/heads/\fR» و «\fBrefs/remotes/\fR»؛ مراجع از انواع دیگر هرگز در نظر گرفته نمی‌شوند\&. در صورت ارائه چندباره، فهرستی از الگوها تجمیع شده و تگ‌های مطابق با هر یک از الگوها مستثنی می‌شوند\&. هنگام ترکیب با
\fB\-\-match\fR،
یک تگ زمانی در نظر گرفته می‌شود که حداقل با یکی از الگوهای
\fB\-\-match\fR
مطابقت داشته باشد و با هیچ‌یک از الگوهای
\fB\-\-exclude\fR
مطابقت نداشته باشد\&. برای پاک کردن و بازنشانی فهرست الگوها از
\fB\-\-no\-exclude\fR
استفاده کنید\&.
.RE
.PP
\fB\-\-always\fR
.RS 4
نمایش شیء کامیت اختصاری یکتا به عنوان راه‌حل پشتیبان (fallback)\&.
.RE
.PP
\fB\-\-first\-parent\fR
.RS 4
هنگام مواجهه با یک کامیت ادغام (merge commit)، تنها نخستین کامیت والد را دنبال می‌کند\&. این گزینه زمانی مفید است که مایل نیستید تگ‌های شاخه‌های ادغام‌شده در تاریخچه کامیت هدف مطابقت داده شوند\&.
.RE
.SH "مثال‌ها (EXAMPLES)"
.sp
با چیزی شبیه درخت کاری فعلی git\&.git، خروجی به این صورت خواهد بود:
.sp
.if n \{\
.RS 4
.\}
.nf
[torvalds@g5 git]$ git describe parent
v1\&.0\&.4\-14\-g2414721
.fi
.if n \{\
.RE
.\}
.sp
به این معنی که سر (head) فعلی شاخه «parent» بر پایه v1\&.0\&.4 است، اما از آنجا که چند کامیت بر روی آن قرار دارد، دستور describe تعداد کامیت‌های اضافی («14») و یک نام شیء اختصاری برای خود کامیت («2414721») را در انتهای آن افزوده است\&.
.sp
تعداد کامیت‌های اضافی برابر با تعداد کامیت‌هایی است که با دستور \fBgit\fR \fBlog\fR \fBv1\&.0\&.4\fR\fB\&.\&.\fR\fBparent\fR نمایش داده می‌شوند\&. پسوند هش برابر با «\fB\-g\fR» به‌علاوه یک اختصار بدون ابهام برای کامیت نوک (tip) شاخه parent است (که \fB2414721b194453f058079d897d13c4e377f92dc6\fR بود)\&. طول اختصار با رشد مخزن افزایش می‌یابد؛ با استفاده از تعداد تقریبی اشیاء در مخزن و کمی محاسبات ریاضی پیرامون مسئله پارادوکس زادروز (birthday paradox)، و حداقل پیش‌فرض آن ۷ است\&. پیشوند «g» مخفف «git» است و به این منظور استفاده می‌شود که امکان توصیف نسخه یک نرم‌افزار بر اساس سیستم مدیریت کنترل نسخه (SCM) که نرم‌افزار با آن مدیریت می‌شود وجود داشته باشد\&. این قابلیت در محیطی که افراد ممکن است از SCMهای مختلفی استفاده کنند بسیار مفید است\&.
.sp
اجرای دستور \fBgit\fR \fBdescribe\fR روی یک نام تگ، تنها نام همان تگ را نمایش می‌دهد:
.sp
.if n \{\
.RS 4
.\}
.nf
[torvalds@g5 git]$ git describe v1\&.0\&.4
v1\&.0\&.4
.fi
.if n \{\
.RE
.\}
.sp
با گزینه \fB\-\-all\fR، این دستور می‌تواند از سر شاخه‌ها به عنوان مرجع استفاده کند، بنابراین خروجی مسیر مرجع را نیز نمایش می‌دهد:
.sp
.if n \{\
.RS 4
.\}
.nf
[torvalds@g5 git]$ git describe \-\-all \-\-abbrev=4 v1\&.0\&.5^2
tags/v1\&.0\&.0\-21\-g975b
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[torvalds@g5 git]$ git describe \-\-all \-\-abbrev=4 HEAD^
heads/lt/describe\-7\-g975b
.fi
.if n \{\
.RE
.\}
.sp
با تنظیم \fB\-\-abbrev\fR روی ۰، این دستور می‌تواند برای یافتن نزدیک‌ترین نام تگ بدون هیچ‌گونه پسوندی استفاده شود:
.sp
.if n \{\
.RS 4
.\}
.nf
[torvalds@g5 git]$ git describe \-\-abbrev=0 v1\&.0\&.5^2
tags/v1\&.0\&.0
.fi
.if n \{\
.RE
.\}
.sp
توجه داشته باشید که پسوندی که در صورت تایپ این دستورات در حال حاضر دریافت می‌کنید ممکن است طولانی‌تر از آنچه لینوس در بالا هنگام اجرای این دستورات مشاهده کرد باشد، زیرا مخزن گیت شما ممکن است کامیت‌های جدیدی داشته باشد که نام شیء آن‌ها با 975b آغاز شده و در آن زمان وجود نداشته‌اند، و پسوند «\-g975b» به تنهایی ممکن است برای رفع ابهام این کامیت‌ها کافی نباشد\&.
.SH "راهبرد جستجو (SEARCH STRATEGY)"
.sp
برای هر commit\-ish ارائه‌شده، \fBgit\fR \fBdescribe\fR ابتدا به دنبال تگی می‌گردد که دقیقاً آن کامیت را تگ کرده باشد\&. تگ‌های یادداشت‌دار همیشه بر تگ‌های سبک‌وزن اولویت دارند و تگ‌هایی با تاریخ جدیدتر همیشه بر تگ‌هایی با تاریخ قدیمی‌تر ترجیح داده می‌شوند\&. اگر یک تطابق دقیق پیدا شود، نام آن خروجی داده شده و جستجو متوقف می‌شود\&.
.sp
اگر تطابق دقیقی یافت نشد، \fBgit\fR \fBdescribe\fR تاریخچه کامیت‌ها را به عقب پیمایش می‌کند تا یک کامیت نیا (اجدادی) را که تگ شده است پیدا کند\&. تگ کامیت نیا به همراه شکل اختصاری SHA\-1 کامیت ورودی در خروجی نمایش داده می‌شود\&. اگر \fB\-\-first\-parent\fR مشخص شده باشد، پیمایش تنها نخستین والد هر کامیت را در نظر خواهد گرفت\&.
.sp
اگر در طول پیمایش چندین تگ پیدا شود، تگی انتخاب و خروجی داده می‌شود که کمترین اختلاف تعداد کامیت را با commit\-ish ورودی داشته باشد\&. در اینجا منظور از کمترین اختلاف تعداد کامیت، کمترین تعداد کامیت ممکن است که توسط \fBgit\fR \fBlog\fR \fBtag\fR\fB\&.\&.\fR\fBinput\fR نمایش داده می‌شود\&.
.SH "اشکالات (BUGS)"
.sp
اشیاء درخت (Tree objects) و همچنین اشیاء تگی که به کامیت‌ها اشاره ندارند را نمی‌توان توصیف کرد\&. هنگام توصیف blobها، تگ‌های سبک‌وزنی که به blobها اشاره می‌کنند نادیده گرفته می‌شوند، اما همچنان blob به عنوان \fI<commit\-ish>\fR\fB:\fR\fI<path>\fR توصیف می‌شود علیرغم اینکه ممکن است تگ سبک‌وزن مناسب‌تر باشد\&.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgit-tag\fR(1)
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)