Tag Commands

Mark important points in history with tags. Use them for releases, milestones, or any commit you want to easily reference later.

Quick Reference

dits tag                        # List all tags
dits tag v1.0.0                 # Create lightweight tag
dits tag -a v1.0.0 -m "msg"     # Create annotated tag
dits tag -d v1.0.0              # Delete tag
dits push origin v1.0.0         # Push specific tag
dits push origin --tags         # Push all tags

Tag Types

Lightweight Tags

Simple pointer to a commit. Like a branch that doesn't change.

dits tag v1.0.0

Annotated Tags (Recommended)

Full object with author, date, message, and optional signature.

dits tag -a v1.0.0 -m "Release"

Use Annotated Tags for Releases

Annotated tags store extra metadata (who, when, why) and are recommended for marking releases and milestones.

Creating Tags

Lightweight Tag

# Tag current commit
$ dits tag v1.0.0

# Tag specific commit
$ dits tag v0.9.0 abc1234

Annotated Tag

# Create annotated tag
$ dits tag -a v1.0.0 -m "Release 1.0.0 - Initial stable release"

# Tag opens editor for message
$ dits tag -a v1.0.0

# Tag specific commit
$ dits tag -a v0.9.0 -m "Beta release" abc1234

Signed Tags (GPG)

# Create signed tag
$ dits tag -s v1.0.0 -m "Signed release"

# Verify signed tag
$ dits tag -v v1.0.0
gpg: Signature made Mon Dec 11 10:30:00 2024
gpg: Good signature from "Your Name <you@example.com>"

Listing Tags

# List all tags
$ dits tag
v0.9.0
v1.0.0
v1.0.1
v1.1.0

# List with pattern
$ dits tag -l "v1.*"
v1.0.0
v1.0.1
v1.1.0

# List with details
$ dits tag -n
v1.0.0    Release 1.0.0 - Initial stable release
v1.0.1    Hotfix for login bug
v1.1.0    New video export feature

# Sort by version
$ dits tag --sort=-version:refname | head -5
v1.1.0
v1.0.1
v1.0.0
v0.9.0

# Show tag info
$ dits show v1.0.0
tag v1.0.0
Tagger: Your Name <you@example.com>
Date:   Mon Dec 11 10:30:00 2024

Release 1.0.0 - Initial stable release

commit abc1234...

Sharing Tags

# Push specific tag
$ dits push origin v1.0.0

# Push all tags
$ dits push origin --tags

# Push with new commits
$ dits push origin main --tags

# Fetch tags from remote
$ dits fetch --tags

# Delete remote tag
$ dits push origin --delete v1.0.0
# or
$ dits push origin :refs/tags/v1.0.0

Deleting Tags

# Delete local tag
$ dits tag -d v1.0.0
Deleted tag 'v1.0.0'

# Delete remote tag
$ dits push origin --delete v1.0.0

# Delete multiple local tags
$ dits tag -d v0.1.0 v0.2.0 v0.3.0

Checking Out Tags

# Checkout a tag (detached HEAD)
$ dits checkout v1.0.0
Note: switching to 'v1.0.0'.
You are in 'detached HEAD' state.

# Create branch from tag
$ dits checkout -b hotfix/v1.0.1 v1.0.0

# Compare current with tag
$ dits diff v1.0.0

Detached HEAD

Checking out a tag puts you in "detached HEAD" state. To make changes, create a new branch: dits checkout -b new-branch

Semantic Versioning

We recommend using semantic versioning for release tags:

MAJOR.MINOR.PATCH

MAJOR - Breaking/incompatible changes
MINOR - New features, backwards-compatible
PATCH - Bug fixes, backwards-compatible

Examples: v1.0.0, v1.0.1, v1.1.0, v2.0.0

Release Workflow

# 1. Ensure you're on main with latest changes
dits checkout main
dits pull origin main

# 2. Update version in package.json (or equivalent)
npm version 1.0.0

# 3. Create annotated tag
dits tag -a v1.0.0 -m "Release 1.0.0

Features:
- New video export
- Improved chunking
- P2P sync

Fixes:
- Fixed lock timeout
- Resolved cache corruption"

# 4. Push with tags
dits push origin main --tags

# 5. Verify on remote
dits ls-remote --tags origin

Related Commands

Branch Commands - Branch management
Log - View history
Remote Commands - Push/fetch