Skip to content

docs: align update examples with the v0.2.0 release #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
christiangda merged 1 commit into from
Sep 19, 2026
Merged

docs: align update examples with the v0.2.0 release #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,28 +144,28 @@ It looks up the newest release, shows a checklist and the plan, asks for confirm
```text
$ machineid update
Checking for updates…
✓ current version v0.2.0
✓ current version v0.1.3
✓ running binary /usr/local/bin/machineid
✓ platform supported darwin/arm64
✓ latest release v0.3.0 (live, 4 of 5 checks left this hour)
✓ latest release v0.2.0 (live, 4 of 5 checks left this hour)
✓ install target /usr/local/bin (running as root)

→ Updating machineid v0.2.0 → v0.3.0 using the signed macOS package
→ Updating machineid v0.1.3 → v0.2.0 using the signed macOS package

Update machineid now? [y/N] y
downloading machineid-darwin-universal.pkg…
✓ SHA-256 verified
✓ pkgutil: Developer ID Installer: SlashDevOps
✓ installed to /usr/local/bin

✅ Updated to v0.3.0
✅ Updated to v0.2.0
```

| Flag | Meaning |
|------|---------|
| `-check` | Report what would happen and change nothing. Served from the cache when it is under an hour old. |
| `-refresh` | Look up the latest release now instead of using the cache. |
| `-version TAG` | Install a specific release, e.g. `-version v0.2.0`. This is also how to go back a version. |
| `-version TAG` | Install a specific release, e.g. `-version v0.1.3`. This is also how to go back a version. |
| `-method auto\|release\|go` | `release` installs the signed asset (default where one exists), `go` rebuilds with `go install`. |
| `-force` | Install to the method's location even if this binary lives elsewhere, and reinstall an equal version. |
| `-yes` | Do not ask for confirmation. Required when stdin is not a terminal. |
Expand Down
4 changes: 2 additions & 2 deletions cmd/machineid/update.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ func runUpdate(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
fs.SetOutput(stderr)

method := fs.String("method", string(selfupdate.MethodAuto), "How to update: auto, release (signed GitHub asset) or go (go install)")
version := fs.String("version", "", "Install a specific release tag, e.g. v0.3.0 (also how to go back a version)")
version := fs.String("version", "", "Install a specific release tag, e.g. v0.1.3 (also how to go back a version)")
check := fs.Bool("check", false, "Report what would happen and exit without changing anything")
refresh := fs.Bool("refresh", false, "Bypass the one-hour cache and look up the latest release now (counts against the hourly budget)")
force := fs.Bool("force", false, "Install to the method's location even if this binary lives elsewhere, and reinstall an equal version")
Expand Down Expand Up @@ -211,7 +211,7 @@ func printUpdateUsage(w io.Writer, fs *flag.FlagSet) {
fmt.Fprintf(w, "\nExamples:\n")
fmt.Fprintf(w, " %s update Check, show the plan, ask, install\n", applicationName)
fmt.Fprintf(w, " %s update -check What would happen; nothing changes\n", applicationName)
fmt.Fprintf(w, " %s update -version v0.3.0 Install a specific release\n", applicationName)
fmt.Fprintf(w, " %s update -version v0.1.3 Install a specific release\n", applicationName)
fmt.Fprintf(w, " %s update -method go Rebuild from source with go install\n", applicationName)
fmt.Fprintf(w, " sudo %s update -yes Non-interactive, e.g. for the macOS package\n", applicationName)
fmt.Fprintf(w, "\nExit Codes:\n")
Expand Down
26 changes: 13 additions & 13 deletions docs/updating.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,21 +60,21 @@ sudo machineid update -yes
```text
$ machineid update
Checking for updates…
✓ current version v0.2.0
✓ current version v0.1.3
✓ running binary /usr/local/bin/machineid
✓ platform supported darwin/arm64
✓ latest release v0.3.0 (live, 4 of 5 checks left this hour)
✓ latest release v0.2.0 (live, 4 of 5 checks left this hour)
✓ install target /usr/local/bin (running as root)

→ Updating machineid v0.2.0 → v0.3.0 using the signed macOS package
→ Updating machineid v0.1.3 → v0.2.0 using the signed macOS package

Update machineid now? [y/N] y
downloading machineid-darwin-universal.pkg…
✓ SHA-256 verified
✓ pkgutil: Developer ID Installer: SlashDevOps
✓ installed to /usr/local/bin

✅ Updated to v0.3.0
✅ Updated to v0.2.0
```

In order:
Expand All @@ -98,7 +98,7 @@ If anything fails before step 6, **nothing has been downloaded and nothing has c
|------|---------|
| `-check` | Report what would happen and exit. Nothing is downloaded. Uses the cached answer when it is under an hour old. |
| `-refresh` | Look up the latest release now instead of using the cache. Counts against the hourly limit. |
| `-version TAG` | Install exactly this release, e.g. `-version v0.2.0`. Works for older versions too. |
| `-version TAG` | Install exactly this release, e.g. `-version v0.1.3`. Works for older versions too. |
| `-method auto\|release\|go` | How to install. `auto` (default) uses `release` where a signed asset exists for your platform and `go` otherwise. See [Per-platform behaviour](#per-platform-behaviour). |
| `-force` | Two things: install to the method's location even if this binary lives elsewhere, and reinstall a version that is already installed. |
| `-yes` | Do not ask for confirmation. Required when stdin is not a terminal. |
Expand Down Expand Up @@ -168,13 +168,13 @@ machineid update -check

```text
Checking for updates…
✓ current version v0.2.0
✓ current version v0.1.3
✓ running binary /usr/local/bin/machineid
✓ platform supported linux/amd64
✓ latest release v0.3.0 (cached 12m0s ago)
✓ latest release v0.2.0 (cached 12m0s ago)
✓ install target /usr/local/bin (in place)

→ Updating machineid v0.2.0 → v0.3.0 using the release archive machineid-linux-amd64.zip
→ Updating machineid v0.1.3 → v0.2.0 using the release archive machineid-linux-amd64.zip
(-check: nothing was changed)
```

Expand All @@ -187,7 +187,7 @@ Checking for updates…
## Installing a specific version, or going back

```bash
machineid update -version v0.2.0
machineid update -version v0.1.3
```

An explicit tag is installed whether it is newer or older than what you have, so this is also how to **downgrade**. The tag must exist on the [releases page](https://github.com/slashdevops/machineid/releases) and carry an asset for your platform.
Expand All @@ -197,7 +197,7 @@ If you built `machineid` yourself, its version is something like `devel` or a br
```text
Error: the running version "devel" is not a release version, so it cannot be compared with a release

Name the release to install explicitly, e.g. machineid update -version v0.3.0
Name the release to install explicitly, e.g. machineid update -version v0.2.0
```

---
Expand Down Expand Up @@ -290,7 +290,7 @@ When stdin is not a terminal and `-yes` is absent, the prompt **declines** rathe
**Pin a version in CI:**

```bash
machineid update -yes -version v0.3.0 -require-signature
machineid update -yes -version v0.2.0 -require-signature
```

**macOS with the `.pkg`:** run under `sudo`, or install once with `go install` and let the updater manage that copy in place.
Expand Down Expand Up @@ -327,14 +327,14 @@ Every error prints a **remedy** underneath it. The common ones:
| `/opt/tools is not writable` | In-place replacement needs write access to the directory | Run with enough privileges, or `chown` the directory. |
| `the running version "devel" is not a release version` | Locally built binary | `machineid update -version vX.Y.Z` |
| `release "v9.9.9" was not found` | Typo, or the tag was never published | Check the releases page. |
| `release v0.3.0 does not carry machineid-linux-arm64.zip` | That release was published without your platform's asset | Pick another `-version`, or `-method go`. |
| `release v0.2.0 does not carry machineid-linux-arm64.zip` | That release was published without your platform's asset | Pick another `-version`, or `-method go`. |
| `does not match its published SHA-256` | Corrupt or tampered download; nothing installed | Retry. If it persists, open an issue. |
| `signature verification of … with cosign failed` | The bundle does not verify | Do **not** install. Retry; if it persists, open an issue. |
| `signature verification … cosign is not installed (-require-signature)` | You demanded a signature but have no `cosign` | Install cosign, or drop the flag. |
| `no release asset is published for windows/amd64` | No Windows binaries yet | `machineid update -method go` (needs Go). |
| `go is not installed` | `-method go` without a toolchain | Install Go, or use `-method release`. |
| `stdin is not a terminal; pass -yes to update without confirmation` | Piped or scripted run without `-yes` | Add `-yes`. |
| `… reports v0.2.0, not the v0.3.0 just installed` | The install landed somewhere other than the binary on your PATH | Check `which machineid`; you probably have two copies. |
| `… reports v0.1.3, not the v0.2.0 just installed` | The install landed somewhere other than the binary on your PATH | Check `which machineid`; you probably have two copies. |

`-debug` prints every command and every request, which is the fastest way to see what a failing run actually did.

Expand Down
2 changes: 1 addition & 1 deletion internal/selfupdate/asset.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ func AssetFor(goos, goarch string) (Asset, error) {

// DarwinZipAsset is the universal macOS zip, for updating a binary that does
// not live in [PkgInstallDir]. It carries the same signed and notarized
// binary as the package. Published from v0.3.0 on.
// binary as the package. Published from v0.2.0 on.
func DarwinZipAsset() Asset {
base := ToolName + "-darwin-universal"

Expand Down
2 changes: 1 addition & 1 deletion internal/selfupdate/errors.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ func (e *NotComparableError) Error() string {
}

func (e *NotComparableError) Remedy() string {
return "Name the release to install explicitly, e.g. " + ToolName + " update -version v0.3.0"
return "Name the release to install explicitly, e.g. " + ToolName + " update -version v0.2.0"
}

// UnsupportedPlatformError is returned when no release asset exists for the platform.
Expand Down
Loading