Skip to main content

Overview

Git tags allow you to mark specific points in your repository’s history, typically for releases or significant milestones. Neo Git Graph provides full tag management capabilities through the graph interface.

Creating Tags

Tag Types

Git supports two types of tags:

Lightweight Tags

Simple pointer to a commit, like a branch that doesn’t change

Annotated Tags

Full objects with tagger name, email, date, and message

Creating a Tag

Tag any commit from the graph:
  1. Right-click on a commit
  2. Select “Add Tag”
  3. Choose tag type (lightweight or annotated)
  4. Enter tag name
  5. For annotated tags, provide a message

Implementation

// From dataSource.ts:245-260
public addTag(
  repo: string,
  tagName: string,
  commitHash: string,
  lightweight: boolean,
  message: string
) {
  let args = ["tag"];
  if (lightweight) {
    args.push(tagName);
  } else {
    args.push("-a", tagName, "-m", message);
  }
  args.push(commitHash);
  return this.runGitCommandSpawn(args, repo);
}
git tag <tag-name> <commit-hash>
Creates a simple reference to the commit.

Tag Naming Conventions

v1.0.0
v1.2.3
v2.0.0-beta.1
Recommended for software releases following semver.org
release-2026-03-01
snapshot-20260303
Useful for periodic snapshots or date-based releases
milestone-project-alpha
archive-before-refactor
stable-backup
Flexible naming for organizational needs
Tag names must follow Git reference naming rules:
  • No spaces or special characters like ~, ^, :, ?, *
  • Cannot start with a dot . or hyphen -
  • Cannot end with .lock

Deleting Tags

Local Tag Deletion

Remove a tag from your local repository:
// From dataSource.ts:262-264
public deleteTag(repo: string, tagName: string) {
  return this.runGitCommand("tag -d " + escapeRefName(tagName), repo);
}

Deletion Workflow

1

Locate Tag

Find the tag in the graph (displayed on the commit it points to)
2

Open Context Menu

Right-click on the tag name
3

Select Delete

Choose “Delete Tag” from the menu
4

Confirm

Confirm the deletion in the dialog
Deleting a tag only removes the local reference. The commit remains in the repository.

Deleting Remote Tags

Git Graph only deletes local tags. To delete a remote tag, use the terminal:
git push origin --delete <tag-name>

Pushing Tags

Push to Remote

Share tags with your team by pushing to the remote repository:
// From dataSource.ts:266-268
public pushTag(repo: string, tagName: string) {
  return this.runGitCommand("push origin " + escapeRefName(tagName), repo);
}

Push Workflow

  1. Right-click on a tag in the graph
  2. Select “Push Tag”
  3. Tag is pushed to the origin remote
  4. Success/error message is displayed
git push origin <tag-name>
Git Graph pushes one tag at a time. To push all tags, use the Git terminal command git push origin --tags.

Push Errors

Common errors when pushing tags:
error: dst ref already exists  
Remote already has a tag with this name. Either:
  • Delete remote tag first: git push origin :refs/tags/<tag-name>
  • Use a different tag name
  • Force push (not recommended): git push --force origin <tag-name>
error: authentication failed
Configure Git credentials for the remote repository
error: No such remote 'origin'
Add a remote: git remote add origin <url>

Tag Visualization

Graph Display

Tags appear in the graph as references on commits:
  • Location: Adjacent to branch names on the commit node
  • Icon: Tag icon distinguishes them from branches
  • Color: Uses distinct styling from branch references
  • Sorting: Tags are sorted alphabetically when multiple tags point to the same commit

Tag Reference Types

The graph displays tag information using Git’s ref system:
// From dataSource.ts:349-354
else if (ref.startsWith("refs/tags/")) {
  refData.refs.push({
    hash: hash,
    name: ref.endsWith("^{}") 
      ? ref.substring(10, ref.length - 3)  // Annotated tag
      : ref.substring(10),                 // Lightweight tag
    type: "tag"
  });
}
Displayed as refs/tags/<name> - direct reference to commit

Context Menu Actions

Right-clicking a tag provides these options:

Checkout Tag

Checkout the commit the tag points to (detached HEAD)

Delete Tag

Remove the tag from local repository

Push Tag

Push the tag to origin remote

Copy Tag Name

Copy tag name to clipboard

Tag Commands via Message Protocol

Request/Response Flow

Tag operations use a message-based protocol:
// From types.ts:92-103
export interface RequestAddTag {
  command: "addTag";
  repo: string;
  commitHash: string;
  tagName: string;
  lightweight: boolean;
  message: string;
}

export interface ResponseAddTag {
  command: "addTag";
  status: GitCommandStatus;  // null on success, error string on failure
}

Response Handling

// From gitGraphView.ts:136-146
case "addTag":
  this.sendMessage({
    command: "addTag",
    status: await this.dataSource.addTag(
      msg.repo,
      msg.tagName,
      msg.commitHash,
      msg.lightweight,
      msg.message
    )
  });
  break;
All tag operations are asynchronous and provide success/failure feedback through the message protocol.

Best Practices

When to Use Tags

v1.0.0 - Initial release
v1.1.0 - Feature update
v1.1.1 - Bug fix release
Tag every public release for easy reference and checkout
milestone-mvp
beta-release
production-ready
Mark significant project milestones
archive-old-api
backup-before-migration
pre-refactor-snapshot
Create recovery points before major changes

Lightweight vs Annotated

  • Temporary markers
  • Personal bookmarks
  • Quick local references
  • Private development tags

Tag Message Format

For annotated tags, write clear, informative messages:
Release v1.2.0

New Features:
- Added user authentication
- Improved performance by 30%
- Dark mode support

Bug Fixes:
- Fixed memory leak in data processing
- Corrected timezone handling

Branch Operations

Manage branches alongside tags

Commit Details

View full commit information for tagged commits

Common Workflows

Release Tagging

1

Verify Commit

Ensure the release commit is correct and builds successfully
2

Create Annotated Tag

Right-click commit → Add Tag → Choose “Annotated”
3

Write Release Notes

Include version number, features, fixes, and breaking changes
4

Push to Remote

Right-click tag → Push Tag to share with team
5

Create GitHub Release

Use GitHub UI to create release from the tag

Moving Tags

Git doesn’t support moving tags directly. To “move” a tag:
  1. Delete the old tag: git tag -d <tag-name>
  2. Create new tag at desired commit
  3. Force push if already on remote: git push origin <tag-name> --force
This is not recommended for public tags as it can cause issues for other users.

Build docs developers (and LLMs) love