SYNOPSIS

git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
        <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

タグを削除、一覧表示、検証するために -d/-l/-v が指定されていない限り、 refs/tags/ にタグ参照を追加します。

-f が指定されていない限り、名前付きタグはまだ存在してはいけません。

-a, -s, -u <key-id> のいずれかが渡されると、 コマンドは「タグ」オブジェクトを作成し、 タグ・メッセージを要求します。 -m<msg> または -F<file> が指定されていない限り、 ユーザーがタグ・メッセージを入力するためのエディターを起動します。

-m<msg> または -F<file> が指定され、 -a と -s と -u <key-id> がない場合、 -a が暗黙に指定されます。

それ以外の場合は、指定されたオブジェクトを直接指すタグ参照(つまり、軽量タグ)が作成されます。

-s または -u<key-id> を使用すると、GnuPG署名付きタグオブジェクトが作成されます。 -u <key-id> が使用されていない場合、現在のユーザーのコミッターIDを使用して、署名用のGnuPGキーが検索されます。 構成変数 gpg.program は、カスタムGnuPGバイナリを指定するために使用されます。

(-a または -s または -u で作成した)タグオブジェクトは「注釈付き」タグ(annotated tags)と呼ばれます。 これらには、作成日や、タグ付け者(tagger)の名前と電子メールアドレスや、タグ付けメッセージや、オプションのGnuPG署名が含まれています。 一方、「軽量」タグ(lightweight tag)は単にオブジェクト(通常はコミットオブジェクト)の名前が含まれています。

注釈付きタグはリリース用であり、軽量タグはプライベートまたは一時オブジェクトラベル用です。 このため、オブジェクトに名前を付けるための一部のgitコマンド( git describe など)は、デフォルトでは軽量タグを無視します。

OPTIONS

-a
--annotate

署名されていない注釈付きのタグオブジェクトを作成します

-s
--sign

デフォルトの電子メールアドレスのキーを使用して、GPG署名付きタグを作成します。 タグGPG署名のデフォルトの動作は、存在する場合は tag.gpgSign 構成変数によって制御され、存在しない場合は無効になります。 git-config(1) を参照してください。

--no-sign

すべてのタグに強制的に署名するように設定されている tag.gpgSign 構成変数をオーバーライドします。

-u <key-id>
--local-user=<key-id>

指定されたキーを使用して、GPG署名付きタグを作成します。

-f
--force

既存のタグを、(失敗して終了するのではなく、)指定された名前に置き換えます

-d
--delete

指定された名前の既存のタグを削除します。

-v
--verify

指定されたタグ名のGPG署名を検証(verify)します。

-n<num>

<num> は、-l を使用したときに、注釈を何行出力するか指定します。 --list の指定を含んでいます。

デフォルトでは、注釈行は印刷されません。 -n に番号が指定されていない場合、最初の行のみが出力されます。 タグに注釈が付けられていない場合は、代わりにコミットメッセージが表示されます。

-l
--list

タグを一覧表示します。オプションで <pattern>... を指定すると、例えば git tag --list 'v-*' のように、パターンにマッチするタグのみをリストアップします。

引数なしで git tag を実行した時も、すべてのタグが一覧表示されます。 パターンはシェルワイルドカードです(つまり、fnmatch(3) を使用してマッチします)。 複数のパターンを指定できます。 それらのいずれかがマッチする場合、タグが表示されます。

このオプションは、 --contains などの他のリストっぽいオプション(list-like option)が提供されている場合に暗黙的に提供されます。 詳細については、これらの各オプションのドキュメントを参照してください。

--sort=<key>

指定されたキーに基づいて並べ替えます。 接頭辞 - を使用して、値の降順で並べ替えます。 -sort=<key> オプションは複数回使用できます。その場合、最後のキーが主キーになります。 "version:refname" または "v:refname" もサポートします(タグ名はバージョンとして扱われます)。 "version:refname" のソート順は、 versionsort.suffix 構成変数の影響も受ける可能性があります。 サポートされているキーは、git for-each-ref のキーと同じです。 並べ替え順序は、デフォルトで、 tag.sort 変数が存在する場合は設定された値になり、存在しない場合は辞書式順序(lexicographic order)になります。 git-config(1) を参照してください。

