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.
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:
Right-click on a commit
Select “Add Tag”
Choose tag type (lightweight or annotated)
Enter tag name
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 );
}
Lightweight Tag
Annotated Tag
git tag < tag-nam e > < commit-has h >
Creates a simple reference to the commit. git tag -a < tag-nam e > -m "<message>" < commit-has h >
Creates a full tag object with metadata and message.
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
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
Locate Tag
Find the tag in the graph (displayed on the commit it points to)
Open Context Menu
Right-click on the tag name
Select Delete
Choose “Delete Tag” from the menu
Confirm
Confirm the deletion in the dialog
Deleting a tag only removes the local reference. The commit remains in the repository.
Git Graph only deletes local tags. To delete a remote tag, use the terminal: git push origin --delete < tag-nam e >
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
Right-click on a tag in the graph
Select “Push Tag”
Tag is pushed to the origin remote
Success/error message is displayed
Single Tag
All Tags (Terminal)
git push origin < tag-nam e >
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
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"
});
}
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
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
Use Lightweight For
Use Annotated For
Temporary markers
Personal bookmarks
Quick local references
Private development tags
Public releases
Official milestones
Team-shared references
Tags requiring documentation
Annotated tags include:
Tagger name and email
Creation date
Message/description
Can be GPG signed
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
Verify Commit
Ensure the release commit is correct and builds successfully
Create Annotated Tag
Right-click commit → Add Tag → Choose “Annotated”
Write Release Notes
Include version number, features, fixes, and breaking changes
Push to Remote
Right-click tag → Push Tag to share with team
Create GitHub Release
Use GitHub UI to create release from the tag
Git doesn’t support moving tags directly. To “move” a tag:
Delete the old tag: git tag -d <tag-name>
Create new tag at desired commit
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.