Skip to content

README.md

Latest commit

 

History

History
294 lines (209 loc) · 9.03 KB

README.md

File metadata and controls

294 lines (209 loc) · 9.03 KB

GitHub Workflow Status (branch) GoDoc Coverage Status Supported Go Versions GitHub Release Go Report Card

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/yylego/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

Stargazers