1 files changed, 45 insertions, 42 deletions

diff --git a/commands/version.go b/commands/version.go
index 189a2e350..ffa4a180a 100644
--- a/commands/version.go
+++ b/commands/version.go
@@ -1,63 +1,66 @@
 package commands
 
 import (
-	"runtime"
+	"log/slog"
 
 	"github.com/spf13/cobra"
 
 	"github.com/git-bug/git-bug/commands/execenv"
 )
 
-type versionOptions struct {
-	number bool
-	commit bool
-	all    bool
-}
+// TODO: 0.12.0: remove deprecated build vars
+var (
+	GitCommit   string
+	GitLastTag  string
+	GitExactTag string
+)
 
 func newVersionCommand(env *execenv.Env) *cobra.Command {
-	options := versionOptions{}
+	return &cobra.Command{
+		Use:     "version",
+		Short:   "Print version information",
+		Example: "git bug version",
+		Long: `
+Print version information.
 
-	cmd := &cobra.Command{
-		Use:   "version",
-		Short: "Show git-bug version information",
-		Run: func(cmd *cobra.Command, args []string) {
-			runVersion(env, options, cmd.Root())
-		},
-	}
+Format:
+  git-bug <version> [commit[/dirty]] <compiler version> <platform> <arch>
 
-	flags := cmd.Flags()
-	flags.SortFlags = false
+Format Description:
+  <version> may be one of:
+  	- A semantic version string, prefixed with a "v", e.g. v1.2.3
+  	- "undefined" (if not provided, or built with an invalid version string)
 
-	flags.BoolVarP(&options.number, "number", "n", false,
-		"Only show the version number",
-	)
-	flags.BoolVarP(&options.commit, "commit", "c", false,
-		"Only show the commit hash",
-	)
-	flags.BoolVarP(&options.all, "all", "a", false,
-		"Show all version information",
-	)
+  [commit], if present, is the commit hash that was checked out during the
+  build. This may be suffixed with '/dirty' if there were local file
+  modifications. This is indicative of your build being patched, or modified in
+  some way from the commit.
 
-	return cmd
-}
+  <compiler version> is the version of the go compiler used for the build.
 
-func runVersion(env *execenv.Env, opts versionOptions, root *cobra.Command) {
-	if opts.all {
-		env.Out.Printf("%s version: %s\n", execenv.RootCommandName, root.Version)
-		env.Out.Printf("System version: %s/%s\n", runtime.GOARCH, runtime.GOOS)
-		env.Out.Printf("Golang version: %s\n", runtime.Version())
-		return
-	}
+  <platform> is the target platform (GOOS).
 
-	if opts.number {
-		env.Out.Println(root.Version)
-		return
+  <arch> is the target architecture (GOARCH).
+`,
+		Run: func(cmd *cobra.Command, args []string) {
+			defer warnDeprecated()
+			env.Out.Printf("%s %s", execenv.RootCommandName, cmd.Root().Version)
+		},
 	}
+}
 
-	if opts.commit {
-		env.Out.Println(GitCommit)
-		return
+// warnDeprecated warns about deprecated build variables
+// TODO: 0.12.0: remove support for old build tags
+func warnDeprecated() {
+	msg := "please contact your package maintainer"
+	reason := "deprecated build variable"
+	if GitLastTag != "" {
+		slog.Warn(msg, "reason", reason, "name", "GitLastTag", "value", GitLastTag)
+	}
+	if GitExactTag != "" {
+		slog.Warn(msg, "reason", reason, "name", "GitExactTag", "value", GitExactTag)
+	}
+	if GitCommit != "" {
+		slog.Warn(msg, "reason", reason, "name", "GitCommit", "value", GitCommit)
 	}
-
-	env.Out.Printf("%s version: %s\n", execenv.RootCommandName, root.Version)
 }