git-tag man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]



GIT-TAG(1)					       GIT-TAG(1)

NAME
       git-tag - Create, list, delete or verify a tag object signed with GPG

SYNOPSIS
       git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
	       <tagname> [<commit> | <object>]
       git tag -d <tagname>...
       git tag [-n[<num>]] -l [--contains <commit>] [<pattern>]
       git tag -v <tagname>...

DESCRIPTION
       Adds a tag reference in .git/refs/tags/.

       Unless  -f  is  given,  the  tag	 must not yet exist in .git/refs/tags/
       directory.

       If one of -a, -s, or -u <key-id> is passed, the command creates	a  tag
       object,	and  requires the tag message. Unless -m <msg> or -F <file> is
       given, an editor is started for the user to type in the tag message.

       If -m <msg> or -F <file> is given and  -a,  -s,	and  -u	 <key-id>  are
       absent, -a is implied.

       Otherwise  just	the  SHA1  object name of the commit object is written
       (i.e. a lightweight tag).

       A GnuPG signed tag object will be created when -s  or  -u  <key-id>  is
       used. When -u <key-id> is not used, the committer identity for the cur-
       rent user is used to find the GnuPG key for signing.

OPTIONS
       -a     Make an unsigned, annotated tag object

       -s     Make a GPG-signed tag, using the default e-mail  address’s
	      key

       -u <key-id>
	      Make a GPG-signed tag, using the given key

       -f, --force
	      Replace an existing tag with the given name (instead of failing)

       -d     Delete existing tags with the given names.

								1

GIT-TAG(1)					       GIT-TAG(1)

       -v     Verify the gpg signature of the given tag names.

       -n<num>
	      <num> specifies how many lines from the annotation, if any,  are
	      printed  when  using -l. The default is not to print any annota-
	      tion lines. If no number is given to -n, only the first line  is
	      printed. If the tag is not annotated, the commit message is dis-
	      played instead.

       -l <pattern>
	      List tags with names that match the given pattern (or all if  no
	      pattern  is  given).  Typing  "git  tag" without arguments, also
	      lists all tags.

       --contains <commit>
	      Only list tags which contain the specified commit.

       -m <msg>
	      Use the given tag message (instead of prompting). If multiple -m
	      options  are  given,  their  values are concatenated as separate
	      paragraphs. Implies -a if none of -a,  -s,  or  -u  <key-id>  is
	      given.

       -F <file>
	      Take the tag message from the given file. Use - to read the mes-
	      sage from the standard input. Implies -a if none of -a,  -s,  or
	      -u <key-id> is given.

       <tagname>
	      The  name of the tag to create, delete, or describe. The new tag
	      name must pass all checks	 defined  by  git-check-ref-format(1).
	      Some  of	these  checks may restrict the characters allowed in a
	      tag name.