--color[=<when>]

--format オプションで指定された色を尊重します。 <when> フィールドは always, never, auto のいずれかでなければなりません(<when> がない場合は、 always が指定されたかのように振る舞います)。

-i
--ignore-case

タグの並べ替えとフィルタリングでは英大文字小文字は区別されません(case insensitive)。

--omit-empty

書式が空文字列に展開される場合、書式化 ref (formatted refs)の後ろに改行を出力しないでください。

--column[=<options>]
--no-column

タグリストを列(columns)に表示します。 オプションの構文については、構成変数 column.tag を参照してください。 オプションのない --column と --no-column は、それぞれ always と never と同等です。

このオプションは、注釈行(annotation lines)のないタグをリストする場合にのみ適用できます。

--contains [<commit>]

指定されたコミットを含むタグのみをリストします(指定されていない場合はHEAD)。 --list の指定を含んでいます。

--no-contains [<commit>]

指定されたコミットを含まないタグのみをリストします(指定されていない場合はHEAD)。 --list の指定を含んでいます。

--merged [<commit>]

指定されたコミットから、コミットに到達できるタグのみをリストします(指定されていない場合は HEAD)。

--no-merged [<commit>]

指定されたコミットから、コミットに到達できないタグのみをリストします(指定されていない場合は HEAD)。

--points-at <object>

指定されたオブジェクトのタグのみを一覧表示します(指定されていない場合はHEAD)。 --list の指定を含んでいます。

-m <msg>
--message=<msg>

(プロンプトを表示する代わりに)指定されたタグメッセージを使用します。 複数の -m オプションが指定されている場合、それらの値は個別の段落として連結されます。 -a と -s と -u <key-id> のいずれも指定されていない場合は、 -a を意味します。

-F <file>
--file=<file>

指定されたファイルからタグメッセージを取得します。 - を使用して、標準入力からメッセージを読み取ります。 -a と -s と -u <key-id> のいずれも指定されていない場合は、 -a を意味します。

-e
--edit

-F を使用してファイルから取得したメッセージと、 -m を使用してコマンドラインを使用したメッセージは、通常は編集しないタグメッセージとして使用されます。 このオプションを使用すると、これらのソースから取得したメッセージをさらに編集できます。

--cleanup=<mode>

このオプションは、タグメッセージのクリーンアップ方法を設定します。 <mode> は、 verbatim, whitespace, strip のいずれかになります。 strip モードがデフォルトです。 verbatim モードはメッセージをまったく変更せず、whitespace は 先頭/末尾 の空白行のみを削除し、strip は空白(whitespace)とコメント(commentary)の両方を削除します。

--create-reflog

タグのreflogを作成します。 タグのreflogをグローバルに有効にするには、 git-config(1) の core.logAllRefUpdates を参照してください。 否定形式 --no-create-reflog は、(コマンドラインで)それ以前に指定された --create-reflog をオーバーライドするだけですが、現在のところ、core.logAllRefUpdates の設定を否定しません。

--format=<format>

表示されているタグrefとそれが指すオブジェクトを %(fieldname) によって差し込みする文字列。 形式はgit-for-each-ref(1) の形式と同じです。 指定しない場合、デフォルトは %(refname:strip=2) です。

<tagname>

作成または削除または説明するタグの名前。 新しいタグ名は、git-check-ref-format(1) で定義されているすべてのチェックに合格する必要があります。 これらのチェックの一部は、タグ名で許可される文字を制限する場合があります。

<commit>
<object>

新しいタグが参照するオブジェクト、通常はコミット。 デフォルトはHEADです。

CONFIGURATION

