feat: add comprehensive CLI version support (fixes #282) by robinbraemer · Pull Request #561 · minekube/gate

robinbraemer · 2025-09-04T14:43:37Z

Problem

Gate CLI lacked standard version support, making it difficult for users and operators to verify which version is running. This was requested by the Discord community and is essential for debugging and operational visibility.

Solution

CLI Version Command (Following Unix Conventions)

Add gate -V and gate --version commands (proper Unix convention)
Keep gate -v for verbosity (traditional Unix usage)
Resolve urfave/cli flag conflicts by customizing version flag behavior
Maintain backward compatibility with --verbosity flag

Startup Version Logging

Log Gate version at startup for operational visibility
Essential for debugging, support, and monitoring
Shows clearly in logs: starting Gate proxy {"version": "v0.54.1"}

Comprehensive Build Integration

GoReleaser: Set version via ldflags using {{.Version}} template
Makefile: Add make build target with proper git version detection
Dockerfile: Accept VERSION build arg and set via ldflags
CI Workflow: Pass version to Docker builds automatically
Version package: Export Version variable for ldflags access

Version Detection Logic

Uses robust git-based versioning:

# From git tags (preferred)
git describe --tags --always --dirty
# Output: v0.54.1-11-g8e6f33f-dirty

# Fallback format  
dev-{commit-hash}
# Output: dev-8e6f33f

Usage Examples

CLI Version Commands (Unix Convention)

$ gate -V           # Version (Unix convention)
gate version v0.54.1

$ gate --version    # Version (long form)
gate version v0.54.1

$ gate -v 2         # Verbosity (Unix convention)
$ gate --verbosity 2

Help Output

GLOBAL OPTIONS:
   --config value, -c value     config file (default: ./config.yml)
   --debug, -d                  Enable debug mode and highest log verbosity
   --verbosity value, -v value  The higher the verbosity the more logs are shown
   --version, -V                Show version information

Startup Logs

INFO    starting Gate proxy     {"version": "v0.54.1"}
INFO    logging verbosity       {"verbosity": 0}
INFO    using config file       {"config": "config.yml"}

Build Integration

# Local development
make build
# Building Gate version: v0.54.1-11-g8e6f33f-dirty

# Docker builds
docker build --build-arg VERSION=v0.54.1 .

# GoReleaser (automatic)
goreleaser build

Benefits

Correct Unix conventions - -V for version, -v for verbose
Operational visibility - Version logged at startup for debugging
Build integration - Consistent versioning across all build methods
User convenience - Easy version verification for support
No breaking changes - All existing flags still work
Proper flag management - No conflicts with urfave/cli defaults

Testing

CLI integration tests - Version display and Unix flag conventions
Build verification - Version properly set via ldflags
Startup logging - Version appears in startup logs
Cross-platform - Works across all supported platforms

Closes #282

Addresses community request from Discord (issue #282). **New Functionality:** - Add --version and -v flags to display Gate version - Automatically provided by urfave/cli framework - Shows version information set during build process **Flag Changes:** - Change verbosity flag alias from -v to --verbose to avoid conflict - Maintain backward compatibility with --verbosity full flag name - Version flag takes precedence as it's a standard CLI convention **Testing:** - Add comprehensive test suite for version functionality - Verify flag conflicts are resolved - Test version integration and help text display - Validate user agent version inclusion **Usage:** ```bash gate --version # Shows: gate version v1.2.3 gate -v # Same as above ``` Fixes #282

**CLI Version Command:** - Add --version and -v flags to Gate CLI - Resolve flag conflict by changing verbosity alias to --verbose - Maintain backward compatibility with full --verbosity flag **Version Logging:** - Log Gate version at CLI startup for operational visibility - Shows in logs: "starting Gate proxy {version: v0.54.1}" - Essential for debugging and support **Build Integration:** - Update .goreleaser.yml to set version.Version via ldflags - Add Makefile build target with proper version from git tags - Update Dockerfile to accept VERSION build arg - Update CI workflow to pass version to Docker builds - Export version.Version variable for ldflags access **Version Detection:** - Use git describe --tags --always --dirty for accurate versioning - Fallback to dev-{commit} format when no tags available - Consistent versioning across all build methods **Testing:** - Comprehensive test suite for CLI integration - Verify flag conflicts resolved - Test version display and user agent inclusion Fixes #282

**Proper Unix CLI Conventions:** - -V / --version for version information (not -v) - -v / --verbosity for verbosity level (traditional Unix usage) **Changes:** - Add custom version flag with -V alias following Unix standards - Keep -v for verbosity as per Unix tradition - Use app.HideVersion to avoid urfave/cli automatic flag conflicts - Update tests to verify correct flag behavior and Unix conventions **Flag Behavior:** ```bash gate -V # Show version (Unix convention) gate --version # Show version (long form) gate -v 2 # Set verbosity level (Unix convention) gate --verbosity 2 # Set verbosity level (long form) ``` This resolves flag conflicts and follows established Unix CLI patterns where -v typically means verbose and -V means version.

cloudflare-workers-and-pages · 2025-09-04T14:54:06Z

Deploying gate-minekube with Cloudflare Pages

Latest commit:	`4134a9c`
Status:	✅ Deploy successful!
Preview URL:	https://e7e8214c.gate-minekube.pages.dev
Branch Preview URL:	https://feat-add-version-command.gate-minekube.pages.dev

View logs

…ekube#561) * feat: add CLI version command support Addresses community request from Discord (issue minekube#282). **New Functionality:** - Add --version and -v flags to display Gate version - Automatically provided by urfave/cli framework - Shows version information set during build process **Flag Changes:** - Change verbosity flag alias from -v to --verbose to avoid conflict - Maintain backward compatibility with --verbosity full flag name - Version flag takes precedence as it's a standard CLI convention **Testing:** - Add comprehensive test suite for version functionality - Verify flag conflicts are resolved - Test version integration and help text display - Validate user agent version inclusion **Usage:** ```bash gate --version # Shows: gate version v1.2.3 gate -v # Same as above ``` Fixes minekube#282 * feat: comprehensive version support and build integration **CLI Version Command:** - Add --version and -v flags to Gate CLI - Resolve flag conflict by changing verbosity alias to --verbose - Maintain backward compatibility with full --verbosity flag **Version Logging:** - Log Gate version at CLI startup for operational visibility - Shows in logs: "starting Gate proxy {version: v0.54.1}" - Essential for debugging and support **Build Integration:** - Update .goreleaser.yml to set version.Version via ldflags - Add Makefile build target with proper version from git tags - Update Dockerfile to accept VERSION build arg - Update CI workflow to pass version to Docker builds - Export version.Version variable for ldflags access **Version Detection:** - Use git describe --tags --always --dirty for accurate versioning - Fallback to dev-{commit} format when no tags available - Consistent versioning across all build methods **Testing:** - Comprehensive test suite for CLI integration - Verify flag conflicts resolved - Test version display and user agent inclusion Fixes minekube#282 * fix: use correct Unix conventions for CLI flags **Proper Unix CLI Conventions:** - -V / --version for version information (not -v) - -v / --verbosity for verbosity level (traditional Unix usage) **Changes:** - Add custom version flag with -V alias following Unix standards - Keep -v for verbosity as per Unix tradition - Use app.HideVersion to avoid urfave/cli automatic flag conflicts - Update tests to verify correct flag behavior and Unix conventions **Flag Behavior:** ```bash gate -V # Show version (Unix convention) gate --version # Show version (long form) gate -v 2 # Set verbosity level (Unix convention) gate --verbosity 2 # Set verbosity level (long form) ``` This resolves flag conflicts and follows established Unix CLI patterns where -v typically means verbose and -V means version.

robinbraemer added 3 commits September 4, 2025 16:33

robinbraemer merged commit 34f103c into master Sep 4, 2025
6 of 7 checks passed

robinbraemer deleted the feat/add-version-command branch September 4, 2025 14:57

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add comprehensive CLI version support (fixes #282)#561

feat: add comprehensive CLI version support (fixes #282)#561
robinbraemer merged 3 commits intomasterfrom
feat/add-version-command

robinbraemer commented Sep 4, 2025 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages Bot commented Sep 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

robinbraemer commented Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

CLI Version Command (Following Unix Conventions)

Startup Version Logging

Comprehensive Build Integration

Version Detection Logic

Usage Examples

CLI Version Commands (Unix Convention)

Help Output

Startup Logs

Build Integration

Benefits

Testing

Uh oh!

cloudflare-workers-and-pages Bot commented Sep 4, 2025

Deploying gate-minekube with Cloudflare Pages

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

robinbraemer commented Sep 4, 2025 •

edited

Loading