CONFIGURATION
       By default, git tag in sign-with-default mode (-s) will use  your  com-
       mitter	identity   (of	 the   form  "Your  Name  <your@email.address:
       mailto:your@email.address>") to find a key. If you want to use  a  dif-
       ferent  default key, you can specify it in the repository configuration
       as follows:

       .ft C
       [user]
	   signingkey = <gpg-key-id>
       .ft

								2

GIT-TAG(1)					       GIT-TAG(1)

DISCUSSION
   On Re-tagging
       What should you do when you tag a wrong commit and you  would  want  to
       re-tag?

       If  you	never pushed anything out, just re-tag it. Use "-f" to replace
       the old one. And you’re done.

       But if you have pushed things out  (or  others  could  just  read  your
       repository  directly),  then others will have already seen the old tag.
       In that case you can do one of two things:

       1. The sane thing. Just admit you screwed up, and use a different name.
	  Others  have	already	 seen  one  tag-name, and if you keep the same
	  name, you may be in the situation that two people both have "version
	  X",  but  they  actually have different "X"'s. So just call it "X.1"
	  and be done with it.

       2. The insane thing. You really want to call the new version  "X"  too,
	  even	though	others	have already seen the old one. So just use git
	  tag -f again, as if you hadn’t already published the old  one.

       However,	 Git  does  not	 (and  it should not) change tags behind users
       back. So if somebody already got the old tag, doing a git pull on  your
       tree shouldn’t just make them overwrite the old one.

       If  somebody got a release tag from you, you cannot just change the tag
       for them by updating your own one. This is a  big  security  issue,  in
       that  people  MUST be able to trust their tag-names. If you really want
       to do the insane thing, you need to just fess up to it, and tell people
       that  you  messed up. You can do that by making a very public announce-
       ment saying:

       .ft C
       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

								3

GIT-TAG(1)					       GIT-TAG(1)

	       git rev-parse X

       which should return 0123456789abcdef.. if you have the new version.

       Sorry for inconvenience.
       .ft

       Does this seem a bit complicated? It should be. There is no way that it
       would  be correct to just "fix" it behind peoples backs. People need to
       know that their tags might have been changed.

   On Automatic following
       If you are following somebody else’s tree, you  are  most	likely
       using  tracking	branches  (refs/heads/origin in traditional layout, or
       refs/remotes/origin/master in the separate-remote layout). You  usually
       want the tags from the other end.

       On  the	other  hand,  if  you  are  fetching  because you would want a
       one-shot merge from somebody else, you typically do  not	 want  to  get
       tags  from  there. This happens more often for people near the toplevel
       but not limited to them. Mere mortals when pulling from each  other  do
       not  necessarily	 want  to  automatically get private anchor point tags
       from the other person.

       You would notice "please pull" messages on the mailing list  says  repo
       URL  and branch name alone. This is designed to be easily cut&pasted to
       a git fetch command line:

       .ft C
       Linus, please pull from

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

       to get the following updates...
       .ft

       becomes:

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

								4

GIT-TAG(1)					       GIT-TAG(1)

       In such a case, you do not want to automatically	 follow	 other’s
       tags.

       One important aspect of git is it is distributed, and being distributed
       largely means there is no inherent "upstream" or	 "downstream"  in  the
       system.	On  the	 face  of it, the above example might seem to indicate
       that the tag namespace is owned by upper echelon	 of  people  and  tags
       only  flow  downwards, but that is not the case. It only shows that the
       usage pattern determines who are interested in whose tags.

       A one-shot pull is a sign that a commit history	is  now	 crossing  the
       boundary	 between  one circle of people (e.g. "people who are primarily
       interested in the networking part of the kernel") who  may  have	 their
       own  set	 of  tags  (e.g. "this is the third release candidate from the
       networking group to be proposed for  general  consumption  with	2.6.21
       release") to another circle of people (e.g. "people who integrate vari-
       ous subsystem improvements"). The latter are usually not interested  in
       the  detailed  tags  used  internally in the former group (that is what
       "internal" means). That is why it is desirable not to follow tags auto-
       matically in this case.

       It  may well be that among networking people, they may want to exchange
       the tags internal to their group, but in that workflow  they  are  most
       likely  tracking	 with  each  other’s progress by having tracking
       branches. Again, the heuristic to automatically follow such tags	 is  a
       good thing.

   On Backdating Tags
       If  you	have  imported some changes from another VCS and would like to
       add tags for major releases of your work, it is useful to  be  able  to
       specify the date to embed inside of the tag object. The data in the tag
       object affects, for example, the ordering of tags in the gitweb	inter-
       face.

       To  set	the date used in future tag objects, set the environment vari-
       able GIT_COMMITTER_DATE to one or more of the date and time.  The  date
       and  time  can  be  specified  in  a number of ways; the most common is
       "YYYY-MM-DD HH:MM".

       An example follows.

       .ft C
       $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
       .ft

								5

GIT-TAG(1)					       GIT-TAG(1)

SEE ALSO
       git-check-ref-format(1).

AUTHOR
       Written	 by    Linus	Torvalds    <torvalds@osdl.org:	   mailto:tor-
       valds@osdl.org>,	  Junio	  C   Hamano  <gitster@pobox.com:  mailto:git-
       ster@pobox.com>	    and	     Chris	Wright	     <chrisw@osdl.org:
       mailto:chrisw@osdl.org>.

DOCUMENTATION
       Documentation  by  David	 Greaves,  Junio  C  Hamano  and  the git-list
       <git@vger.kernel.org: mailto:git@vger.kernel.org>.

GIT
       Part of the git(1) suite

								6

[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net