Repository tags

Tags mark a specific commit at a point in your repository history. When you tag a commit, you're including all the changes before it. You can later compare tags to see the difference between two points in history. Tags are commonly used to mark release versions, with the release name as the tag name.

Bitbucket Cloud supports tags for Git and Mercurial repositories. You can create a tag in Bitbucket or locally and push it to Bitbucket.

This page

Create a tag in Bitbucket

  1. From your Bitbucket repository, click the link for the commit you want to tag.
  2. In the details on the right side of the page, click the  button.
  3. Enter a Tag name and click Create tag.

Removing a tag

You can't remove a tag from Bitbucket after you've added it. To remove a tag, you'll have to do so from the command line. Refer to Tags for Git repositories and Tags for Mercurial repositories for these commands.

See the commits for a tag

  1. Click the Commits link the left panel.
  2. Click the dropdown at the top of the page.
  3. Click the Tags tab.
  4. Search for and click the tag you want to see. The Commits list updates with all the commits for that tag.

When you create a tag for a Mercurial repository, the .hgtags file updates with the commit hash and the name of the tag. As a result, you'll see a new commit to the repository with the change.

Create and push a tag to Bitbucket

You can create tags locally for your Git or Mercurial repositories. Depending on the type of tag you create, they'll appear in Bitbucket anywhere that lists your tags for a commit.

Tags for Git repositories

While Git supports annotated and lightweight tags, you can only create and see annotated tags in Bitbucket. Git stores annotated tags as full objects in the repository, which means they include the name, email, date, and have a message. Lightweight tags don't include all this additional information.

Use the following commands to create, push, and perform other tagging options for Git repositories.

Tag task Git commands
Create an annotated tag
git tag -a <tag_name> -m '<tag_message>'
Create a lightweight tag
git tag <tag_name>
Push all your tags (a regular push won't push a tag)
git push origin --tags
Push a single tag
git push origin : <tag_name>
List the tags in a repository
git tag
Remove a tag from a repository
git tag -d <tag_name>
git push origin :refs/tags/<tag_name>

Tags for Mercurial repositories

While Mercurial supports regular and local tags, you can only create and see regular tags in Bitbucket. Regular tags are version controlled, and Mercurial stores them in the .hgtags file. You use local tags, which are unversioned, for your personal convenience, and Mercurial stores them in the .hg/localtags file.

Use the following commands to create and perform other tagging options for Mercurial repositories.

Tag task Mercurial commands
Create a regular tag hg tag <tag_name>
Create a local tag (Hg) hg tag -l <tag_name>
Push your tags (a normal push) hg push
List the tags in a repository hg tags
Remove a tag from a repository
hg tag --remove <tag_name>

Compare the diffs with tags

Once you've got at least one tag, you can compare that tag with another tag or a branch.

  1. Click + in the global sidebar and select Compare branches or tags under Get to work.
  2. From each dropdown, select the tag or branch that you want to include as part of the comparison.
  3. Click Compare.

You'll see a diff, a list of commits, and any pull requests merged between the two versions.

Last modified on Jun 27, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.