tago

README

tago

Smart Git tag version management built with Golang.

---

CHINESE README

中文说明

Main Features

🏷️ Smart Tag Management: Auto create and bump semantic version tags in Git repositories
⚡ Version Base System: Configurable version increment mechanism (1/10/100)
🎯 Interactive Confirmation: When using low version base, asks before operations; high version base enables auto mode
🌍 Submodule Support: Independent tag management in main project and submodules
📋 Semantic Versioning: Follows v{major}.{minor}.{patch} format standards

Installation

go install github.com/go-mate/tago/cmd/tago@latest

Usage

Show tags

tago

output:

refs/tags/v0.0.0 Wed Feb 12 16:18:18 2025 +0700
refs/tags/v0.0.1 Thu Feb 13 16:43:08 2025 +0700
refs/tags/v0.0.2 Thu Feb 13 18:43:40 2025 +0700
refs/tags/v0.0.3 Wed Apr 30 15:18:56 2025 +0700
refs/tags/v0.0.4 Wed May 7 18:38:38 2025 +0700

Initialize Repo with First Tag

Create the first tag when no tags exist in the repo:

# Create v0.0.0 tag (default)
tago init

# Create custom version tag
tago init --major=1 --minor=0 --patch=0
tago init -a=0 -b=1 -c=0

The init command handles these scenarios:

• No tags exist: Creates new tag with interactive confirmation
• Different tag exists: Reports what tag exists and prevents execution
• Same tag exists at current commit: Skips creation and asks if you want to push
• Same tag exists at different commit: Reports commit mismatch and prevents execution

Example workflow:

# First time - creates tag
$ tago init
Create tag v0.0.0? (Y/n): Y
Push tag v0.0.0 to remote? (Y/n): Y
SUCCESS

# If tag exists at current commit - asks about push action
$ tago init
Tag v0.0.0 exists at current commit
Push tag v0.0.0 to remote? (Y/n): Y
SUCCESS

Bump Tag Version (Interactive Mode)

Bump from va.b.c to va.b.c+1 and push new tag with interactive confirmation:

tago bump

Output:

cd xxx && git push origin v0.0.5

Bump Tag Version (Auto Mode)

Bump from va.b.c to va.b.c+1 and push new tag without interactive confirmation:

tago bump -b=100

Output:

cd xxx && git push origin v0.0.5

Main Project Tag Management

When working in main project root DIR:

tago bump main
tago bump main -b=10

Submodule Tag Management

When working in submodule DIR (with path prefix):

cd submodule-dir
tago bump sub-module
tago bump sub-module -b=100

Requirements

• Git Repo: Must be run inside a valid Git repo
• Git Branch: Assumes main branch is named "main" (not "master")
• Tag Format: Tags must follow semantic versioning v{major}.{minor}.{patch} format

Version Base System

The version base (-b option) controls version increment mechanism:

• 0 and 1: Interactive mode, asks before each action
• ≥ 2: Auto mode, supports automatic version increment

Version Increment Examples

With version base 10:

• v1.2.9 → v1.3.0 (patch reaches base, advances to next minor)
• v1.9.8 → v1.9.9 (standard increment)
• v1.9.9 → v2.0.0 (minor reaches base, advances to next major)

Advanced Usage

Command Examples

# Show current tags
tago

# Bump tag (with confirmation)
tago bump

# Quick bump without confirmation
tago bump -b=100

# Main project tag bump
tago bump main -b=10

# Submodule tag bump (run from submodule DIR)
cd my-submodule
tago bump sub-module -b=10

Version Management Workflow

1. When development completes: Run tago to view current tags
2. Create new version: Run tago bump to upgrade version
3. Automation scenarios: Use tago bump -b=100 to skip confirmation
4. Multi-module projects: Use appropriate subcommands based on context

Core Capabilities

Smart Version Management

• Auto parse existing tag formats
• Support semantic versioning standards
• Handle version increment logic
• Validate Git repo status

Flexible Confirmation System

• Low version base: Interactive confirmation before each action
• High version base: Auto execution, suitable when scripting
• Simple and effective prompt messages
• Operation cancellation support

Multi-project Architecture Support

• Main project tags: v{major}.{minor}.{patch}
• Submodule tags: {path}/v{major}.{minor}.{patch}
• Path-aware tag management
• Git submodule compatible design

Troubleshooting

Common Issues

Issue: "no tag found in repo"

• Cause: No existing tags in the repo
• Solution: Use init command: tago init to create the first tag with interactive confirmation

Issue: "not in submodule path"

• Cause: Running tago bump sub-module from project root instead of submodule DIR
• Solution: Navigate to the submodule DIR before running the command

Issue: "tag format mismatch"

• Cause: Existing tag doesn't match required v{major}.{minor}.{patch} format
• Solution: Ensure tags follow semantic versioning format (e.g., v1.2.3, not v1.2 / 1.2.3)

Issue: "no matching tag found"

• Cause: No tags matching the expected pattern (e.g., looking at main project tags when just submodule tags exist)
• Solution: Create appropriate tag format based on command context (main vs sub-module)

Issue: Push fails with "origin does not seem to be a git repo"

• Cause: No remote repo configured
• Solution: Add remote: git remote add origin <url> and use -b=0 to skip auto-push

Tag Format Requirements

• Valid formats: v0.0.1, v1.2.3, v10.20.30
• Invalid formats: v1.2, 1.2.3, version-1.2.3, v1.2.x
• Submodule tags: mymodule/v1.2.3, path/to/module/v0.1.0

---

📄 License

MIT License - see LICENSE.

---

💬 Contact & Feedback

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Mistake reports? Open an issue on GitHub with reproduction steps
• 💡 Fresh ideas? Create an issue to discuss
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

---

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

---

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

---

GitHub Stars