version

Overview ¶

Package version provides version information and build metadata for Hitch.

Overview ¶

This package manages Hitch's version information, including the version number, git commit hash, build time, and Go runtime information. It provides functions for accessing and formatting version data for display in the CLI and for programmatic version checks.

Version Variables ¶

Three variables are set at build time using ldflags:

var (
    Version   = "dev"      // Semantic version (e.g., "1.0.0")
    Commit    = "unknown"  // Git commit hash
    BuildTime = "unknown"  // Build timestamp
)

These variables are populated during the build process:

go build -ldflags="-X github.com/DoomedRamen/hitch/internal/version.Version=1.0.0 \
                    -X github.com/DoomedRamen/hitch/internal/version.Commit=$(git rev-parse HEAD) \
                    -X github.com/DoomedRamen/hitch/internal/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)"

Development Builds ¶

When variables aren't set (development builds), they default to:

• Version: "dev"
• Commit: "unknown"
• BuildTime: "unknown"

This allows running Hitch from source without special build flags.

Version Functions ¶

GetVersion():

version := version.GetVersion()
// Returns: "1.0.0" or "dev (development)"

Returns a simple version string suitable for display.

GetVersionString():

versionStr := version.GetVersionString()
// Returns: "v1.0.0, commit: abc1234, built: 2024-01-15T10:30:00Z, linux/amd64"

Returns a comprehensive version string with all build information.

GetVersionInfo():

info := version.GetVersionInfo()
// Returns: map[string]interface{}{
//     "version": "1.0.0",
//     "commit": "abc123...",
//     "build_time": "2024-01-15T10:30:00Z",
//     "go_version": "go1.21.5",
//     "go_os": "linux",
//     "go_arch": "amd64",
// }

Returns structured version information useful for programmatic access.

GetShortVersion():

short := version.GetShortVersion()
// Returns: "1.0.0" or "dev"

Returns a minimal version string suitable for compact display.

IsDevelopment():

if version.IsDevelopment() {
    fmt.Println("Running development build")
}

Checks if this is a development build (Version == "dev").

Usage in CLI ¶

The version package is used by the root command to display version info:

var rootCmd = &cobra.Command{
    Use:     "hitch",
    Short:   "Git workflow manager for multi-environment development",
    Version: version.GetVersionString(),
}

Users can then run:

$ hitch version
v1.0.0, commit: abc1234, built: 2024-01-15T10:30:00Z, linux/amd64

$ hitch --version
v1.0.0, commit: abc1234, built: 2024-01-15T10:30:00Z, linux/amd64

Build Process Integration ¶

In Makefile or build script:

VERSION := $(shell git describe --tags --always --dirty)
COMMIT := $(shell git rev-parse HEAD)
BUILD_TIME := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)

LDFLAGS := -ldflags "-X github.com/DoomedRamen/hitch/internal/version.Version=$(VERSION) \
                      -X github.com/DoomedRamen/hitch/internal/version.Commit=$(COMMIT) \
                      -X github.com/DoomedRamen/hitch/internal/version.BuildTime=$(BUILD_TIME)"

build:
    go build $(LDFLAGS) -o hitch ./cmd/hitch

Goreleaser Integration ¶

For automated releases with goreleaser:

# .goreleaser.yaml
builds:
  - main: ./cmd/hitch
    ldflags:
      - -s -w
      - -X github.com/DoomedRamen/hitch/internal/version.Version={{.Version}}
      - -X github.com/DoomedRamen/hitch/internal/version.Commit={{.Commit}}
      - -X github.com/DoomedRamen/hitch/internal/version.BuildTime={{.Date}}

Version String Formats ¶

Different formats for different contexts:

Short (GetShortVersion):

"1.0.0"

Simple (GetVersion):

"1.0.0" or "dev (development)"

Full (GetVersionString):

"v1.0.0, commit: abc1234, built: 2024-01-15T10:30:00Z, linux/amd64"

Structured (GetVersionInfo):

{
  "version": "1.0.0",
  "commit": "abc1234567890abcdef1234567890abcdef12345",
  "build_time": "2024-01-15T10:30:00Z",
  "go_version": "go1.21.5",
  "go_os": "linux",
  "go_arch": "amd64"
}

