[mike@mwxm4]

README.md

@@ -11,6 +11,7 @@ directory. Go port of the original Perl `mgsh` (`mgsh.perl`).
 - [Public mirror (`pushremote`)](#public-mirror-pushremote) ·
   [Deleting a mirror (`deleteremote`)](#deleting-a-mirror-deleteremote) ·
   [Releases](#releases)
+- [Updating itself](#updating-itself)
 - [Configuration](#configuration) · [Settings reference](#settings-reference) ·
   [Per-project configuration](#per-project-configuration)
 - [Git server layout](#git-server-layout)
@@ -148,6 +149,7 @@ Run `help` for the full list. Highlights:
 | `unalias <name>`          | remove a command alias                         |
 | `config [-k]`             | show the effective configuration and its sources |
 | `rescan`                  | reload the config, refresh the cached repo list |
+| `update [-c]`             | update mgsh to the newest release (`-c`: only look) |
 | `!<command>`              | run `<command>` in the shell                   |
 
 Commands that touch a repository (`push`, `pull`, `log`, `diff`, `tag`, `dist`,
@@ -498,6 +500,66 @@ This is where the providers stop resembling each other, and mgsh papers over it:
 The GitLab route needs the package registry enabled on the project — it is on by
 default, but a self-hosted instance can turn it off.
 
+## Updating itself
+
+```
+update -c        # only look
+update           # fetch and replace
+```
+
+and from outside the shell, `mgsh update` / `mgsh --update` — the dashed
+spelling is the one that also works before mgsh is configured, where every
+other command exits with "not configured".
+
+mgsh fetches the newest release from
+[git.micw.org/mike/mgsh](https://git.micw.org/mike/mgsh) — the URL sits fixed in
+the program, there is nothing to configure. What it needs is one release per
+version, whose tag is the bare number (`4.1.0`), with the files from `./bin` as
+its assets; the one looked for is the one matching `GOOS`/`GOARCH` of this
+machine. That is exactly what `./build.sh` produces and `release` publishes, so
+`./build.sh && release 4.1.0` is the whole publishing side.
+
+What gets replaced is the running file itself. If the `mgsh` that was called is
+a symlink — say `~/bin/mgsh` pointing at `~/src/mgsh/bin/mgsh-darwin-arm64` —
+the target behind it is renewed, not the link. Before the swap, what was freshly
+fetched is called once with `--version`; if it does not report the expected
+number, everything stays as it was. The swap itself is a `rename` within the
+same directory, hence atomic: either the old file or the new one, never half of
+one. If the binary lies somewhere you may not write to (`/usr/local/bin`),
+`update` says so and does nothing — then `sudo`.
+
+### Once a day, by itself
+
+Without being asked, mgsh looks once a day and says so on stderr — at the start
+of an interactive session, and after the output of a one-shot command:
+
+```
+mgsh 4.1.0 is available, run 'mgsh --update'
+```
+
+The run in the foreground never touches the network for this. It only reads a
+note — `~/Library/Caches/mgsh/update.json`, on Linux `~/.cache/mgsh/update.json`
+— and when that one is older than a day, it starts `mgsh --update-refresh` on
+the side: the same binary once more, detached, without output, only to ask.
+Nobody waits for its answer; it will be in the note at the next call. mgsh
+thereby stays exactly as fast as before, even when the server happens to be
+silent.
+
+The timestamp moves on *before* the asking. Two simultaneous runs therefore
+start one query, not two, and a server that does not answer is asked again
+tomorrow rather than on every call. If the note cannot be written, the question
+is dropped entirely — otherwise a write-protected cache directory would mean one
+process per call.
+
+Asking and speaking happen only when stderr hangs on a terminal. In a pipe, in a
+script and under cron there is quiet, and `MGSH_NO_UPDATE_CHECK=1` turns it off
+altogether.
+
+`selfupdate.go` is a copy from [dx](https://git.micw.org/mike/dx) and hangs on
+nothing in the rest of mgsh: standard library only, every name it brings starts
+with `selfUpdate` or `update`, and the block at the top of the file is all there
+is to adjust when it moves on to the next program.
+
 ## Configuration
 
 mgsh has **no built-in defaults**. Settings are resolved in three steps, each