diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2487242..940cd84 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -38,7 +38,7 @@ jobs: mkdir -p "$DEST" ./binscripts/gvm-installer "${{ github.sha }}" "$DEST" test -f "$DEST/gvm/VERSION" - grep -q '1.1.0' "$DEST/gvm/VERSION" + grep -q '1.2.0' "$DEST/gvm/VERSION" echo "dest=$DEST" >> "$GITHUB_OUTPUT" ls -la "$DEST/gvm/scripts" diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 606c1f2..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,51 +0,0 @@ -# gvm2 agent guide - -Community reboot of [moovweb/gvm](https://github.com/moovweb/gvm). CLI command stays `gvm`; install dir stays `~/.gvm` for drop-in compatibility. Repo/product name is **gvm2**. - -## Layout - -| Path | Role | -|------|------| -| `binscripts/gvm-installer` | Curl / CI installer (clones into `~/.gvm`) | -| `scripts/` | Commands (`install`, `list`, …) and helpers under `function/` / `env/` | -| `scripts/env/cd` | Shell `cd` override for `.go-version` / `.go-pkgset` auto-switch | -| `tests/` | `tf` comment tests; `tests/scenario/` are isolated installs | - -## Commands - -```bash -# Local install into a temp dir (same shape as CI) -./binscripts/gvm-installer "$(git rev-parse --abbrev-ref HEAD)" /tmp/gvm2-test - -# Run suite (requires Ruby gem `tf`) -gem install tf -v '>=0.4.1' -rake default # comment tests -rake scenario # scenario installs -``` - -Smoke after sourcing: - -```bash -source /tmp/gvm2-test/gvm/scripts/gvm -gvm install go1.22.12 -B -gvm use go1.22.12 -mkdir -p "/tmp/dir with spaces" && cd "/tmp/dir with spaces" -``` - -Set `GVM_NO_CD=1` before sourcing to skip the `cd` hook (performance / autofs). - -## Issue triage labels - -| Label | Use | -|-------|-----| -| `p0-shell` | `cd`, PATH, zsh / hexdump | -| `p1-bootstrap` | Install / bootstrap without existing Go | -| `p2-docs` | Docs / UX | -| `upstream-pr` | Tracking a moovweb/gvm PR | -| `wontfix` | Out of scope for gvm2 | - -## Conventions - -- Conventional Commits; no AI co-author trailers. -- Prefer binary install (`-B` / auto prefer-binary) over documenting go1.4 chains. -- Do not rename the `gvm` CLI or `~/.gvm` path without an explicit migration plan. diff --git a/ChangeLog b/ChangeLog index d548ff6..b38f228 100644 --- a/ChangeLog +++ b/ChangeLog @@ -5,6 +5,23 @@ All notable changes to gvm2 are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/). +## [1.2.0] - 2026-07-14 + +### Added + +- `gvm listall` annotations for `latest` / `beta` / `rc` (moovweb/gvm#516). +- `gvm listall --latest` and `--porcelain` for nvm-style / script workflows. +- README quick-start and command table aimed at easier onboarding (moovweb/gvm#517). + +### Fixed + +- README status banner typo ("ustable" → restore "rough edges" wording). + +### Changed + +- Fresh-install locale prompt mentions `gvm listall --latest`. +- Remove `AGENTS.md` from the repo (agent guidance belongs in Cursor User Rules, not GitHub). + ## [1.1.0] - 2026-07-13 ### Added @@ -14,7 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/). - `gvm list --porcelain` and `gvm pkgset list --porcelain` for machine-readable output. - `GVM_NO_CD=1` to disable the `cd` auto-switch hook. - GitHub Actions CI (Ubuntu/macOS, bash/zsh smoke). -- Project `AGENTS.md` and issue triage labels (`p0-shell`, `p1-bootstrap`, …). +- Issue triage labels (`p0-shell`, `p1-bootstrap`, …). ### Fixed diff --git a/README.md b/README.md index 5387e9e..319abe1 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,42 @@ # gvm2 -> **Status: stable for daily use (v1.1.0)** +> **Status: stable for daily use (v1.2.0)** > > gvm2 is a community reboot of the Go Version Manager. Please file bugs and > contributions against this repository. Production use is supported for the > install and shell-integration paths covered by CI; advanced pkgset workflows -> may still be ustable. +> may still have rough edges. + +## Quick start + +Install gvm2, then install and select a Go version (binary install is preferred +on a fresh machine): + +```bash +bash < <(curl -s -S -L https://raw.githubusercontent.com/brianrobt/gvm2/master/binscripts/gvm-installer) +source ~/.gvm/scripts/gvm + +gvm install go1.22.12 # or: gvm install "$(gvm listall --latest)" +gvm use go1.22.12 --default +go version +``` + +Common commands (nvm-style workflow): + +| Goal | Command | +|------|---------| +| List available versions | `gvm listall` | +| Latest stable name only | `gvm listall --latest` | +| Install a version | `gvm install go1.22.12` | +| Switch version | `gvm use go1.22.12` | +| List installed versions | `gvm list` | +| Per-directory auto-switch | commit a `.go-version` (and optional `.go-pkgset`) | + +`gvm listall` annotates `latest`, `beta`, and `rc` (Go has no official LTS). Use +`gvm listall --porcelain` for script-friendly names only. + +Set `GVM_NO_CD=1` before sourcing gvm to disable the `cd` auto-switch hook +(performance / autofs). ## About this reboot @@ -31,73 +62,71 @@ triage groups the backlog into these priorities: |----------|------|----------|----------------| | P0 | Shell integration (`cd`, PATH, zsh) | [#527](https://github.com/moovweb/gvm/issues/527), [#528](https://github.com/moovweb/gvm/issues/528), [#515](https://github.com/moovweb/gvm/issues/515) | Fixed in 1.1.0 | | P1 | Install / bootstrap | [#530](https://github.com/moovweb/gvm/issues/530), [#480](https://github.com/moovweb/gvm/issues/480) | Fixed in 1.1.0 | -| P2 | UX / docs / ergonomics | [#517](https://github.com/moovweb/gvm/issues/517), [#516](https://github.com/moovweb/gvm/issues/516) | Planned | +| P2 | UX / docs / ergonomics | [#517](https://github.com/moovweb/gvm/issues/517), [#516](https://github.com/moovweb/gvm/issues/516) | Fixed in 1.2.0 ([#4](https://github.com/brianrobt/gvm2/issues/4)) | | P3 | Features (progress bars, worktrees, auto-detect `go.mod`) | [#514](https://github.com/moovweb/gvm/issues/514), [#523](https://github.com/moovweb/gvm/issues/523) | Backlog | Tracked here: [brianrobt/gvm2/issues](https://github.com/brianrobt/gvm2/issues). Pull requests and other contributions are very much appreciated. -GVM provides an interface to manage Go versions. +## Features -Features -======== * Install/Uninstall Go versions with `gvm install [tag]` where tag is "go1.22.12", "go1", "weekly.2011-11-08", or "tip" +* List available versions with `gvm listall` (annotations + `--latest` / `--porcelain`) * List added/removed files in GOROOT with `gvm diff` * Manage GOPATHs with `gvm pkgset [create/use/delete] [name]`. Use `--local` as `name` to manage repository under local path (`/path/to/repo/.gvm_local`). -* List latest release tags with `gvm listall`. Use `--all` to list weekly as well. * Cache a clean copy of the latest Go source for multiple version installs. * Link project directories into GOPATH -* Optional `GVM_NO_CD=1` to disable the `cd` auto-switch hook +* Auto-switch on `cd` via `.go-version` / `.go-pkgset` (optional `GVM_NO_CD=1` to disable) + +## Background -Background -========== When we started developing in Go mismatched dependencies and API changes plagued our build process and made it extremely difficult to merge with other peoples changes. After nuking my entire GOROOT several times and rebuilding I decided to come up with a tool to oversee the process. It eventually evolved into what gvm is today. -Installing -========== +## Installing To install: -1. Install [Bison](https://www.gnu.org/software/bison/) (needed for source builds): +1. Install [Bison](https://www.gnu.org/software/bison/) (needed for source builds): - ``` - sudo apt-get install bison - ``` + ```bash + sudo apt-get install bison + ``` -1. Install gvm2: +2. Install gvm2: - ``` - bash < <(curl -s -S -L https://raw.githubusercontent.com/brianrobt/gvm2/master/binscripts/gvm-installer) - ``` + ```bash + bash < <(curl -s -S -L https://raw.githubusercontent.com/brianrobt/gvm2/master/binscripts/gvm-installer) + ``` -Or if you are using zsh just change `bash` with `zsh` +Or if you are using zsh just change `bash` with `zsh`. -Installing Go -============= +## Installing Go On a machine with no Go installed, prefer a binary install (default when no `go` is on `PATH`): -``` +```bash gvm install go1.22.12 gvm use go1.22.12 [--default] ``` -Once this is done Go will be in the path and ready to use. $GOROOT and $GOPATH are set automatically. +Once this is done Go will be in the path and ready to use. `$GOROOT` and `$GOPATH` are set automatically. Additional options can be specified when installing Go: - Usage: gvm install [version] [options] - -s, --source=SOURCE Install Go from specified source. - -n, --name=NAME Override the default name for this version. - -pb, --with-protobuf Install Go protocol buffers. - -b, --with-build-tools Install package build tools. - -B, --binary Only install from binary. - --prefer-binary Attempt a binary install, falling back to source. - -h, --help Display this message. +``` +Usage: gvm install [version] [options] + -s, --source=SOURCE Install Go from specified source. + -n, --name=NAME Override the default name for this version. + -pb, --with-protobuf Install Go protocol buffers. + -b, --with-build-tools Install package build tools. + -B, --binary Only install from binary. + --prefer-binary Attempt a binary install, falling back to source. + -h, --help Display this message. +``` ### Compiling from source (Go 1.5+) @@ -115,57 +144,63 @@ binary to bootstrap source installations on ARM as well when needed. [compiler_note]: https://docs.google.com/document/d/1OaatvGhEAq7VseQ9kkavxKNAfepWy2yhPUBs96FGV28/edit -List Go Versions -================ -To list all installed Go versions (The current version is prefixed with "=>"): +## List Go Versions - gvm list +To list all installed Go versions (the current version is prefixed with `=>`): -To list all Go versions available for download: +```bash +gvm list +``` - gvm listall +To list Go versions available for download (annotated with `latest` / `beta` / `rc`): + +```bash +gvm listall +gvm listall --latest # print only the latest stable tag +gvm listall --porcelain # names only, for scripts +``` + +## Uninstalling -Uninstalling -============ To completely remove gvm and all installed Go versions and packages: - gvm implode +```bash +gvm implode +``` If that doesn't work see the troubleshooting steps at the bottom of this page. -Mac OS X Requirements -==================== - * Install Xcode Command Line Tools from the App Store. +## Mac OS X Requirements -``` +* Install Xcode Command Line Tools from the App Store. + +```bash xcode-select --install ``` -Linux Requirements -================== +## Linux Requirements + +### Debian/Ubuntu + +```bash +sudo apt-get install curl git make binutils bison gcc build-essential +``` -Debian/Ubuntu -================== - sudo apt-get install curl git make binutils bison gcc build-essential +### Redhat/Centos -Redhat/Centos -================== +```bash +sudo yum install curl git make bison gcc glibc-devel +``` - sudo yum install curl - sudo yum install git - sudo yum install make - sudo yum install bison - sudo yum install gcc - sudo yum install glibc-devel +## FreeBSD Requirements -FreeBSD Requirements -==================== +```bash +sudo pkg_add -r bash +sudo pkg_add -r git +``` - sudo pkg_add -r bash - sudo pkg_add -r git +## Vendoring Native Code and Dependencies -Vendoring Native Code and Dependencies -================================================== GVM supports vendoring package set-specific native code and related dependencies, which is useful if you need to qualify a new configuration or version of one of these dependencies against a last-known-good version @@ -176,43 +211,45 @@ As a convenience matter, GVM will furnish the following environment variables to aid in this manner if you want to decouple your work from what the operating system provides: -1. ``${GVM_OVERLAY_PREFIX}`` functions in a manner akin to a root directory - hierarchy suitable for auto{conf,make,tools} where it could be passed in - to ``./configure --prefix=${GVM_OVERLAY_PREFIX}`` and not conflict with any - existing operating system artifacts and hermetically be used by your - workspace. This is suitable to use with ``C{PP,XX}FLAGS and LDFLAGS``, but you will have - to manage these yourself, since each tool that uses them is different. +1. `${GVM_OVERLAY_PREFIX}` functions in a manner akin to a root directory + hierarchy suitable for auto{conf,make,tools} where it could be passed in + to `./configure --prefix=${GVM_OVERLAY_PREFIX}` and not conflict with any + existing operating system artifacts and hermetically be used by your + workspace. This is suitable to use with `C{PP,XX}FLAGS` and `LDFLAGS`, but you will have + to manage these yourself, since each tool that uses them is different. -2. ``${PATH}`` includes ``${GVM_OVERLAY_PREFIX}/bin`` so that any tools you - manually install will reside there, available for you. +2. `${PATH}` includes `${GVM_OVERLAY_PREFIX}/bin` so that any tools you + manually install will reside there, available for you. -3. ``${LD_LIBRARY_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib`` so that any - runtime library searching can be fulfilled there on FreeBSD and Linux. +3. `${LD_LIBRARY_PATH}` includes `${GVM_OVERLAY_PREFIX}/lib` so that any + runtime library searching can be fulfilled there on FreeBSD and Linux. -4. ``${DYLD_LIBRARY_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib`` so that any - runtime library searching can be fulfilled there on Mac OS X. +4. `${DYLD_LIBRARY_PATH}` includes `${GVM_OVERLAY_PREFIX}/lib` so that any + runtime library searching can be fulfilled there on Mac OS X. -5. ``${PKG_CONFIG_PATH}`` includes ``${GVM_OVERLAY_PREFIX}/lib/pkgconfig`` so - that ``pkg-config`` can automatically resolve any vendored dependencies. +5. `${PKG_CONFIG_PATH}` includes `${GVM_OVERLAY_PREFIX}/lib/pkgconfig` so + that `pkg-config` can automatically resolve any vendored dependencies. Recipe for success: - gvm use go1.22.12 - gvm pkgset use current-known-good - # Let's assume that this includes some C headers and native libraries, which - # Go's CGO facility wraps for us. Let's assume that these native - # dependencies are at version V. - gvm pkgset create trial-next-version - # Let's assume that V+1 has come along and you want to safely trial it in - # your workspace. - gvm pkgset use trial-next-version - # Do your work here replicating current-known-good from above, but install - # V+1 into ${GVM_OVERLAY_PREFIX}. - -See examples/native for a working example. - -Troubleshooting -=============== +```bash +gvm use go1.22.12 +gvm pkgset use current-known-good +# Let's assume that this includes some C headers and native libraries, which +# Go's CGO facility wraps for us. Let's assume that these native +# dependencies are at version V. +gvm pkgset create trial-next-version +# Let's assume that V+1 has come along and you want to safely trial it in +# your workspace. +gvm pkgset use trial-next-version +# Do your work here replicating current-known-good from above, but install +# V+1 into ${GVM_OVERLAY_PREFIX}. +``` + +See `examples/native` for a working example. + +## Troubleshooting + If gvm's state gets mixed up, `rm -rf ~/.gvm` removes it completely. Set `GVM_NO_CD=1` before sourcing gvm if the `cd` hook conflicts with autofs or is too slow for your environment. diff --git a/VERSION b/VERSION index 9084fa2..26aaba0 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.1.0 +1.2.0 diff --git a/locales/en-US_go_install_prompt.txt b/locales/en-US_go_install_prompt.txt index 24c8b3f..fab0fb8 100644 --- a/locales/en-US_go_install_prompt.txt +++ b/locales/en-US_go_install_prompt.txt @@ -1,8 +1,9 @@ It doesn't look like Go has been installed. Follow these steps to begin: - 1) Use 'gvm listall' to select a go version + 1) Use 'gvm listall' (or 'gvm listall --latest') to select a go version 2) Use 'gvm install ' (binary preferred on a fresh machine) 3) Then use 'cd .' or 'gvm use '. Example: gvm install go1.22.12 + gvm install "$(gvm listall --latest)" (Source builds auto-bootstrap a binary compiler when needed.) diff --git a/scripts/listall b/scripts/listall index 8a23759..af8cbf4 100755 --- a/scripts/listall +++ b/scripts/listall @@ -3,17 +3,40 @@ function show_usage() { echo "Usage: gvm listall [options]" - echo " -a, --all List all tags." + echo " -a, --all List all tags (including weekly/tip)." + echo " -A, --annotate Annotate versions (default for human output)." + echo " -p, --porcelain Machine-readable names only (no header/annotations)." + echo " --latest Print the latest stable go1.x.y and exit." echo " -h, --help Display this message." + echo + echo "Annotations (Go has no official LTS channel):" + echo " latest Highest stable go1.x.y" + echo " beta Pre-release beta" + echo " rc Release candidate" } +tag_filter="release" +porcelain=false +annotate=true +latest_only=false + function read_command_line() { - tag_filter="release" for i in "$@"; do case $i in -a|--all) tag_filter="" ;; + -A|--annotate) + annotate=true + porcelain=false + ;; + -p|--porcelain) + porcelain=true + annotate=false + ;; + --latest) + latest_only=true + ;; -h|--help*) show_usage exit 0 @@ -27,25 +50,91 @@ function read_command_line() { done } +# True when tag is a stable go1.x / go1.x.y (excludes beta/rc). +function is_stable_go() { + [[ "$1" =~ ^go[0-9]+(\.[0-9]+)+$ ]] +} + +function version_kind() { + local v=$1 + case "$v" in + *beta*) echo "beta" ;; + *rc*) echo "rc" ;; + *) + if is_stable_go "$v"; then + echo "stable" + else + echo "" + fi + ;; + esac +} + read_command_line "$@" -echo -display_message "gvm gos (available)" -echo -versions=$(git ls-remote -t https://github.com/golang/go | awk -F/ '{ print $NF }' | $SORT_PATH) -if [[ $? -ne 0 ]]; then +if ! versions=$(git ls-remote -t https://github.com/golang/go | awk -F/ '{ print $NF }'); then display_fatal "Failed to get version list from Google" fi + +filtered="" for version in $versions; do if [[ "$tag_filter" == "release" ]]; then - if [[ "${version:0:7}" == "release" ]]; then - echo " $version" - elif [[ "${version:0:3}" == "go1" ]]; then - echo " $version" + if [[ "${version:0:7}" == "release" ]] || [[ "${version:0:3}" == "go1" ]]; then + filtered+="$version"$'\n' + fi + else + filtered+="$version"$'\n' + fi +done + +sorted=$(printf '%s' "$filtered" | $SORT_PATH -V) + +latest_stable="" +while IFS= read -r version; do + [[ -z "$version" ]] && continue + if is_stable_go "$version"; then + latest_stable=$version + fi +done <<< "$sorted" + +if [[ "$latest_only" == true ]]; then + if [[ -z "$latest_stable" ]]; then + display_fatal "Could not determine latest stable Go version" + fi + echo "$latest_stable" + exit 0 +fi + +if [[ "$porcelain" != true ]]; then + echo + display_message "gvm gos (available)" + echo +fi + +while IFS= read -r version; do + [[ -z "$version" ]] && continue + if [[ "$annotate" == true ]]; then + kind=$(version_kind "$version") + note="" + case "$kind" in + beta) note="beta" ;; + rc) note="rc" ;; + stable) + if [[ "$version" == "$latest_stable" ]]; then + note="latest" + fi + ;; + esac + if [[ -n "$note" ]]; then + printf ' %-16s # %s\n' "$version" "$note" + else + printf ' %s\n' "$version" fi else - echo " $version" + printf ' %s\n' "$version" fi -done | sort -V -echo +done <<< "$sorted" +if [[ "$porcelain" != true ]]; then + echo +fi diff --git a/tests/gvm_listall_comment_test.sh b/tests/gvm_listall_comment_test.sh index 71071d5..bf66217 100644 --- a/tests/gvm_listall_comment_test.sh +++ b/tests/gvm_listall_comment_test.sh @@ -1 +1,4 @@ gvm listall #status=0 +gvm listall --latest #status=0; match=/go1\./ +gvm listall --porcelain #status=0; match=/go1/ +gvm listall -h #status=0; match=/--latest/