Disclaimer: Based on Google Gemini-Pro prompts!

Managing version numbers can get messy when working solo. If you accidentally created development branches named after version numbers (like v0.1.0) or mixed up your tag formats, you can easily clean up your history and establish a friction-free release workflow.

The Goal

Convert version branches into permanent Git tags, format historical versions cleanly (v0.0.1 instead of v0.1), and establish a streamlined process for future releases.

Troubleshooting: “fatal: Failed to resolve as a valid ref”

If you attempt to swap tags and see this error:

❯ git tag v0.1 v0.0.2
fatal: Failed to resolve 'v0.0.2' as a valid ref.

This happens because Git creates tags using the syntax: git tag <new-tag> <old-target>. The error triggers when the second argument does not exist in your history yet. To fix it, ensure your existing tag is placed at the end of the command.

Phase 1: Convert Version Branches into Tags

Run these commands to create tags at the exact tip of your version branches, then delete the obsolete branches.

# 1. Pull down all remote data
git fetch --all

# 2. Tag the tips of your branches
git tag v0.1.0 v0.1.0
git tag v0.1.1 v0.1.1

# 3. Safely delete the local branches
git branch -d v0.1.0
git branch -d v0.1.1

# 4. Remove the branches from GitHub
git push origin --delete v0.1.0
git push origin --delete v0.1.1

Phase 2: Standardize Historical Tag Formats

Correct your old version tags to match a three-digit semantic versioning layout.

# 1. Target the old tag to spawn the new formatted tag
git tag v0.0.1 v0.1
git tag v0.0.2 v0.2

# 2. Delete the old, improperly formatted tags locally
git tag -d v0.1 v0.2

# 3. Delete the old tags from GitHub
git push origin --delete v0.1 v0.2

Phase 3: Publish the New Tag Timeline

Push all your newly minted local tags up to GitHub in one command:

git push origin --tags

Future Proofing: The Solo Developer Release Workflow

When you are the sole developer on a project, you do not need a new branch for every release. Keep your development on main and use tags to mark milestones.

When your code on main is ready for a release, follow these three steps:

  1. Tag your code: Add a release marker to your current commit on main.
    git tag -a v0.2.0 -m "Release version 0.2.0"
  2. Push the tag: Send the tag to GitHub.
    git push origin v0.2.0
  3. Publish on GitHub: Navigate to your GitHub repository’s Releases page, target your newly pushed tag, and click Draft a new release to package your code.