@izykitten/ce 0.0.3-dev.5 → 0.0.3-dev.6

package/README.md

@@ -53,7 +53,7 @@ Prefixes can use guards too. A guard that does not pass leaves the prefix empty,
 
 Guards decide from the run's metadata, so they need it too: outside a Forgejo Actions run, `{?default}` fails like `{default}` would. Only `{env.NAME}` and `{arg.NAME}` work everywhere. A guard that does not pass decides on its own, though: a tag with one is left out, and a prefix with one is empty, even if another guard in it could not be worked out, so `{?default}{?env.X}` outside a run with `X` empty is simply left out. To tell whether a branch is the default one, ce reads `repository.default_branch` from the event file, or `DEFAULT_BRANCH` when the event has none, as on a scheduled run; set `DEFAULT_BRANCH: main` in such a workflow. Pull requests and tags are never the default branch, so they need neither.
 
-Put templates in single quotes: `?` is a glob character in zsh.
+Quote a template in a workflow's `env:`: YAML reads `CACHE_PREFIX: {ref}` as a mapping, and `{?pr}pr-{pr}` not at all.
 
 A branch, PR and default-branch build:
 
@@ -73,13 +73,41 @@ The same can be written by hand, since ce only prefixes a `--cache-from` whose s
 
 The `--cache-from` that `--cache` makes leaves out a gha `mode=`, which only applies to export, and a `--cache-from` given twice, as the default branch's own scope is on the default branch, is passed once.
 
-A release on a SemVer tag, with the version aliases only for stable releases:
+### Recommended tags
+
+For an image others pull by version:
 
 ```sh
--t '{image}:{ref},{?version}{version},{?stable}{major}.{minor},{?stable}{major},sha-{sha}'
+-t '{image}:{ref},{?version}{version},{?stable}{major}.{minor},{?stable}{major},{?stable}latest'
 ```
 
-`{stable}` does not mean newest: rebuilding an older release moves its aliases back to it.
+| Build             | Tags                                    |
+| ----------------- | --------------------------------------- |
+| branch `main`     | `main`                                  |
+| branch `ci/fix`   | `ci-fix`                                |
+| pull request 3    | `pr-3`                                  |
+| tag `v1.2.3`      | `v1.2.3`, `1.2.3`, `1.2`, `1`, `latest` |
+| tag `v1.3.0-rc.1` | `v1.3.0-rc.1`, `1.3.0-rc.1`             |
+| tag `v0.3.1`      | `v0.3.1`, `0.3.1`, `0.3`, `0`, `latest` |
+
+- `{ref}` names every build after what was pushed, so a branch or pull request can be pulled to try it, and a release keeps its git tag's name, `v` included.
+- `{?version}{version}` adds the version without the `v`, as most images are tagged, for pre-releases too.
+- `1.2` and `1` follow the newest stable release in their line, for those who want fixes but not the next major version. Before 1.0, SemVer lets any minor release break things, so `0` can move from 0.3 to a 0.4 that does; pin `0.3` to avoid that.
+- `latest` is the newest stable release, as on most images. A repository with no release tag yet has no `latest`: deploy `main` instead, or use `{?default}latest` until the first release.
+
+The guard on `latest` picks what it follows:
+
+| Tag                   | `latest` follows                          |
+| --------------------- | ----------------------------------------- |
+| `{?stable}latest`     | stable releases                           |
+| `{?version}latest`    | every SemVer tag, pre-releases included   |
+| `{?tag}latest`        | every tag                                 |
+| `{?default}latest`    | the default branch                        |
+| `{?env.LATEST}latest` | builds where an earlier step set `LATEST` |
+
+Guards go by the build, not by what is in the registry: `latest` and the version aliases move to the last build whose guards pass. A `v1.2.4` fix pushed after `v2.0.0`, or a rebuild of an older release, moves them back to it. For a rule such as "only the highest version" or "the default branch until the first release", have an earlier step check the registry and set the variable an `{?env.NAME}` guard reads.
+
+`{ref}` moves with each push. To also keep every branch and pull request build under a name of its own, add `{?branch}{ref}-{sha},{?pr}{ref}-{sha}`, which gives `main-0123456` and `pr-3-0123456`.
 
 ### Build args and the Containerfile
 

package/dist/ce.js

@@ -2112,7 +2112,7 @@ function envFlag(name) {
   throw new CeError(`ce: ${name} must be true or false, not ${JSON.stringify(process.env[name])}`);
 }
 function shellQuote(arg) {
-  return /^[A-Za-z0-9_@%+:,./-][A-Za-z0-9_@%+=:,./-]*$/u.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+  return /^[A-Za-z0-9_@%+=:,./-]+$/u.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
 }
 async function runEngine(engine, argv, tagPrefix, cachePrefix, options = {}) {
   const dryRun = options.dryRun ?? envFlag("CE_DRY_RUN");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@izykitten/ce",
-  "version": "0.0.3-dev.5",
+  "version": "0.0.3-dev.6",
   "description": "Container engine wrapper: tag/cache rewriting for docker, podman and buildah, registry login, and a Forgejo OIDC Docker credential helper",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -30,4 +30,4 @@
   "devDependencies": {
     "@types/bun": "1.4.3"
   }
-}
+}