| 1 | git-tag(1) |
| 2 | ========== |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-tag - Create, list, delete or verify tags |
| 7 | |
| 8 | |
| 9 | SYNOPSIS |
| 10 | -------- |
| 11 | [synopsis] |
| 12 | git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e] |
| 13 | [(--trailer <token>[(=|:)<value>])...] |
| 14 | <tagname> [<commit> | <object>] |
| 15 | git tag -d <tagname>... |
| 16 | git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>] |
| 17 | [--points-at <object>] [--column[=<options>] | --no-column] |
| 18 | [--create-reflog] [--sort=<key>] [--format=<format>] |
| 19 | [--merged <commit>] [--no-merged <commit>] [<pattern>...] |
| 20 | git tag -v [--format=<format>] <tagname>... |
| 21 | |
| 22 | DESCRIPTION |
| 23 | ----------- |
| 24 | |
| 25 | Add a tag reference in `refs/tags/`, unless `-d`/`-l`/`-v` is given |
| 26 | to delete, list or verify tags. |
| 27 | |
| 28 | Unless `-f` is given, the named tag must not yet exist. |
| 29 | |
| 30 | If one of `-a`, `-s`, or `-u <key-id>` is passed, the command |
| 31 | creates a 'tag' object, and requires a tag message. Unless |
| 32 | `-m <msg>` or `-F <file>` is given, an editor is started for the user to type |
| 33 | in the tag message. |
| 34 | |
| 35 | If `-m <msg>` or `-F <file>` or `--trailer <token>[=<value>]` is given |
| 36 | and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied. |
| 37 | |
| 38 | Otherwise, a tag reference that points directly at the given object |
| 39 | (i.e., a lightweight tag) is created. |
| 40 | |
| 41 | A cryptographically signed tag object will be created when `-s` or |
| 42 | `-u <key-id>` is used. The signing backend (GPG, X.509, SSH, etc.) is |
| 43 | controlled by the `gpg.format` configuration variable, defaulting to |
| 44 | OpenPGP. When `-u <key-id>` is not used, the committer identity for |
| 45 | the current user is used to find the key for signing. The |
| 46 | configuration variable `gpg.program` is used to specify a custom |
| 47 | signing binary. |
| 48 | |
| 49 | Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated" |
| 50 | tags; they contain a creation date, the tagger name and e-mail, a |
| 51 | tagging message, and an optional cryptographic signature. Whereas a |
| 52 | "lightweight" tag is simply a name for an object (usually a commit |
| 53 | object). |
| 54 | |
| 55 | Annotated tags are meant for release while lightweight tags are meant |
| 56 | for private or temporary object labels. For this reason, some git |
| 57 | commands for naming objects (like `git describe`) will ignore |
| 58 | lightweight tags by default. |
| 59 | |
| 60 | |
| 61 | OPTIONS |
| 62 | ------- |
| 63 | `-a`:: |
| 64 | `--annotate`:: |
| 65 | Make an unsigned, annotated tag object |
| 66 | |
| 67 | `-s`:: |
| 68 | `--sign`:: |
| 69 | Make a cryptographically signed tag, using the default signing |
| 70 | key. The signing backend used depends on the `gpg.format` |
| 71 | configuration variable. The default key is determined by the |
| 72 | backend. For GPG, it's based on the committer's email address, |
| 73 | while for SSH it may be a specific key file or agent |
| 74 | identity. See linkgit:git-config[1]. |
| 75 | |
| 76 | `--no-sign`:: |
| 77 | Override `tag.gpgSign` configuration variable that is |
| 78 | set to force each and every tag to be signed. |
| 79 | |
| 80 | `-u <key-id>`:: |
| 81 | `--local-user=<key-id>`:: |
| 82 | Make a cryptographically signed tag using the given key. The |
| 83 | format of the <key-id> and the backend used depend on the |
| 84 | `gpg.format` configuration variable. See |
| 85 | linkgit:git-config[1]. |
| 86 | |
| 87 | `-f`:: |
| 88 | `--force`:: |
| 89 | Replace an existing tag with the given name (instead of failing) |
| 90 | |
| 91 | `-d`:: |
| 92 | `--delete`:: |
| 93 | Delete existing tags with the given names. |
| 94 | |
| 95 | `-v`:: |
| 96 | `--verify`:: |
| 97 | Verify the cryptographic signature of the given tags. |
| 98 | |
| 99 | `-n<num>`:: |
| 100 | _<num>_ specifies how many lines from the annotation, if any, |
| 101 | are printed when using `-l`. Implies `--list`. |
| 102 | + |
| 103 | The default is not to print any annotation lines. |
| 104 | If no number is given to `-n`, only the first line is printed. |
| 105 | If the tag is not annotated, the commit message is displayed instead. |
| 106 | |
| 107 | `-l`:: |
| 108 | `--list`:: |
| 109 | List tags. With optional `<pattern>...`, e.g. `git tag --list |
| 110 | 'v-*'`, list only the tags that match the pattern(s). |
| 111 | + |
| 112 | Running `git tag` without arguments also lists all tags. The pattern |
| 113 | is a shell wildcard (i.e., matched using `fnmatch`(3)). Multiple |
| 114 | patterns may be given; if any of them matches, the tag is shown. |
| 115 | + |
| 116 | This option is implicitly supplied if any other list-like option such |
| 117 | as `--contains` is provided. See the documentation for each of those |
| 118 | options for details. |
| 119 | |
| 120 | `--sort=<key>`:: |
| 121 | Sort based on the key given. Prefix `-` to sort in |
| 122 | descending order of the value. You may use the `--sort=<key>` option |
| 123 | multiple times, in which case the last _<key>_ becomes the primary |
| 124 | key. Also supports "`version:refname`" or "`v:refname`" (tag |
| 125 | names are treated as versions). The "`version:refname`" sort |
| 126 | order can also be affected by the "`versionsort.suffix`" |
| 127 | configuration variable. |
| 128 | The keys supported are the same as those in `git for-each-ref`. |
| 129 | Sort order defaults to the value configured for the `tag.sort` |
| 130 | variable if it exists, or lexicographic order otherwise. See |
| 131 | linkgit:git-config[1]. |
| 132 | |
| 133 | `--color[=<when>]`:: |
| 134 | Respect any colors specified in the `--format` option. The |
| 135 | _<when>_ field must be one of `always`, `never`, or `auto` (if |
| 136 | _<when>_ is absent, behave as if `always` was given). |
| 137 | |
| 138 | `-i`:: |
| 139 | `--ignore-case`:: |
| 140 | Sorting and filtering tags are case insensitive. |
| 141 | |
| 142 | `--omit-empty`:: |
| 143 | Do not print a newline after formatted refs where the format expands |
| 144 | to the empty string. |
| 145 | |
| 146 | `--column[=<options>]`:: |
| 147 | `--no-column`:: |
| 148 | Display tag listing in columns. See configuration variable |
| 149 | `column.tag` for option syntax. `--column` and `--no-column` |
| 150 | without options are equivalent to `always` and `never` respectively. |
| 151 | + |
| 152 | This option is only applicable when listing tags without annotation lines. |
| 153 | |
| 154 | `--contains [<commit>]`:: |
| 155 | Only list tags which contain _<commit>_ (`HEAD` if not |
| 156 | specified). Implies `--list`. |
| 157 | |
| 158 | `--no-contains [<commit>]`:: |
| 159 | Only list tags which don't contain _<commit>_ (`HEAD` if |
| 160 | not specified). Implies `--list`. |
| 161 | |
| 162 | `--merged [<commit>]`:: |
| 163 | Only list tags whose commits are reachable from |
| 164 | _<commit>_ (`HEAD` if not specified). |
| 165 | |
| 166 | `--no-merged [<commit>]`:: |
| 167 | Only list tags whose commits are not reachable from |
| 168 | _<commit>_ (`HEAD` if not specified). |
| 169 | |
| 170 | `--points-at [<object>]`:: |
| 171 | Only list tags of _<object>_ (`HEAD` if not |
| 172 | specified). Implies `--list`. |
| 173 | |
| 174 | `-m <msg>`:: |
| 175 | `--message=<msg>`:: |
| 176 | Use _<msg>_ (instead of prompting). |
| 177 | If multiple `-m` options are given, their values are |
| 178 | concatenated as separate paragraphs. |
| 179 | Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` |
| 180 | is given. |
| 181 | |
| 182 | `-F <file>`:: |
| 183 | `--file=<file>`:: |
| 184 | Take the tag message from _<file>_. Use `-` to |
| 185 | read the message from the standard input. |
| 186 | Implies `-a` if none of `-a`, `-s`, or `-u <key-id>` |
| 187 | is given. |
| 188 | |
| 189 | `--trailer <token>[(=|:)<value>]`:: |
| 190 | Specify a (_<token>_, _<value>_) pair that should be applied as a |
| 191 | trailer. (e.g. `git tag --trailer "Custom-Key: value"` |
| 192 | will add a "Custom-Key" trailer to the tag message.) |
| 193 | The `trailer.*` configuration variables |
| 194 | (linkgit:git-interpret-trailers[1]) can be used to define if |
| 195 | a duplicated trailer is omitted, where in the run of trailers |
| 196 | each trailer would appear, and other details. |
| 197 | The trailers can be extracted in `git tag --list`, using |
| 198 | `--format="%(trailers)"` placeholder. |
| 199 | |
| 200 | `-e`:: |
| 201 | `--edit`:: |
| 202 | Let further edit the message taken from file with `-F` and command line with |
| 203 | `-m`. |
| 204 | |
| 205 | `--cleanup=<mode>`:: |
| 206 | Set how the tag message is cleaned up. |
| 207 | The _<mode>_ can be one of `verbatim`, `whitespace` and `strip`. The |
| 208 | `strip` mode is default. The `verbatim` mode does not change message at |
| 209 | all, `whitespace` removes just leading/trailing whitespace lines and |
| 210 | `strip` removes both whitespace and commentary. |
| 211 | |
| 212 | `--create-reflog`:: |
| 213 | Create a reflog for the tag. To globally enable reflogs for tags, see |
| 214 | `core.logAllRefUpdates` in linkgit:git-config[1]. |
| 215 | The negated form `--no-create-reflog` only overrides an earlier |
| 216 | `--create-reflog`, but currently does not negate the setting of |
| 217 | `core.logAllRefUpdates`. |
| 218 | |
| 219 | `--format=<format>`:: |
| 220 | A string that interpolates `%(fieldname)` from a tag ref being shown |
| 221 | and the object it points at. The format is the same as |
| 222 | that of linkgit:git-for-each-ref[1]. When unspecified, |
| 223 | defaults to `%(refname:strip=2)`. |
| 224 | |
| 225 | _<tagname>_:: |
| 226 | The name of the tag to create, delete, or describe. |
| 227 | The new tag name must pass all checks defined by |
| 228 | linkgit:git-check-ref-format[1]. Some of these checks |
| 229 | may restrict the characters allowed in a tag name. |
| 230 | |
| 231 | _<commit>_:: |
| 232 | _<object>_:: |
| 233 | The object that the new tag will refer to, usually a commit. |
| 234 | Defaults to `HEAD`. |
| 235 | |
| 236 | CONFIGURATION |
| 237 | ------------- |
| 238 | By default, `git tag` in sign-with-default mode (`-s`) will use your |
| 239 | committer identity (of the form `Your Name <your@email.address>`) to |
| 240 | find a key. If you want to use a different default key, you can specify |
| 241 | it in the repository configuration as follows: |
| 242 | |
| 243 | ------------------------------------- |
| 244 | [user] |
| 245 | signingKey = <key-id> |
| 246 | ------------------------------------- |
| 247 | |
| 248 | The signing backend can be chosen via the `gpg.format` configuration |
| 249 | variable, which defaults to `openpgp`. See linkgit:git-config[1] |
| 250 | for a list of other supported formats. |
| 251 | |
| 252 | The path to the program used for each signing backend can be specified |
| 253 | with the `gpg.<format>.program` configuration variable. For the |
| 254 | `openpgp` backend, `gpg.program` can be used as a synonym for |
| 255 | `gpg.openpgp.program`. See linkgit:git-config[1] for details. |
| 256 | |
| 257 | `pager.tag` is only respected when listing tags, i.e., when `-l` is |
| 258 | used or implied. The default is to use a pager. |
| 259 | |
| 260 | See linkgit:git-config[1] for more details and other configuration |
| 261 | variables. |
| 262 | |
| 263 | DISCUSSION |
| 264 | ---------- |
| 265 | |
| 266 | On Re-tagging |
| 267 | ~~~~~~~~~~~~~ |
| 268 | |
| 269 | What should you do when you tag a wrong commit and you would |
| 270 | want to re-tag? |
| 271 | |
| 272 | If you never pushed anything out, just re-tag it. Use `-f` to |
| 273 | replace the old one. And you're done. |
| 274 | |
| 275 | But if you have pushed things out (or others could just read |
| 276 | your repository directly), then others will have already seen |
| 277 | the old tag. In that case you can do one of two things: |
| 278 | |
| 279 | . The sane thing. |
| 280 | Just admit you screwed up, and use a different name. Others have |
| 281 | already seen one tag-name, and if you keep the same name, you |
| 282 | may be in the situation that two people both have "version X", |
| 283 | but they actually have 'different' "X"'s. So just call it "X.1" |
| 284 | and be done with it. |
| 285 | |
| 286 | . The insane thing. |
| 287 | You really want to call the new version "X" too, 'even though' |
| 288 | others have already seen the old one. So just use `git tag -f` |
| 289 | again, as if you hadn't already published the old one. |
| 290 | |
| 291 | However, Git does *not* (and it should not) change tags behind |
| 292 | users back. So if somebody already got the old tag, doing a |
| 293 | `git pull` on your tree shouldn't just make them overwrite the old |
| 294 | one. |
| 295 | |
| 296 | If somebody got a release tag from you, you cannot just change |
| 297 | the tag for them by updating your own one. This is a big |
| 298 | security issue, in that people MUST be able to trust their |
| 299 | tag-names. If you really want to do the insane thing, you need |
| 300 | to just fess up to it, and tell people that you messed up. You |
| 301 | can do that by making a very public announcement saying: |
| 302 | |
| 303 | ------------ |
| 304 | Ok, I messed up, and I pushed out an earlier version tagged as X. I |
| 305 | then fixed something, and retagged the *fixed* tree as X again. |
| 306 | |
| 307 | If you got the wrong tag, and want the new one, please delete |
| 308 | the old one and fetch the new one by doing: |
| 309 | |
| 310 | git tag -d X |
| 311 | git fetch origin tag X |
| 312 | |
| 313 | to get my updated tag. |
| 314 | |
| 315 | You can test which tag you have by doing |
| 316 | |
| 317 | git rev-parse X |
| 318 | |
| 319 | which should return 0123456789abcdef.. if you have the new version. |
| 320 | |
| 321 | Sorry for the inconvenience. |
| 322 | ------------ |
| 323 | |
| 324 | Does this seem a bit complicated? It *should* be. There is no |
| 325 | way that it would be correct to just "fix" it automatically. |
| 326 | People need to know that their tags might have been changed. |
| 327 | |
| 328 | |
| 329 | On Automatic following |
| 330 | ~~~~~~~~~~~~~~~~~~~~~~ |
| 331 | |
| 332 | If you are following somebody else's tree, you are most likely |
| 333 | using remote-tracking branches (eg. `refs/remotes/origin/master`). |
| 334 | You usually want the tags from the other end. |
| 335 | |
| 336 | On the other hand, if you are fetching because you would want a |
| 337 | one-shot merge from somebody else, you typically do not want to |
| 338 | get tags from there. This happens more often for people near |
| 339 | the toplevel but not limited to them. Mere mortals when pulling |
| 340 | from each other do not necessarily want to automatically get |
| 341 | private anchor point tags from the other person. |
| 342 | |
| 343 | Often, "please pull" messages on the mailing list just provide |
| 344 | two pieces of information: a repo URL and a branch name; this |
| 345 | is designed to be easily cut&pasted at the end of a `git fetch` |
| 346 | command line: |
| 347 | |
| 348 | ------------ |
| 349 | Linus, please pull from |
| 350 | |
| 351 | git://git..../proj.git master |
| 352 | |
| 353 | to get the following updates... |
| 354 | ------------ |
| 355 | |
| 356 | becomes: |
| 357 | |
| 358 | ------------ |
| 359 | $ git pull git://git..../proj.git master |
| 360 | ------------ |
| 361 | |
| 362 | In such a case, you do not want to automatically follow the other |
| 363 | person's tags. |
| 364 | |
| 365 | One important aspect of Git is its distributed nature, which |
| 366 | largely means there is no inherent "upstream" or |
| 367 | "downstream" in the system. On the face of it, the above |
| 368 | example might seem to indicate that the tag namespace is owned |
| 369 | by the upper echelon of people and that tags only flow downwards, but |
| 370 | that is not the case. It only shows that the usage pattern |
| 371 | determines who are interested in whose tags. |
| 372 | |
| 373 | A one-shot pull is a sign that a commit history is now crossing |
| 374 | the boundary between one circle of people (e.g. "people who are |
| 375 | primarily interested in the networking part of the kernel") who may |
| 376 | have their own set of tags (e.g. "this is the third release |
| 377 | candidate from the networking group to be proposed for general |
| 378 | consumption with 2.6.21 release") to another circle of people |
| 379 | (e.g. "people who integrate various subsystem improvements"). |
| 380 | The latter are usually not interested in the detailed tags used |
| 381 | internally in the former group (that is what "internal" means). |
| 382 | That is why it is desirable not to follow tags automatically in |
| 383 | this case. |
| 384 | |
| 385 | It may well be that among networking people, they may want to |
| 386 | exchange the tags internal to their group, but in that workflow |
| 387 | they are most likely tracking each other's progress by |
| 388 | having remote-tracking branches. Again, the heuristic to automatically |
| 389 | follow such tags is a good thing. |
| 390 | |
| 391 | |
| 392 | On Backdating Tags |
| 393 | ~~~~~~~~~~~~~~~~~~ |
| 394 | |
| 395 | If you have imported some changes from another VCS and would like |
| 396 | to add tags for major releases of your work, it is useful to be able |
| 397 | to specify the date to embed inside of the tag object; such data in |
| 398 | the tag object affects, for example, the ordering of tags in the |
| 399 | gitweb interface. |
| 400 | |
| 401 | To set the date used in future tag objects, set the environment |
| 402 | variable GIT_COMMITTER_DATE (see the later discussion of possible |
| 403 | values; the most common form is "YYYY-MM-DD HH:MM"). |
| 404 | |
| 405 | For example: |
| 406 | |
| 407 | ------------ |
| 408 | $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 |
| 409 | ------------ |
| 410 | |
| 411 | include::date-formats.adoc[] |
| 412 | |
| 413 | FILES |
| 414 | ----- |
| 415 | |
| 416 | `$GIT_DIR/TAG_EDITMSG`:: |
| 417 | This file contains the message of an in-progress annotated |
| 418 | tag. If `git tag` exits due to an error before creating an |
| 419 | annotated tag then the tag message that has been provided by the |
| 420 | user in an editor session will be available in this file, but |
| 421 | may be overwritten by the next invocation of `git tag`. |
| 422 | |
| 423 | CONFIGURATION |
| 424 | ------------- |
| 425 | |
| 426 | include::includes/cmd-config-section-all.adoc[] |
| 427 | |
| 428 | :git-tag: 1 |
| 429 | include::config/tag.adoc[] |
| 430 | |
| 431 | NOTES |
| 432 | ----- |
| 433 | |
| 434 | include::ref-reachability-filters.adoc[] |
| 435 | |
| 436 | SEE ALSO |
| 437 | -------- |
| 438 | linkgit:git-check-ref-format[1]. |
| 439 | linkgit:git-config[1]. |
| 440 | |
| 441 | GIT |
| 442 | --- |
| 443 | Part of the linkgit:git[1] suite |