| GIT-TAG(1) | Git Manual | GIT-TAG(1) |
نام (NAME)
git-tag - ایجاد، فهرست کردن، حذف یا اعتبارسنجی تگها
خلاصه دستور (SYNOPSIS)
git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
[(--trailer <token>[(=|:)<value>])...]
<tagname> [<commit> | <object>]
git tag -d <tagname>...
git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
[--points-at <object>] [--column[=<options>] | --no-column]
[--create-reflog] [--sort=<key>] [--format=<format>]
[--merged <commit>] [--no-merged <commit>] [<pattern>...]
git tag -v [--format=<format>] <tagname>...
توضیحات (DESCRIPTION)
یک مرجع تگ در refs/tags/ اضافه میکند، مگر اینکه -d/-l/-v برای حذف، فهرست کردن یا اعتبارسنجی تگها داده شده باشد.
مگر در حالتی که -f داده شده باشد، تگ نامبرده نباید از قبل وجود داشته باشد.
اگر یکی از گزینههای -a، -s یا -u <key-id> داده شود، این دستور یک شیء tag ایجاد کرده و نیازمند یک پیام تگ خواهد بود. مگر اینکه -m <msg> یا -F <file> داده شده باشد، یک ویرایشگر باز میشود تا کاربر پیام تگ را وارد کند.
اگر -m <msg> یا -F <file> یا --trailer <token>[=<value>] داده شود و گزینههای -a، -s و -u <key-id> غایب باشند، -a به صورت ضمنی در نظر گرفته میشود.
در غیر این صورت، یک مرجع تگ که مستقیماً به شیء دادهشده اشاره میکند (یعنی یک تگ سبک یا lightweight tag) ایجاد میشود.
هنگامی که از -s یا -u <key-id> استفاده شود، یک شیء تگ با امضای رمزنگاریشده ایجاد خواهد شد. پشتبند امضا (مانند GPG، X.509، SSH و غیره) توسط متغیر پیکربندی gpg.format کنترل میشود که مقدار پیشفرض آن OpenPGP است. هنگامی که از -u <key-id> استفاده نشود، هویت کامیتکننده برای کاربر جاری جهت یافتن کلید امضا استفاده میشود. متغیر پیکربندی gpg.program برای تعیین برنامه باینری سفارشی امضا استفاده میشود.
اشیاء تگ (ایجادشده با -a، -s یا -u) تگهای «حاشیهنویسیشده» (annotated) نامیده میشوند؛ آنها شامل تاریخ ایجاد، نام و ایمیل ایجادکننده تگ، پیام تگ و یک امضای رمزنگاریشده اختیاری هستند. در حالی که یک تگ «سبک» (lightweight) صرفاً یک نام برای یک شیء (معمولاً یک شیء کامیت) است.
تگهای حاشیهنویسیشده برای انتشار در نظر گرفته شدهاند در حالی که تگهای سبک برای برچسبگذاری موقت یا خصوصی اشیاء هستند. به همین دلیل، برخی دستورات گیت برای نامگذاری اشیاء (مانند git describe) به صورت پیشفرض تگهای سبک را نادیده میگیرند.
گزینهها (OPTIONS)
-a, --annotate
-s, --sign
--no-sign
-u <key-id>, --local-user=<key-id>
-f, --force
-d, --delete
-v, --verify
-n<num>
پیشفرض این است که هیچ خطی از حاشیهنویسی چاپ نشود. اگر هیچ عددی به -n داده نشود، فقط خط اول چاپ میشود. اگر تگ حاشیهنویسی نشده باشد، به جای آن پیام کامیت نمایش داده میشود.
-l, --list
اجرای git tag بدون آرگومان نیز تمام تگها را فهرست میکند. الگو یک نویسه عام (wildcard) پوسته است (یعنی با استفاده از fnmatch(3) تطبیق داده میشود). چندین الگو میتوانند مشخص شوند؛ اگر هر یک از آنها مطابقت داشته باشد، تگ نشان داده میشود.
این گزینه در صورت ارائه هر گزینه فهرستمانند دیگری مانند --contains به صورت ضمنی فعال میشود. برای جزئیات به مستندات مربوط به هر یک از آن گزینهها مراجعه کنید.
--sort=<key>
--color[=<when>]
-i, --ignore-case
--omit-empty
--column[=<options>], --no-column
این گزینه تنها هنگام فهرست کردن تگها بدون خطوط حاشیهنویسی کاربرد دارد.
--contains [<commit>]
--no-contains [<commit>]
--merged [<commit>]
--no-merged [<commit>]
--points-at [<object>]
-m <msg>, --message=<msg>
-F <file>, --file=<file>
--trailer <token>[(=|:)<value>]
-e, --edit
--cleanup=<mode>
--create-reflog
--format=<format>
<tagname>
<commit>, <object>
پیکربندی (CONFIGURATION)
بهطور پیشفرض، git tag در حالت امضا با پیشفرض (-s) از هویت کامیتکننده شما (به شکل Your Name <your@email.address>) برای یافتن کلید استفاده میکند. اگر میخواهید از کلید پیشفرض متفاوتی استفاده کنید، میتوانید آن را در پیکربندی مخزن به شکل زیر تعیین کنید:
[user]
signingKey = <key-id>
پشتبند امضا را میتوان با متغیر پیکربندی gpg.format انتخاب کرد که مقدار پیشفرض آن openpgp است. برای فهرستی از سایر قالبهای پشتیبانیشده به git-config(1) مراجعه کنید.
مسیر برنامهای که برای هر پشتبند امضا استفاده میشود را میتوان با متغیر پیکربندی gpg.<format>.program مشخص کرد. برای پشتبند openpgp، میتوان از gpg.program به عنوان مترادفی برای gpg.openpgp.program استفاده کرد. برای جزئیات به git-config(1) مراجعه کنید.
متغیر pager.tag تنها هنگام فهرست کردن تگها رعایت میشود، یعنی زمانی که -l استفاده شده یا ضمنی باشد. پیشفرض استفاده از صفحهبند (pager) است.
برای جزئیات بیشتر و سایر متغیرهای پیکربندی به git-config(1) مراجعه کنید.
بحث و بررسی (DISCUSSION)
درباره تگگذاری مجدد (On Re-tagging)
هنگامی که به اشتباه یک کامیت نادرست را تگ میکنید و میخواهید مجدداً تگ بگذارید، چه باید بکنید؟
اگر هرگز چیزی را به بیرون push نکردهاید، فقط آن را مجدداً تگ بزنید. از -f برای جایگزینی تگ قبلی استفاده کنید. و کار تمام است.
اما اگر تغییرات را push کردهاید (یا دیگران میتوانستند مستقیماً مخزن شما را بخوانند)، آنگاه دیگران قبلاً تگ قدیمی را دیدهاند. در این حالت میتوانید یکی از این دو کار را انجام دهید:
با این حال، گیت تگها را پشت سر کاربران تغییر نمیدهد (و نباید هم بدهد). بنابراین اگر کسی قبلاً تگ قدیمی را دریافت کرده باشد، اجرای git pull روی درخت شما نباید تگ قدیمی او را رونویسی کند.
اگر کسی یک تگ انتشار از شما دریافت کرده است، نمیتوانید صرفاً با بهروزرسانی تگ خودتان، تگ او را تغییر دهید. این یک مسئله امنیتی بزرگ است، زیرا افراد باید بتوانند به نامهای تگ خود اطمینان کنند. اگر واقعاً میخواهید آن کار غیرمعقول را انجام دهید، باید صادقانه به آن اعتراف کنید و به افراد اطلاع دهید که دچار اشتباه شدهاید. میتوانید این کار را با یک اعلان عمومی به این صورت انجام دهید:
Ok, I messed up, and I pushed out an earlier version tagged as X. I
then fixed something, and retagged the *fixed* tree as X again.
If you got the wrong tag, and want the new one, please delete
the old one and fetch the new one by doing:
git tag -d X
git fetch origin tag X
to get my updated tag.
You can test which tag you have by doing
git rev-parse X
which should return 0123456789abcdef.. if you have the new version.
Sorry for the inconvenience.
آیا این کمی پیچیده به نظر میرسد؟ باید هم باشد. هیچ راهی وجود ندارد که "درست کردن" خودکار آن کار صحیحی باشد. افراد باید بدانند که ممکن است تگهایشان تغییر کرده باشد.
درباره دنبال کردن خودکار (On Automatic following)
اگر در حال دنبال کردن درخت شخص دیگری هستید، به احتمال زیاد از شاخههای ردیابی از راه دور (مانند refs/remotes/origin/master) استفاده میکنید. شما معمولاً تگهای طرف مقابل را میخواهید.
از سوی دیگر، اگر به این دلیل fetch میکنید که میخواهید یک ادغام تکباره از شخص دیگری انجام دهید، معمولاً نمیخواهید تگها را از آنجا دریافت کنید. این موضوع بیشتر برای افراد نزدیک به بالاترین ردههای پروژه اتفاق میافتد اما محدود به آنها نیست. کاربران معمولی هنگام pull کردن از یکدیگر لزوماً نمیخواهند تگهای نقاط لنگرگاه خصوصی طرف مقابل را دریافت کنند.
اغلب، پیامهای "لطفاً pull کنید" در فهرست پستی صرفاً دو بخش اطلاعاتی را ارائه میدهند: یک آدرس اینترنتی مخزن و یک نام شاخه؛ این قالب به گونهای طراحی شده که به راحتی در انتهای یک خط فرمان git fetch رونوشت و جایگذاری شود:
Linus, please pull from
git://git..../proj.git master
to get the following updates...
تبدیل میشود به:
$ git pull git://git..../proj.git master
در چنین شرایطی، شما مایل نیستید تگهای شخص دیگر را به طور خودکار دنبال کنید.
یکی از جنبههای مهم گیت ماهیت توزیعشده آن است، که اساساً بدان معناست که هیچ "بالادست" یا "پاییندست" ذاتی در سیستم وجود ندارد. در ظاهر، مثال بالا ممکن است نشان دهد که فضای نام تگها متعلق به سطوح بالای سلسلهمراتب است و تگها فقط به سمت پایین جریان دارند، اما واقعیت چنین نیست. این صرفاً نشان میدهد که الگوی استفاده مشخص میکند چه کسانی به تگهای چه کسانی علاقهمندند.
یک pull تکباره نشانهای از این است که تاریخچه کامیت اکنون در حال عبور از مرز میان یک گروه از افراد (مثلاً "افرادی که بیشتر به بخش شبکه هسته علاقهمندند") که ممکن است مجموعه تگهای خود را داشته باشند (مثلاً "این سومین نامزد انتشار از گروه شبکه است که برای استفاده عمومی با انتشار 2.6.21 پیشنهاد میشود") به گروه دیگری از افراد (مثلاً "افرادی که بهبودهای زیرسیستمهای مختلف را ادغام میکنند") است. گروه دوم معمولاً به تگهای تفصیلی که به صورت داخلی در گروه اول استفاده میشوند علاقهای ندارند (معنای "داخلی" همین است). به همین دلیل مطلوب است که در این حالت تگها به صورت خودکار دنبال نشوند.
ممکن است افراد بخش شبکه بخواهند تگهای داخلی گروه خود را مبادله کنند، اما در آن گردش کار احتمالاً از طریق شاخههای ردیابی از راه دور پیشرفت یکدیگر را دنبال میکنند. در این حالت نیز منطق دنبال کردن خودکار چنین تگهایی بسیار سودمند است.
درباره تاریخگذاری گذشتهنگر تگها (On Backdating Tags)
اگر تغییراتی را از یک سیستم کنترل نسخه دیگر وارد کردهاید و میخواهید تگهایی برای انتشارهای اصلی کار خود اضافه کنید، تعیین تاریخی برای گنجاندن در شیء تگ بسیار سودمند است؛ این داده در شیء تگ، برای مثال، بر ترتیب نمایش تگها در رابط وبگیت (gitweb) تأثیر میگذارد.
برای تعیین تاریخ مورد استفاده در اشیاء تگ آینده، متغیر محیطی GIT_COMMITTER_DATE را تنظیم کنید (به بحث بعدی پیرامون مقادیر ممکن مراجعه فرمایید؛ رایجترین قالب "YYYY-MM-DD HH:MM" است).
برای مثال:
$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
قالبهای تاریخ (DATE FORMATS)
متغیرهای محیطی GIT_AUTHOR_DATE و GIT_COMMITTER_DATE از قالبهای تاریخ زیر پشتیبانی میکنند:
قالب داخلی گیت (Git internal format)
ایمنتر است که پیش از <unix-timestamp> علامت @ قرار دهید (مثلاً @0 +0000)، که گیت را وادار میکند آن را به عنوان یک برچسب زمانی خام تفسیر کند. این کار برای مقادیر کمتر از ۱۰۰٬۰۰۰٬۰۰۰ (که کمتر از ۹ رقم دارند) الزامی است تا از اشتباه گرفته شدن با سایر قالبهای تاریخ مانند YYYYMMDD جلوگیری شود.
استاندارد RFC 2822
استاندارد ISO 8601
یادداشت
علاوه بر این، بخش تاریخ در قالبهای زیر نیز پذیرفته میشود: YYYY.MM.DD، MM/DD/YYYY و DD.MM.YYYY.
فایلها (FILES)
$GIT_DIR/TAG_EDITMSG
پیکربندی (CONFIGURATION)
تمام موارد زیر این خط در این بخش به صورت گزینششده از مستندات git-config(1) گنجانده شده است. محتوا معادل همان چیزی است که در آنجا یافت میشود:
tag.forceSignAnnotated
tag.sort
tag.gpgSign
نکات (NOTES)
هنگام ترکیب چند فیلتر --contains و --no-contains، تنها مراجعی نشان داده میشوند که حداقل شامل یکی از کامیتهای --contains بوده و شامل هیچیک از کامیتهای --no-contains نباشند.
هنگام ترکیب چند فیلتر --merged و --no-merged، تنها مراجعی نشان داده میشوند که از حداقل یکی از کامیتهای --merged قابل دسترس بوده و از هیچیک از کامیتهای --no-merged قابل دسترس نباشند.
همچنین ببینید (SEE ALSO)
گیت (GIT)
بخشی از مجموعه git(1)
| 2026-06-29 | Git 2.55.0 |