Runtime Information ¶

GetVersionInfo includes Go runtime details:

• go_version: Go version used to build (e.g., "go1.21.5")
• go_os: Operating system (e.g., "linux", "darwin", "windows")
• go_arch: Architecture (e.g., "amd64", "arm64")

This helps diagnose platform-specific issues.

Development vs Release Builds ¶

Development builds (no ldflags):

$ go run ./cmd/hitch version
dev (development)

$ hitch version
dev (development)

Release builds (with ldflags):

$ ./hitch version
v1.0.0, commit: abc1234, built: 2024-01-15T10:30:00Z, linux/amd64

Semantic Versioning ¶

Hitch follows semantic versioning (semver):

MAJOR.MINOR.PATCH

Examples:

• 1.0.0: Initial stable release
• 1.1.0: New features, backwards compatible
• 1.1.1: Bug fixes
• 2.0.0: Breaking changes

Git Describe Integration ¶

For automated version from git tags:

VERSION := $(shell git describe --tags --always --dirty)

This produces versions like:

• v1.0.0 (exact tag)
• v1.0.0-3-gabc1234 (3 commits after v1.0.0)
• v1.0.0-dirty (uncommitted changes)

Testing ¶

The package includes tests in version_test.go:

func TestGetVersion(t *testing.T) {
    v := GetVersion()
    if v == "" {
        t.Error("Version should not be empty")
    }
}

Tests verify:

• Functions return non-empty strings
• Development builds are detected correctly
• Version info includes expected fields
• String formatting is correct

Programmatic Version Checks ¶

Check version programmatically:

import "github.com/DoomedRamen/hitch/internal/version"

func checkVersion() {
    if version.IsDevelopment() {
        fmt.Println("⚠️  Running development build")
        fmt.Println("   Some features may be unstable")
        return
    }

    info := version.GetVersionInfo()
    fmt.Printf("Hitch %s\n", info["version"])
    fmt.Printf("Built: %s\n", info["build_time"])
}

User-Facing Display ¶

Format for user display:

fmt.Println("Hitch version:", version.GetVersion())
fmt.Println("Full details:", version.GetVersionString())

Output:

Hitch version: 1.0.0
Full details: v1.0.0, commit: abc1234, built: 2024-01-15T10:30:00Z, linux/amd64

CI/CD Integration ¶

In GitHub Actions:

• name: Build run: | VERSION=$(git describe --tags --always) COMMIT=$(git rev-parse HEAD) BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)

  go build -ldflags="-X github.com/DoomedRamen/hitch/internal/version.Version=$VERSION \ -X github.com/DoomedRamen/hitch/internal/version.Commit=$COMMIT \ -X github.com/DoomedRamen/hitch/internal/version.BuildTime=$BUILD_TIME" \ -o hitch ./cmd/hitch

Example: Complete Version Display ¶

func displayVersionInfo() {
    if version.IsDevelopment() {
        fmt.Println("🚧 Development Build")
        fmt.Println()
        fmt.Println("This is a development build of Hitch.")
        fmt.Println("For production use, install a released version.")
        return
    }

    info := version.GetVersionInfo()

    fmt.Println("Hitch - Git workflow manager")
    fmt.Println()
    fmt.Printf("Version:    %s\n", info["version"])
    fmt.Printf("Commit:     %s\n", info["commit"])
    fmt.Printf("Built:      %s\n", info["build_time"])
    fmt.Printf("Go version: %s\n", info["go_version"])
    fmt.Printf("Platform:   %s/%s\n", info["go_os"], info["go_arch"])
}

Output:

Hitch - Git workflow manager

Version:    1.0.0
Commit:     abc1234567890abcdef1234567890abcdef12345
Built:      2024-01-15T10:30:00Z
Go version: go1.21.5
Platform:   linux/amd64

Best Practices ¶

1. Always set version info in release builds
2. Use semantic versioning for releases
3. Include commit hash for traceability
4. Include build time for debugging
5. Use IsDevelopment() to show warnings
6. Display full version in --version output
7. Use short version in compact displays

This package provides complete version information management for Hitch, supporting both development workflows and production releases.