デフォルトでは、 sign-with-default モード(-s)の git tag は、コミッターID(Your Name <your@email.address> 形式)を使用してキーを検索します。 別のデフォルトキーを使用する場合は、リポジトリ構成(repository configuration)で以下のように指定できます:

[user]
    signingKey = <gpg-key_id>

pager.tag は、タグを一覧表示する場合、つまり -l が使用または暗示されている場合にのみ尊重されます。 デフォルトではpagerを使用します。 git-config(1) を参照してください。

DISCUSSION

On Re-tagging

間違ったコミットにタグを付けてしまいました。再度タグを付けたい場合はどうすればよいですか？

あなたがまだ何もプッシュしたことがない場合は、タグを付け直してください。 古いものを置き換えるには -f を使用します。 これで完了です。

しかし、あなたが何かプッシュした場合(または他の人があなたのリポジトリを直接読み取ることができた場合)、他の人はすでに古いタグを見ているでしょう。 その場合、あなたは以下の2つのいずれかを実行できます:

  1. 常識的には、失敗したことを認めて、別の名前を使用してください。 他の人は既にとあるタグ名を見たことがあり、同一の名前を保持している場合、2人が両方とも「バージョンX」を持っているように見える状況にあるかもしれませんが、実際には「異なる」「X」を持っています。 だから、それを「X.1」と呼んで、それで終わりです。

  2. 非常識なやり方は、他の人がすでに古いバージョンを見たとしても、あなたは本当に新しいバージョンを「X」と呼びたいのです。 したがって、古いものをまだ公開していないかのように、もう一度 git tag -f を使用します。

しかしながら、 Gitは、 ユーザーいない所で勝手にタグを変更することはありません(また変更すべきではありません)。 ですから、 誰かが既に古いタグを取得している場合、 あなたのツリーで git pull を実行しても、 古いタグを上書きすることにはならないはずです。

誰かがあなたからリリースタグを取得した場合、あなた自身のタグを更新することで、その人のタグを変更することはできません。これは、人々が自分のタグ名を信頼できなければならないという点で、大きなセキュリティ上の議題です。 もしあなたが本当に非常識なことをしたいのであれば、 素直に白状して自分が失敗したことを人々に伝える必要があります。 そうするには、 以下のように公言すればよいでしょう:

私はやらかしちまって、間違いのあるバージョンをXとタグ付けしてプッシュしてしまいました。
それから私は、その何かを修正し、「修正された」ツリーを再度Xとしてタグ付けしました。

あなたが既に間違ったタグを取得してしまっていて、新しいタグが必要な場合は、
古いタグを削除し、以下の手順を実行して新しいタグをフェッチしてください。お願いします:

        git tag -d X
        git fetch origin tag X

これで更新されたタグを取得します。

あなたは以下のようにしてあなたの持っているタグをテストできます

        git rev-parse X

これは、あなたが新しいバージョンを持っているなら、 0123456789abcdef.. と返されるはずです。

ご不便おかけしてすみませんでした。

これは少々複雑に見えますか？ そのとおりです。 自動的に「修正」するだけで正しくなる方法はありません。 人々にタグが変更された可能性があることを知らせる必要があります。

On Automatic following

他の誰かのツリーを追っている場合は、リモート追跡ブランチ(例: refs/remotes/origin/master)を使用している可能性があります。 通常、相手側からのタグが必要です。

一方、他の誰かからの一回限りの(one-shot)マージが必要なためにフェッチしている場合は、通常、そこからタグを取得する必要はありません。 これは、トップレベルに近い人によく起こりますが、それに限定されません。 神ならぬ人々は、お互いからプルするとき、必ずしも相手からプライベートアンカーポイントタグを自動的に取得したいとは思いません。

多くの場合、メーリングリストの「プルしてください」というメッセージは、リポジトリのURLとブランチ名の2つの情報を提供するだけです。 これは、 git fetch コマンドラインの最後で簡単にカットアンドペーストできるように設計されています:

