نام (NAME)

git-describe - نام‌گذاری کامیت بر اساس نزدیک‌ترین تگ قابل دسترسی

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

git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
git describe <blob>

توضیحات (DESCRIPTION)

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

به‌طور پیش‌فرض (بدون گزینه‌های --all یا --tags)، دستور git describe تنها تگ‌های یادداشت‌دار (annotated tags) را نمایش می‌دهد. برای اطلاعات بیشتر درباره ایجاد تگ‌های یادداشت‌دار، گزینه‌های -a و -s در git-tag(1) را ببینید.

اگر شیء داده‌شده به یک blob اشاره داشته باشد، به صورت <commit-ish>:<path> توصیف می‌شود؛ به گونه‌ای که blob را می‌توان در مسیر <path> در <commit-ish> پیدا کرد، که خود نشان‌دهنده نخستین کامیتی است که این blob در یک پیمایش معکوس بازنگری‌ها از HEAD در آن رخ می‌دهد.

گزینه‌ها (OPTIONS)

<commit-ish>...

--dirty[=<mark>], --broken[=<mark>]

--all

--tags

--contains

--abbrev=<n>

--candidates=<n>

--exact-match

--debug

--long

--match <pattern>

--exclude <pattern>

--always

--first-parent

مثال‌ها (EXAMPLES)

با چیزی شبیه درخت کاری فعلی git.git، خروجی به این صورت خواهد بود:

[torvalds@g5 git]$ git describe parent
v1.0.4-14-g2414721

به این معنی که سر (head) فعلی شاخه «parent» بر پایه v1.0.4 است، اما از آنجا که چند کامیت بر روی آن قرار دارد، دستور describe تعداد کامیت‌های اضافی («14») و یک نام شیء اختصاری برای خود کامیت («2414721») را در انتهای آن افزوده است.

تعداد کامیت‌های اضافی برابر با تعداد کامیت‌هایی است که با دستور git log v1.0.4..parent نمایش داده می‌شوند. پسوند هش برابر با «-g» به‌علاوه یک اختصار بدون ابهام برای کامیت نوک (tip) شاخه parent است (که 2414721b194453f058079d897d13c4e377f92dc6 بود). طول اختصار با رشد مخزن افزایش می‌یابد؛ با استفاده از تعداد تقریبی اشیاء در مخزن و کمی محاسبات ریاضی پیرامون مسئله پارادوکس زادروز (birthday paradox)، و حداقل پیش‌فرض آن ۷ است. پیشوند «g» مخفف «git» است و به این منظور استفاده می‌شود که امکان توصیف نسخه یک نرم‌افزار بر اساس سیستم مدیریت کنترل نسخه (SCM) که نرم‌افزار با آن مدیریت می‌شود وجود داشته باشد. این قابلیت در محیطی که افراد ممکن است از SCMهای مختلفی استفاده کنند بسیار مفید است.

اجرای دستور git describe روی یک نام تگ، تنها نام همان تگ را نمایش می‌دهد:

[torvalds@g5 git]$ git describe v1.0.4
v1.0.4

با گزینه --all، این دستور می‌تواند از سر شاخه‌ها به عنوان مرجع استفاده کند، بنابراین خروجی مسیر مرجع را نیز نمایش می‌دهد:

[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b

[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b

با تنظیم --abbrev روی ۰، این دستور می‌تواند برای یافتن نزدیک‌ترین نام تگ بدون هیچ‌گونه پسوندی استفاده شود:

[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

توجه داشته باشید که پسوندی که در صورت تایپ این دستورات در حال حاضر دریافت می‌کنید ممکن است طولانی‌تر از آنچه لینوس در بالا هنگام اجرای این دستورات مشاهده کرد باشد، زیرا مخزن گیت شما ممکن است کامیت‌های جدیدی داشته باشد که نام شیء آن‌ها با 975b آغاز شده و در آن زمان وجود نداشته‌اند، و پسوند «-g975b» به تنهایی ممکن است برای رفع ابهام این کامیت‌ها کافی نباشد.

راهبرد جستجو (SEARCH STRATEGY)

برای هر commit-ish ارائه‌شده، git describe ابتدا به دنبال تگی می‌گردد که دقیقاً آن کامیت را تگ کرده باشد. تگ‌های یادداشت‌دار همیشه بر تگ‌های سبک‌وزن اولویت دارند و تگ‌هایی با تاریخ جدیدتر همیشه بر تگ‌هایی با تاریخ قدیمی‌تر ترجیح داده می‌شوند. اگر یک تطابق دقیق پیدا شود، نام آن خروجی داده شده و جستجو متوقف می‌شود.

اگر تطابق دقیقی یافت نشد، git describe تاریخچه کامیت‌ها را به عقب پیمایش می‌کند تا یک کامیت نیا (اجدادی) را که تگ شده است پیدا کند. تگ کامیت نیا به همراه شکل اختصاری SHA-1 کامیت ورودی در خروجی نمایش داده می‌شود. اگر --first-parent مشخص شده باشد، پیمایش تنها نخستین والد هر کامیت را در نظر خواهد گرفت.

اگر در طول پیمایش چندین تگ پیدا شود، تگی انتخاب و خروجی داده می‌شود که کمترین اختلاف تعداد کامیت را با commit-ish ورودی داشته باشد. در اینجا منظور از کمترین اختلاف تعداد کامیت، کمترین تعداد کامیت ممکن است که توسط git log tag..input نمایش داده می‌شود.

اشکالات (BUGS)

اشیاء درخت (Tree objects) و همچنین اشیاء تگی که به کامیت‌ها اشاره ندارند را نمی‌توان توصیف کرد. هنگام توصیف blobها، تگ‌های سبک‌وزنی که به blobها اشاره می‌کنند نادیده گرفته می‌شوند، اما همچنان blob به عنوان <commit-ish>:<path> توصیف می‌شود علیرغم اینکه ممکن است تگ سبک‌وزن مناسب‌تر باشد.

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

git-tag(1)

گیت (GIT)

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