Differences between revisions 24 and 30 (spanning 6 versions)
Revision 24 as of 2008-04-20 00:09:43
Size: 5096
Editor: abuehl
Comment:
Revision 30 as of 2009-05-19 19:30:56
Size: 5598
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 4: Line 4:
(''Note: If you are migrating from ["CVS"], please [:CvsConcepts#tag:read this discussion of CVS tags] before you continue.'') (''Note: If you are migrating from [[CVS]], please [[CvsConcepts#tag|read this discussion of CVS tags]] before you continue.'')
Line 6: Line 6:
`hg tags`[[BR]] `hg tags`<<BR>>
Line 9: Line 9:
A '''tag''' is a symbolic identifier for a [:ChangeSet:changeset]. It can contain any characters except ":" (colon), "\r" (Carriage Return) or "\n" (Line Feed). Mercurial has two kinds of tags: local and regular. A '''tag''' is a symbolic identifier for a [[ChangeSet|changeset]]. It can contain any characters except ":" (colon), "\r" (Carriage Return) or "\n" (Line Feed). Mercurial has two kinds of tags: local and regular.
Line 11: Line 11:
A ''local'' tag is a convenience identifier that is not revision controlled, does not propagate with other changes, and lives in the {{{.hg/localtags}}} file in a [:Repository:repository]. A ''local'' tag is a convenience identifier that is not revision controlled, does not propagate with other changes, and lives in the {{{.hg/localtags}}} file in a [[Repository|repository]].
Line 13: Line 13:
A "regular" tag (with no special specifier) ''is'' revision controlled, ''does'' propagate with other changes, and lives in the {{{.hgtags}}} file in a repository. (It is therefore possible to remove tags by editing {{{.hgtags}}} and committing the change - this being the nearest equivalent to {{{cvs tag -d}}}). A "regular" tag (with no special specifier) ''is'' revision controlled, ''does'' propagate with other changes, and lives in the {{{.hgtags}}} file in a repository.
Line 15: Line 15:
[[TableOfContents]] <<TableOfContents>>
Line 22: Line 22:
 * be version controlled and [:Merge:mergeable] just like any other file  * be version controlled and [[Merge|mergeable]] just like any other file
Line 24: Line 24:
 * allow adding a tag to an already [:Commit:committed] changeset  * allow adding a tag to an already [[Commit|committed]] changeset
Line 27: Line 27:
Thus Mercurial stores tags as a file in the [:WorkingDirectory:working dir]. This file is
called .hgtags and consists of a list of [:ChangeSetID:changeset IDs] and their
Thus Mercurial stores tags as a file in the [[WorkingDirectory|working dir]]. This file is
called .hgtags and consists of a list of [[ChangeSetID|changeset IDs]] and their
Line 44: Line 44:
 * [:Update:Updating] a working dir to a particular tag will take that directory back to a point before the tag itself existed.
 * [:Clone:Cloning] a repo to a particular tag will give you a new repo that does ''not'' have that tag.
 * [[Update|Updating]] a working dir to a particular tag will take that directory back to a point before the tag itself existed.
 * [[Clone|Cloning]] a repo to a particular tag will give you a new repo that does ''not'' have that tag.
Line 56: Line 56:
The tags that are in effect at any given time are the tags specified
in each [[Head|head]].
A difficult case arises, if the same tag specifies two different revisions in two different heads. There is no general "correct" solution to this problem.
Line 57: Line 60:
The tags that are in effect at any given time are the tags specified
in each [:Head:head], with heads closer to the [:Tip:tip] taking precedence. Local
tags override all other tags.
If two definitions/changes of tags seem unrelated like in the following diagram, the "[[Tip|tip]]most" (e.g. the one with the higher numeric revision number) wins.
{{{#!dot
    digraph G {
      "..." -> "Rev: 12" -> "Rev: 13\ntag_a=1"
      "Rev: 12" -> "Rev: 14\ntag_a=2"
    }
}}}
In the above diagram {{{tag_a}}} refers to revision 2, since revision 14 is higher than revision 13.
Line 61: Line 69:
See also: [:MultipleHeads] /!\ Note that the numeric revision number depends on the sequence by which changes got pulled into a repository and may therefore vary even on repositories containing the same changesets.

However if a tag was defined in a common ancestor of both heads, but changed in just one head, the changed one wins over the unchanged one.
{{{#!dot
    digraph G {
      "..." -> "Rev: 12\ntag_b=9" -> "Rev: 13\ntag_b=10"
      "Rev: 12\ntag_b=9" -> "Rev: 14\n (this revision still contains tag_b=9) "
    }
}}}
In the above diagram {{{tag_b}}} revers to revision 10, although revision 13 is not tip.

/!\ Note that this ''multiple-head tag collision resolution algorithm'' depends on the {{{.hgtags}}}-file to be append only and be carefully merged.

Local tags override all other tags.

See also: [[MultipleHeads]]
Line 65: Line 88:
Only the last line where the tag appears is taken into account. If there is just one head only the last line where the tag appears is taken into account. If there are multiple heads, the previous definitions of the tag are used to determine which head holds the most recent tag. See "How do tags work with multiple heads?".
If a tag points to {{{0000000000000000000000000000000000000000}}} it is considered to be deleted.
Line 68: Line 93:
=== How do I remove a tag? ===
Either by
  * {{{hg tag --remove tagname}}} (this being the nearest equivalent to {{{cvs tag -d}}})
  * adding {{{tagname 0000000000000000000000000000000000000000}}} to the end of {{{.hgtags}}}
  * removing all references to ''tagname'' in {{{.hgtags}}} (but this might confuse the multiple-head tag collision resolution algorithm)
Line 69: Line 100:
{{{
hg tags

list repository tags

    List the repository tags.

    This lists both regular and local tags. When the -v/--verbose switch
    is used, a third column "local" is printed for local tags.
}}}

{{{
hg tag [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...

add one or more tags for the current or given revision

    Name a particular revision using <name>.

    Tags are used to name particular revisions of the repository and are
    very useful to compare different revisions, to go back to significant
    earlier versions or to mark branch points as releases, etc.

    If no revision is given, the parent of the working directory is used,
    or tip if no revision is checked out.

    To facilitate version control, distribution, and merging of tags,
    they are stored as a file named ".hgtags" which is managed
    similarly to other project files and can be hand-edited if
    necessary. The file '.hg/localtags' is used for local tags (not
    shared among repositories).

    See 'hg help dates' for a list of formats valid for -d/--date.

options:

 -f --force replace existing tag
 -l --local make the tag local
 -r --rev revision to tag
    --remove remove a tag
 -m --message use <text> as commit message
 -d --date record datecode as commit date
 -u --user record user as committer
}}}
 * http://www.selenic.com/mercurial/hg.1.html#tag
 * http://www.selenic.com/mercurial/hg.1.html#tags

Tag

(Note: If you are migrating from CVS, please read this discussion of CVS tags before you continue.)

hg tags
hg tag [-l] [-m TEXT] [-d DATE] [-u USER] [-r REV] NAME...

A tag is a symbolic identifier for a changeset. It can contain any characters except ":" (colon), "\r" (Carriage Return) or "\n" (Line Feed). Mercurial has two kinds of tags: local and regular.

A local tag is a convenience identifier that is not revision controlled, does not propagate with other changes, and lives in the .hg/localtags file in a repository.

A "regular" tag (with no special specifier) is revision controlled, does propagate with other changes, and lives in the .hgtags file in a repository.

How do tags work in Mercurial?

Tags work slightly differently in Mercurial than most revision systems. The design attempts to meet the following requirements:

  • be version controlled and mergeable just like any other file

  • allow signing of tags
  • allow adding a tag to an already committed changeset

  • allow changing tags in the future

Thus Mercurial stores tags as a file in the working dir. This file is called .hgtags and consists of a list of changeset IDs and their corresponding tags. To add a tag to the system, simply add a line to this file and then commit it for it to take effect. The hg tag command will do this for you and hg tags will show the currently effective tags.

Note that because tags refer to changeset IDs and the changeset ID is effectively the sum of all the contents of the repository for that change, it is impossible in Mercurial to simultaneously commit and add a tag for the changeset being committed. Thus tagging a revision must be done as a second step. Thus, as above, the only changesets that can be tagged are ones already committed.

The fact that tags identify changesets and are also parts of changesets has some potentially confusing implications:

  • The changeset that a tag refers to is always older than the changeset that commits the tag itself.
  • Updating a working dir to a particular tag will take that directory back to a point before the tag itself existed.

  • Cloning a repo to a particular tag will give you a new repo that does not have that tag.

<!> Common wisdom says that to avoid the confusion of a disappearing tag, you should clone the entire repo and then update the working directory to the tag. Thus preserving the tag in the repo.

What if I want to just keep local tags?

You can use "hg tag" command with an option -l or --local. This will store the tag in the file .hg/localtags, which will not be distributed or versioned. The format of this file is identical to the one of .hgtags and the tags stored there are handled the same.

How do tags work with multiple heads?

The tags that are in effect at any given time are the tags specified in each head. A difficult case arises, if the same tag specifies two different revisions in two different heads. There is no general "correct" solution to this problem.

If two definitions/changes of tags seem unrelated like in the following diagram, the "tipmost" (e.g. the one with the higher numeric revision number) wins.

In the above diagram tag_a refers to revision 2, since revision 14 is higher than revision 13.

/!\ Note that the numeric revision number depends on the sequence by which changes got pulled into a repository and may therefore vary even on repositories containing the same changesets.

However if a tag was defined in a common ancestor of both heads, but changed in just one head, the changed one wins over the unchanged one.

In the above diagram tag_b revers to revision 10, although revision 13 is not tip.

/!\ Note that this multiple-head tag collision resolution algorithm depends on the .hgtags-file to be append only and be carefully merged.

Local tags override all other tags.

See also: MultipleHeads

What if multiple lines with different revisions use the same tag name in .hgtags?

If there is just one head only the last line where the tag appears is taken into account. If there are multiple heads, the previous definitions of the tag are used to determine which head holds the most recent tag. See "How do tags work with multiple heads?". If a tag points to 0000000000000000000000000000000000000000 it is considered to be deleted.

The behavior is identical when this happens in .hg/localtags.

How do I remove a tag?

Either by

  • hg tag --remove tagname (this being the nearest equivalent to cvs tag -d)

  • adding tagname 0000000000000000000000000000000000000000 to the end of .hgtags

  • removing all references to tagname in .hgtags (but this might confuse the multiple-head tag collision resolution algorithm)

Help texts


CategoryCommand CategoryGlossary

Tag (last edited 2013-09-01 02:00:16 by KevinBot)