リーナス、更新を取得するために、

        git://git..../proj.git master

上記から取得してください。

とあれば、以下のようになります:

$ git pull git://git..../proj.git master

このような場合、あなたは相手のタグを自動的に追跡したくはないでしょう。

Gitの重要な側面の1つは分散型であり、これは主にシステムに固有の「上流」(upstream)または「下流」(downstream)がないことを意味します。 一見すると、上記の例は、タグの名前空間が上層部の人々によって所有されており、タグが下向きにのみ流れることを示しているように見えるかもしれませんが、そうではありません。 使用パターンによって、誰が誰のタグに関心があるかが決まることだけが示されています。

一回限りのプル(on-shot pull)は、あるコミット履歴が、独自のタグ(例:「これは、2.6.21リリースで一般消費向けに提案されるネットワーク処理関連グループからの3番目のリリース候補です」)を持つあるサークル(例:「カーネルのネットワーク処理部分に主に関心がある人々」)と、別のサークル(例:「さまざまなサブシステムの改善を統合する人々」)の間の境界を越えていることを示すサインです。 後者は通常、前者のグループで内部的に使用される詳細なタグには関心がありません(これが「内部」の意味です)。そのため、この場合、タグを自動的に追跡しないことが望ましいです。

ネットワーク処理関連グループの人々の間では、 グループ内でタグを交換したいと思うかもしれませんが、 その作業フローでは、リモート追跡ブランチを使用して互いの進行状況を追跡している可能性があります。 繰り返しますが、 そのようなタグを自動的に追跡するヒューリスティックは良いことです。

On Backdating Tags

別のVCSからいくつかの変更をインポートし、作業のメジャーリリースのタグを追加したい場合は、タグオブジェクト内に埋め込む日付を指定できると便利です。 タグオブジェクト内のこのようなデータは、たとえば、gitwebインターフェイスでのタグの順序に影響します。

将来のタグオブジェクトで使用される日付を設定するには、環境変数 GIT_COMMITTER_DATE を設定します(可能な値については後の説明を参照してください。最も一般的な形式は "YYYY-MM-DD HH:MM" です)。

For example:

$ 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> <time-zone-offset> ここで、 <unix-timestamp> UNIXエポックからの秒数です。 <time-zone-offset> はUTCからの正または負のオフセットです。 たとえば、CET(UTCより1時間進んでいます)は +0100 です。

RFC 2822

RFC 2822で説明されている標準の電子メール形式。たとえば、 Thu, 07 Apr 2005 22:13:13 +0200 。

ISO 8601

ISO 8601規格で指定されている日時(例: 2005-04-07T22:13:13)。パーサは、 T 文字の代わりにスペースも受け入れます。秒の小数部分は無視されます。たとえば、 2005-04-07T22:13:13.019 は 2005-04-07T22:13:13 として扱われます。

Note
 日付部分は、上記に加えて、 YYYY.MM.DD または MM/DD/YYYY または DD.MM.YYYY 形式が受け入れられます。

FILES

$GIT_DIR/TAG_EDITMSG

このファイルには、 処理中の注釈付きタグのメッセージが含まれています。 注釈付きタグの作成前にエラーにより「git tag」が終了した場合、 エディター・セッションにてユーザーが書き込んだタグ・メッセージがこのファイルに存在します。 ただし、このファイルは次回の「git tag」の呼び出しによって上書きされる可能性があります。

NOTES

複数の --contains フィルターと --no-contains フィルターを組み合わせる場合、少なくとも1つの --contains コミットを含み、 --no-contains コミットを含まない参照のみが表示されます。

複数の --merged フィルターと --no-merged フィルターを組み合わせると、少なくとも1つの --merged コミットから到達可能で、 --no-merged コミットのいずれからも到達できない参照のみが表示されます。

SEE ALSO

git-check-ref-format(1). git-config(1).

GIT

Part of the git(1) suite