Documentation
¶
Overview ¶
Package goversion provides a library for managing semantic version bumps in Go projects.
It provides functionalities for:
- Reading and writing a version file that contains a version constant.
- Normalizing and parsing semantic version strings (ensuring a canonical "v" prefix).
- Bumping versions using standard keywords (e.g., major, minor, patch, premajor, preminor, prepatch, prerelease, and from-git) or setting an explicit version.
- Integrating with Git to stage changes, commit updates with the new version as the commit message (without the "v" prefix), and tag commits with the new version (prefixed with "v").
This library is designed to be used both as a standalone command-line tool via the provided CLI (in the cmd folder) and as a programmatic API to integrate version bumping into other Go programs.
Usage Example:
import (
"log"
"github.com/bcomnes/goversion/pkg"
)
func main() {
// Bump the version by "patch".
err := goversion.Run("pkg/version/version.go", "patch", []string{"pkg/version/version.go"})
if err != nil {
log.Fatalf("version bump failed: %v", err)
}
log.Println("Version bumped successfully!")
}
For additional details and API documentation, see https://pkg.go.dev/github.com/bcomnes/goversion.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var (
Version = "1.0.3"
)
Functions ¶
This section is empty.
Types ¶
type VersionMeta ¶
type VersionMeta struct {
OldVersion string // The version before bumping.
NewVersion string // The new version after bumping.
BumpType string // How the version was bumped (e.g. "major", "explicit", "from-git", etc.).
}
VersionMeta holds metadata about the version bump operation.
func DryRun ¶
func DryRun(versionFilePath string, versionArg string) (VersionMeta, error)
DryRun is a new function that simulates the version bump operation without writing any changes to disk or modifying the git repository. It returns the VersionMeta data that would be generated by a real bump.
func Run ¶
func Run(versionFilePath string, versionArg string, extraFiles []string) (VersionMeta, error)
Run is the main function for the goversion library. It accepts a path to the Go file containing a version declaration, a version argument (which can be one of the bump keywords or an explicit version), and a slice of extra files to include in the commit. Supported versionArg values are:
[<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]
It now returns metadata about the operation.
Example ¶
ExampleRun demonstrates how to use the Run function in a Git repository. It creates a temporary directory, initializes a Git repo, writes an initial version file (using escaped newline literals), stages and commits it, then changes the current working directory to that temporary repo before bumping the version with a "patch" directive (bumping 1.2.3 to 1.2.4). The updated file content is then printed out.
Save this file as pkg/example_test.go so it is included as a testable example.
// Create a temporary directory.
tmpDir, err := os.MkdirTemp("", "goversion_example")
if err != nil {
fmt.Println("failed to create temporary directory:", err)
return
}
defer os.RemoveAll(tmpDir)
// Initialize a new Git repository in tmpDir.
cmd := exec.Command("git", "init")
cmd.Dir = tmpDir
if output, err := cmd.CombinedOutput(); err != nil {
fmt.Println("failed to initialize git repository:", string(output), err)
return
}
// Configure Git user settings.
configCmds := [][]string{
{"git", "config", "user.email", "test@example.com"},
{"git", "config", "user.name", "Test User"},
}
for _, args := range configCmds {
cmd = exec.Command(args[0], args[1:]...)
cmd.Dir = tmpDir
if output, err := cmd.CombinedOutput(); err != nil {
fmt.Println("failed to configure git:", string(output), err)
return
}
}
// Change working directory to the temporary repository so that Git commands run correctly.
origDir, err := os.Getwd()
if err != nil {
fmt.Println("failed to get current working directory:", err)
return
}
if err := os.Chdir(tmpDir); err != nil {
fmt.Println("failed to change working directory:", err)
return
}
defer os.Chdir(origDir) // Restore original working directory when done.
// Define the path to the version file.
versionFile := filepath.Join(tmpDir, "version.go")
// Write an initial version file using escaped newline literals.
initialContent := "package version\n\nvar (\n\tVersion = \"1.2.3\"\n)\n"
err = os.WriteFile(versionFile, []byte(initialContent), 0644)
if err != nil {
fmt.Println("failed to write version file:", err)
return
}
// Stage and commit the initial version file.
cmd = exec.Command("git", "add", ".")
cmd.Dir = tmpDir
if output, err := cmd.CombinedOutput(); err != nil {
fmt.Println("failed to execute git add:", string(output), err)
return
}
cmd = exec.Command("git", "commit", "-m", "initial commit")
cmd.Dir = tmpDir
if output, err := cmd.CombinedOutput(); err != nil {
fmt.Println("failed to execute git commit:", string(output), err)
return
}
// Call Run to bump the version ("patch" will bump 1.2.3 to 1.2.4).
_, err = Run(versionFile, "patch", []string{versionFile})
if err != nil {
fmt.Println("error bumping version:", err)
return
}
// Read the updated version file.
newContent, err := os.ReadFile(versionFile)
if err != nil {
fmt.Println("failed to read version file:", err)
return
}
// Print the updated content.
fmt.Printf("%s", newContent)
Output: package version var ( Version = "1.2.4" )
Source Files