Tags

A tag is a name for a commit that does not move. Branches advance as you commit; tags do not, which is what makes them right for releases. They have a section of their own in the sidebar, under the branches.

Making one

New Tag tags the commit you have checked out. It is the plus button on the Tags heading in the sidebar, Repository ▸ New Tag…, and New Tag… in the Command Palette, and all three open the same sheet.

Tag name is the only thing it needs. Message (optional) decides which kind of tag you get: left empty, a lightweight one; with anything in it, an annotated one. The sheet uses neither word; the two kinds are described further down.

While you type, Tag availability checks the name against your own tags and then against the remote you push to, and reads Checking this name against local and remote tags… until it has an answer:

• Free — Available locally and on origin. When the remote could not be checked, or there is no remote, the sentence says that instead; the tag can be made either way.
• Taken here — Tag already exists locally. There is nothing to make; choose another name.
• Taken only on the remote — Tag already exists on the remote, and a box to tick before the tag can be made, Create the local tag anyway. Making it leaves the remote’s tag alone, and pushing yours may be refused if the two point at different commits.

Pushing it as you make it

Push to origin after creating starts unticked. It becomes available once the name has been checked and there is a remote to push to, and it names that remote: the one you push to, which is not always origin. Tick it and Create becomes Create and Push: the tag is made, and then sent to that remote. The remote is settled when you press the button, so a change to your configuration in the meantime cannot send the tag somewhere else.

If the push fails, the tag is still made. It is in the list, and can be pushed from there.

The list

Tags carries the number of tags on its heading. The section is closed when a repository opens, and opening it shows the three newest, or No tags yet. A lightweight tag has no date of its own, so it is dated by the commit it points at.

With more than three there is a fourth row, Show all tags, which opens every tag in a list of its own with Search tags at the top, matching a tag’s name or the first line of its message — of its commit’s message, for a lightweight tag. Choosing one there selects it and closes the list. A selected tag that is not among the three newest stands in the place of Show all tags for as long as it is selected — and the row still opens the list.

Selecting a tag scopes the history to it: the commit it points at and everything that led to it. The section opens by itself when a tag is selected, wherever from — the Reference filter in the history as well as the sidebar.

The two kinds

• Lightweight — a name and nothing else.
• Annotated — a name with a message, an author and a date, stored as a real object in the repository.

Use annotated for anything anyone else will see. A release tag that carries no record of who made it or when is a release tag you will wish you had annotated.

Pushing one you already have

Tags do not travel with commits. One you did not push as you made it is pushed on its own: Push…, under Tag actions — the button at the end of a selected tag’s row — or in the row’s context menu. It asks Push Tag first, and sends that tag and no other to the remote you push to. A local tag you made while trying something out does not travel just because you pushed a branch.

Deleting

Delete…, in the same two places, asks Delete Tag and deletes the local tag. As with branches, deleting a local tag does not delete the remote one.