Differences from Batect
Ratect is a from-scratch Rust implementation inspired by Batect (which is itself no longer maintained — the upstream repository was archived in October 2023), not a wrapper or fork. It does not read Batect’s documentation or source at runtime. To move an existing project over, follow Migrating a Batect Project to Ratect; this page is what changes once you have.
Every Batect configuration field and CLI flag is supported, field-for-field and flag-for-flag, unless listed below — see config reference/ CLI reference for the full accepted schema and flags. This page lists the exceptions: a real behavioral divergence, an extension beyond what Batect does, or a restriction narrower than it. It doesn’t restate how a field or flag works — config reference/CLI reference/ task lifecycle are the authoritative source for that; this page only says what’s different and points there for the rest.
Unrecognized fields fail closed: Ratect’s YAML parsing rejects unknown keys — a typo’d field name, or (unlikely, since Batect’s own
includetypes beyondfile/gitare the only thing left genuinely unsupported here) a real gap — fails config loading with an error naming it, rather than silently ignoring it. There’s no partial/best-effort mode.
Configuration format
Top-level fields
Every other top-level field is supported field-for-field — see config reference for the full list. The exceptions:
| Field | Notes |
|---|---|
config_variables | description: is recognized but inert — Ratect has no help/usage output to show one in. |
include | Ratect enforces that a Git include’s path (and anything it transitively includes) stays within that repository’s own clone, and that a bundle’s containers’ host paths (volumes, build_directory, build_secrets, build_ssh) stay inside its clone or your project directory unless your include entry sets allow_host_paths; Batect has no equivalent containment check for either. In ratect.toml specifically, a Git-included bundle also can’t declare further Git includes of its own unless allow_nested_git_includes is set — ratect-compat stays unrestricted, matching Batect. See What a bundle may do. A Git include’s clone is cached under ~/.ratect/incl, keyed by a SHA-256 of the remote and ref with each length-prefixed, with a TOML sidecar — not Batect’s ~/.batect/incl, keyed by a hash of git <remote> @<ref>, which two different remote/ref pairs can share. Neither tool reuses or sweeps the other’s clones. The sweep that removes a clone unused for 30 days counts them as 30 × 24 hours, where Batect counts 30 calendar days in your time zone, so across a daylight-saving change the two can disagree by up to an hour about whether a clone is due. It skips, with a warning, a sidecar it can’t read or parse, and goes on to the rest; Batect’s stops at the first such file, so while it’s there no clone is ever removed. See Git includes. Cloning a Git include is guarded by a lock file, as in Batect, but a lock whose holder has exited (killed during a first clone, say) is taken over by the next load that needs the include, where Batect’s waits 5 minutes and fails until the file is deleted by hand; a lock left by an older Ratect is still waited on. A load waiting on another process’s clone says so on stderr, where Batect’s waits in silence. Where the lock’s proof of exit doesn’t reach every process sharing the cache, such as a host and a container sharing ~/.ratect/incl, two loads can clone the same include at once; the second to finish uses the first’s clone. See decisions/0023 and decisions/0027. The Cloning <repo> <ref>... line, and the blank line after it, are printed only by a load that clones; Batect’s also come from a load that waited out another process’s clone and then skips its own. git’s own output is captured: a failed clone’s is part of the error (except, in ratect.toml, for a Git include a bundle declares, where it goes to RUST_LOG=debug — see Nested Git includes), where Batect prints git clone’s as it runs, its error saying only that git exited with a code, and puts only a failed git checkout’s in its error; and a successful clone’s warnings are dropped, where Batect shows git clone’s. A prompt for credentials still reaches the terminal. Wherever Ratect names an include’s repo, any credentials in its URL are shown as *** (https://***@host/repo.git), as is anything else between :// and the URL’s last @ (https://host/a@b is shown as https://***@b); Batect prints the URL whole. An include written as an object with no type loads as a file include; Batect requires type, and fails to load the file without it. The git checkout after the clone uses none of your Git configuration, nor the clone your init.templateDir, so core.autocrlf doesn’t change a clone’s line endings, no hook runs during the checkout, and a file stored in Git LFS stays a pointer file; Batect’s checkout uses your configuration. Batect’s also searches upward from the clone’s directory for a repository, so when the clone’s .git is missing it checks the ref out in whichever repository holds the cache, and both its commands use the variables naming a repository that git rev-parse --local-env-vars lists, which Ratect’s ignore, such as an exported GIT_WORK_TREE, which makes its clone fail, or the absolute GIT_INDEX_FILE a hook of git commit -a gets, under which it checks out no files. |
forbid_telemetry | Recognized, no effect — Ratect doesn’t collect telemetry, so there’s nothing to forbid. |
Expressions
The syntax and which fields support it match Batect, field-for-field — see Expressions. The exceptions:
- When a task’s values are evaluated. Both evaluate only what a task uses, once the run reaches it, after its prerequisites. Ratect evaluates every container in the task’s graph before starting any of them, where Batect evaluates each as it creates or builds it — so here a value that can’t be evaluated fails the task before its dependencies start, rather than after.
image— see Container fields below.batect.project_directoryhas its.and..components resolved:-f ../proj/batect.ymlgives/parent/proj, where Batect gives/parent/cwd/../proj. Both name the same directory, and a volume path built from either is normalised the same way, so the difference only shows where the value is used as a string — inenvironmentorbuild_args.
Container fields
Every other container field is supported field-for-field — see config reference for the full list. The exceptions:
| Field | Notes |
|---|---|
image | An expression-looking value ($VAR) is rejected when the file loads rather than resolved or used as a literal — Batect resolves nothing here either, but silently treats it as a literal image name that then fails at pull time instead. ratect.toml does resolve them; see config reference. |
volumes | A cache mount’s name must use Docker’s own volume-name character set; Batect doesn’t validate it at all, so an unvalidated name could bind-mount an arbitrary host directory under --cache-type=directory. Breaking change for --cache-type=directory only — --cache-type=volume already enforced this via Docker itself. See Cache volumes. A newly generated .batect/caches/key holds a UUID rather than Batect’s six-character id, under a comment that doesn’t name Batect; each tool reads the other’s key file, so the volume names stay the same. A line of that file that starts with # after leading spaces is a comment, where Batect counts it as a key line: Batect refuses a file holding one beside the key, and takes one on its own as the key, where Ratect refuses the file as having no key line. A key path that is a symbolic link to nothing is refused, where Batect creates the key file wherever the link points. |
ports | A port written with a leading + (+80, '+80-+90', '+80:+80'), or unquoted as a YAML hexadecimal or octal integer (0x50, 0o120), is accepted as the port it denotes; Batect rejects each as a malformed port range. The same holds for a task’s run.ports. |
dependencies | A name that isn’t a declared container is rejected when the file loads — and so is one in a task’s dependencies or run.container. Batect reports the same error in the same words, but only once a task that reaches the reference runs, so a stale reference in a container or task nothing runs never stops Batect and stops every ratect-compat command. A name given twice — here, in a task’s dependencies, or in a task’s prerequisites — is accepted, and that container starts, or that task runs, once; Batect rejects the duplicate when the file loads (The dependency 'X' is given more than once, and likewise for a prerequisite). ratect doctor and ratect config validate warn about it. See config reference. |
capabilities_to_add / capabilities_to_drop | Also accepts BPF/CHECKPOINT_RESTORE/PERFMON — Docker capabilities added after Batect’s last release, so its own Capability enum predates them. A superset: every config Batect itself accepts here still parses identically. |
health_check / setup_commands | A task’s own container’s readiness gate doesn’t fail the task once its main command has exited 0, whatever the failure — typically the container stopped before reporting a health status, before a setup command could exec into it, or while one was running and was killed with it; Batect’s does. A failure of that gate while the main command is still running fails the task as Batect’s does, but cancels the main command up to two seconds later, and is forgiven if the main command exits 0 within that time. That, and the race it leaves open, are in task lifecycle. Under ratect a task’s own container has no readiness gate at all — see Dependency Readiness. |
dockerfile | A Dockerfile that is a symbolic link, or is reached through a linked directory, is refused before the build, since Ratect’s build context doesn’t carry symbolic links and the daemon would report the Dockerfile missing. Batect builds one whose link stays inside the build directory. |
log_driver / log_options | An absent value leaves the daemon’s own default alone; Batect’s config model bakes in a literal "json-file" default explicitly. Immaterial in practice — that’s Docker’s own out-of-the-box default too. |
shm_size | A size whose count times its unit doesn’t fit in a 64-bit number of bytes is an Invalid size error when the file loads, like any other malformed size. Batect’s multiplication overflows silently, and it sends Docker the meaningless size that results. Whitespace around a size string is ignored (' 128m '), as is whitespace that isn’t ASCII, and an unquoted YAML integer is read as the number it denotes, whatever its spelling (+5, 0x10, 0o17); Batect refuses each. Both accept whitespace between the count and its unit ('128 m') or after a bare count ('2 '). |
run_as_current_user | A .toml file refuses it, in favour of identity: the same goal, with a mechanism that depends on the daemon — see Coming from run_as_current_user. A .yml keeps it, and the rest of this row is about that. Host-side uid/gid lookup only works on Unix — see User mapping. A home_directory containing a : or a control character, or with no directory name to create (/, or a path ending in ..), is rejected when the file loads. Batect checks neither: it writes the first into the generated /etc/passwd as it is, where a : shifts the entry’s fields and a newline adds an entry of its own, and passes the second to Docker. A read-only cache mount (options: ro) isn’t given to the mapped user, since nothing can write to it anyway; Batect tries to change its owner like any other cache’s, which the read-only mount refuses, failing the run before the container starts. The generated /etc/passwd, /etc/shadow and /etc/group end their last line; Batect’s don’t, and musl libc (alpine’s) reads an unterminated last line one character short, so on a musl image the user’s shell reads as /bin/s and the group’s member a letter short. |
Task fields
Every task field is supported field-for-field — see config
reference for the full list. The
exceptions are about when a mistake is caught: dependencies naming an
undeclared container, and a name given twice in dependencies or
prerequisites, are under dependencies in Container
fields above, and a customise naming a container the task
doesn’t start is under Load errors.
run fields
Every run field is supported field-for-field — see
TaskRun for the full list. The
exceptions are about when a mistake is caught: container naming an undeclared
container is under dependencies in Container fields
above, and a container also listed in the task’s dependencies is under Load
errors.
Null values
A field given a YAML null (volumes: with nothing after it, ~ or null)
mostly loads as if it were left out — a container’s volumes, ports,
environment, health_check or run_as_current_user, a task’s
prerequisites, dependencies or customise, and the top-level
forbid_telemetry or config_variables, for example. Batect rejects a null on
each of those. Where Batect accepts one — run’s command, entrypoint and
working_directory, a config variable’s default and description,
health_check’s retries — the two tools agree. Some nulls are rejected here
too, such as an environment variable’s value and shm_size, in Ratect’s own
words.
Load errors
Ratect checks a config when the file loads, and the report is its own:
- Some checks Batect makes only once a task reaches them are made when the
file loads here, for any command that loads it —
--list-tasksincluded — and the first hard error stops it, so a config Batect lists, or runs a different task from, can fail to load here. Besides the undeclared names underdependenciesin Container fields, they include arun_as_current_userhome_directorythat isn’t an absolute path, and a relativecachemount destination underrun_as_current_user— Batect checks both as it configures the container, though its message for the cache path is never seen, since Docker has already refused the relative mount when the container was created; and a task’scustomisenaming a container its task doesn’t start, or itsrun.containeralso listed in itsdependencies, checked for every task rather than only the ones run.--tag-imageon a container that uses a pulled image isn’t checked at load, but fails as soon as that container’s image is resolved — after its dependencies have started and its prerequisite tasks have run, but before it runs — where Batect fails once the task using it has finished. - A negative
health_checkduration, such as-2s, is rejected when the file loads. Batect loads one, and the run fails only once Docker refuses it. A negative zero, such as-0s, is zero, and loads in both. - The wording is Ratect’s, not Batect’s —
Configuration file "batect.yml" not found.rather thanThe file '<absolute path>' does not exist., and likewise for malformed volumes, ports, devices and includes, expressions, durations, duplicatebuild_sshids, an undeclared config variable given a value — which names the variable but neither which of--config-varand--config-vars-filegave it nor, for the file, its line — a name defined in more than one file, a file that contains no configuration, and an included file that setsforbid_telemetrytotrue. A file inside a Git include, or a container’s path inside one, is named by its path within the repository plus the remote and ref,'1.yml' from the bundle '<repo>' at '<ref>', where Batect writes<repo>@<ref>: 1.ymlor1.yml from <repo>@<ref>. - A check made once the file has parsed names what it’s about — the container or task — rather than giving Batect’s YAML path, line and column.
- An error raised while the file is parsed gives its line, column and YAML
path in Ratect’s own layout —
deserialization error at line 8, column 23: containers.build-env.not_a_real_field: unknown field: not_a_real_field, under theFailed to parse config file "<path>"line of the cause chain below — where Batect prints<file> (at <path> on line L, column C): <message>. The wording is Ratect’s too:unknown field: Xwith no list of the known ones,missing field: X, and for a value of the wrong type the path and the mismatch, with noValue for 'X' is invalid:prefix — a refused null isinvalid type: null, expected <what the field takes>, as incontainers.app.shm_size: invalid type: null, expected a size like '128', ..., where Batect saysUnexpected null or empty value for non-null field.A null where a mapping of fields is expected is read as an empty one, so it reports any field that mapping must have as missing. An unknown field’s column is its value’s, not its key’s, and so is that of a task, config variable or container name Batect refuses — though the message for one is Batect’s, verbatim. A key given twice in one mapping istasks.t: duplicate key "t" at line 9, column 3, giving only the second occurrence’s line, where Batect’sDuplicate key 't'. It was previously given at line L, column C.also gives the first’s. - The full cause chain is printed:
Error: <message>, then aCaused by:list when there is a cause, where Batect prints one message. A parse error’s own reason is in that list, underFailed to parse config file "<path>". The same holds for every fatal error, not only a config one. - With several problems, the one reported isn’t necessarily Batect’s first.
Of several containers, tasks or
customiseentries failing the same check, the first the files declare is reported, as in Batect, but each check runs over every container before the next check starts, and over containers before tasks, so of two failing different checks the one reported can differ. Every config check runs before an--override-imagecontainer name is looked up, a duplicatebuild_sshid is checked after a container’s image source, a volume’s fields are checked in a different order, and of several undeclared config variables given values, the first by name is reported, where Batect reports the file’s first, in file order, before any--config-var. Acommand,entrypointor setup command that can’t be tokenized is reported after every error raised while the files are parsed, after every container’s image source,imageexpressions,dnsentries and fields its file’s format doesn’t allow are checked, and after the same container’svolumes,build_directoryandbuild_secrets, where Batect reports whichever the file gives first.
CLI flags
Every other flag from Batect’s own CLI reference is supported flag-for-flag — see CLI reference for the full list. The exceptions:
| Flag | Notes |
|---|---|
--version | Prints one line, ratect-compat <version>, rather than Batect’s seven labelled lines (its version, build date and commit, and the JVM, OS, Docker and Git versions) and the help blurb after them. Also gets a -V short form Batect doesn’t have (a clap default). Acts as soon as it’s reached: whatever follows it on the command line is never parsed or checked, and no check across options is made, so --version --bogus and --tag-image app=t --override-image app=i --version exit 0, where Batect checks every option first and rejects them. Given with --help, whichever of the two comes first wins; Batect always shows the help. |
--help / -h | The layout and text are clap’s rather than Batect’s, including <CONFIG_FILE>-style value placeholders and [default: …] for a fixed default. A description never shows an environment variable’s current value or whether batect.local.yml exists — Batect’s say, for example, whether DOCKER_HOST is currently set, and to what. Like --version, acts as soon as it’s reached, without checking what follows it, so --version --help prints the version, where Batect shows the help. Exits 0, as help conventionally does; Batect’s HelpCommand returns 1. See Options and decisions/0016. |
--list-tasks / -T | The listing opens with Tasks in <project>:, followed, when any task has a group, by a blank line before the first group heading. Batect’s opens a flat list with Available tasks:, and a grouped one with its first group heading. The -o quiet listing, the one meant for scripts, has no header in either. |
--config-var | --config-var NAME= sets the variable to an empty value, which Batect rejects as having no value. A value containing = is split at its first =, so --config-var a=b=c sets a to b=c; Batect splits at the last, setting a=b to c. --override-image and --tag-image also split at the first =. |
--tag-image | A TAG Docker would refuse is rejected while the arguments are parsed, as a usage error, on every command, --list-tasks included. Batect rejects it only when that image’s build step starts, after the task’s prerequisites have run. The check is the one docker tag makes, with its reasons, so a digest (app@sha256:…) is refused too; Batect accepts one, and the daemon then refuses the build. Batect’s parser is an older copy of the same grammar: it rejects a name whose first component has uppercase in it (MyOrg/app), which the current one takes as a registry host, and an IPv6 registry host, and it counts the 255-character limit over the whole name rather than the repository path; its uppercase message also doesn’t name the repository. See decisions/0018. |
TASK_NAME (positional) | A misspelled task name’s Did you mean suggestions include every task tied on edit distance; Batect keeps only one name per distance. An unknown task’s error reads Task 'X' not found., where Batect’s reads The task 'X' does not exist., and its closing hint names ratect-compat --list-tasks and ratect-compat --help rather than ./batect’s. No task name at all is a command-line error, as in Batect, reported like any other (see below): exit 125, where Batect exits 255. See Exit codes and error reporting. |
-- ADDITIONAL_ARGS | When neither the task’s run nor its container sets a command, the arguments replace the image’s default CMD, as docker run <image> <args> does; Batect refuses them with an error. Every invocation Batect accepts runs the same here. See Using ADDITIONAL_ARGS in a task command. |
--output / -o | An explicit -o fancy fails up front with a clear error when stdout isn’t a terminal, and so does one on a terminal with TERM=dumb; TERM unset is accepted, as in Batect. Batect accepts both refused cases: when stdout isn’t a terminal it crashes with an unhandled exception on the first repaint, and on a terminal with TERM=dumb it writes cursor movements that terminal can’t perform, garbling the display. all’s status lines also drop Batect’s inner Batect | prefix — the outer prefix already says whose line it is. all’s | separator is unstyled, where Batect bolds and colours it with the name before it: emphasis is for names, never punctuation (decisions/0017). fancy clips a line to the terminal’s width in display columns, so a wide character counts as two; Batect counts UTF-16 units, so a line holding wide characters is clipped earlier here. Choosing a style automatically doesn’t special-case TRAVIS=true, as Batect does by picking simple; that only matters on Travis CI with a real terminal, since a CI runner without one gets simple anyway. See Output Styles. |
--no-color | A superset, not a gap: Batect rejects -o fancy --no-color at parse time (its console couples color and cursor movement under one flag); Ratect’s keeps them independent, so that combination renders colorless fancy instead. Ratect also honours two environment variables Batect ignores: NO_COLOR has --no-color’s full effect, including making simple the auto-selected style, and CLICOLOR_FORCE colours output to a non-terminal. See Colour. |
--no-cleanup, --no-cleanup-after-failure, --no-cleanup-after-success | Batect’s own DontCleanup still stops a started container, just skips removing it; Ratect leaves it genuinely running (not just present-but-stopped) for investigation. With cleanup after success disabled, a task whose own container runs to completion exits with that container’s exit code; Batect exits 255 whatever the code was, 0 included, so a script checking the exit status can’t tell a pass from a fail. |
--docker-cert-path, --docker-tls, --docker-tls-verify, --docker-tls-ca-cert, --docker-tls-cert, --docker-tls-key | Batect’s bare --docker-tls (without -verify) disables all server certificate verification, not just hostname matching. Ratect doesn’t support that mode at all — --docker-tls and --docker-tls-verify behave identically here, the daemon’s certificate always fully verified. See TLS with a private certificate authority for the supported alternative (your own CA). A superset in one respect: Batect requires all of ca.pem, cert.pem and key.pem, and Ratect none of them — without a CA the system trust store is used, and without a cert.pem/key.pem pair no client certificate is presented. A CA that is given is the only one trusted. See TLS through the options. |
--docker-tls-ca-cert, --docker-tls-cert, --docker-tls-key | A file that exists but isn’t a regular file is accepted — a pipe, such as <(…), to keep a key off disk, is read like a file, once. Batect refuses one as refers to something other than a file. A missing file or a directory is refused before any command runs, as in Batect. See TLS through the options. |
--docker-context | A context’s SkipTLSVerify is not honoured: the daemon’s certificate is always fully verified, as with --docker-tls. Batect honours it, skipping verification. See Which daemon is used. |
--docker-host | An https:// host connects over TLS, as if --docker-tls-verify were given — from the flag, DOCKER_HOST, or a Docker context. Batect (and the Docker CLI) connect to such a host without TLS unless the TLS options or the context’s stored files ask for it. See Options. |
--docker-host | A host whose scheme isn’t unix://, tcp://, http:// or https:// — from the flag, DOCKER_HOST, or a Docker context — is refused on connecting, in Ratect’s own words: from the flag or DOCKER_HOST, Failed to connect to Docker host '<host>', caused by URI scheme is not supported: <host>. That includes ssh://, which Batect’s Docker client accepts. Where Batect refuses a host, as it does npipe:// off Windows, its message is protocol not available. |
--docker-context, --docker-config | A Docker CLI config.json that can’t be read or isn’t valid JSON, when the active context would be read from it, is a warning naming the file, and the default context is used, as the current Docker CLI does. Batect fails, as the Docker CLI it was built against did. See Which daemon is used. |
--docker-host, --docker-context | An empty DOCKER_HOST or DOCKER_CONTEXT counts as unset, as in the Docker CLI. Batect takes an empty value as set: an empty DOCKER_HOST still rules out every context and becomes the host, and an empty DOCKER_CONTEXT names a context called "". See Which daemon is used. |
--docker-tls-verify, --enable-buildkit | An empty DOCKER_TLS_VERIFY or DOCKER_BUILDKIT counts as unset, as in the Docker CLI: no TLS, and the daemon’s own builder. Batect rejects an empty value as not a boolean. Both are also read in any case, so True and Yes are accepted; Batect takes only the all-lower and all-upper spellings. An invalid DOCKER_TLS_VERIFY is rejected only when connecting to a host without --docker-tls/--docker-tls-verify, so --list-tasks and a connection through a context never read it; Batect rejects it on every command. See Environment variables. |
--docker-config, --docker-cert-path | A directory given by the flag, DOCKER_CONFIG or DOCKER_CERT_PATH that doesn’t exist or isn’t a directory is refused before any command runs, as in Batect, but in Ratect’s own words, naming the flag or variable, the path and what is wrong with it. ratect doctor reports one as a problem and carries on with its other checks. See Options. |
--enable-buildkit | An invalid DOCKER_BUILDKIT (the flag’s default) is rejected the first time a run builds an image — every run of a task with a build_directory container, since Ratect always builds and leaves Docker’s layer cache to skip unchanged work — rather than on every command. A task that only pulls images, --list-tasks and --clean never read it. Batect, like the Docker CLI, rejects an invalid value on every command. A daemon whose Builder-Version ping header is none of empty, 1 and 2 is reported at the same point, and not at all when DOCKER_BUILDKIT or the flag chooses the builder; Batect fails every run that connects to it, with an unhandled exception. |
--cache-type | Unlike Batect, not forced to directory for Windows containers — Ratect has no Windows support to special-case. A BATECT_CACHE_TYPE that is no cache type is refused, as in Batect, in Ratect’s own words, naming the variable, its value and the two cache types. |
--clean, --clean-cache | Under --cache-type=directory, the Docker daemon is never contacted, so cleaning works while it’s unreachable; Batect checks it can reach the daemon first, under either cache type, and fails without it. A project with no .batect/caches directory has nothing to remove, and Ratect warns that the directory isn’t there, where Batect fails with exit code 255. An entry there that is a symbolic link is skipped rather than followed, with a warning naming it: Batect follows it and deletes the contents of whatever it points to, even outside the project. |
--max-parallelism | Batect’s flag caps every setup/cleanup step, via a step-scheduling model Ratect doesn’t have, but one: a container’s run — its start, then the wait for it to exit — never counts, for any container, dependencies included, since it lasts the container’s whole lifetime; every container’s create counts. Ratect’s caps image pulls/builds, every container’s create (the task’s own included), a dependency’s start, and setup commands. So a dependency’s start is capped where Batect’s isn’t: under a low cap, dependencies start one at a time where Batect starts them together — timing only, the run’s outcome is the same. The task’s own container’s start and run are never gated, as in Batect. Health-check waits and cleanup teardown, which Batect’s cap covers, are deliberately excluded (teardown is concurrent, gated only by dependency order). |
--log-file | Batect’s own default (no --log-file) is a silent NullLogSink, nothing anywhere; Ratect always logs to stderr regardless, so --log-file here tees into a file in addition to stderr, not instead of it. The file is plain text, each record starting on a new line — one carrying a multi-line error, such as why the run failed, continues over the lines after it — where Batect writes one JSON object per message, and logs Ratect’s own records at debug and other crates’ at info unless RUST_LOG says otherwise, where Batect logs every message. The records are Ratect’s own rather than Batect’s, ending, at that default, with why the run failed when it did: the Git include cache sweep, for example, logs only what goes wrong, in its own words, and none of Batect’s No repositories ready for clean up., Deleting repository as it has not been used in over 30 days. or Repository deletion completed. records. |
--generate-completion-script, --generate-completion-task-info | Not accepted — an unrecognized-argument error. Batect’s are hidden flags for its own shell completion, which reaches them only through Batect’s wrapper script. ratect-compat has no shell completion; the native binary prints its own script with ratect completions <shell>. |
--no-update-notification, --upgrade, --no-wrapper-cache-cleanup | Recognized, no effect — permanently inapplicable, since Ratect is a single native binary with no self-updating wrapper script to disable notifications for, clean caches for, or upgrade. Recognized rather than rejected so an existing Batect invocation carrying one doesn’t hard-fail outright. Hidden from --help, where Batect lists all three — --upgrade under its help options, the other two under its execution options. See CLI reference. |
Beyond any one flag:
- A mistake on the command line is reported in
clap’s format: anerror: …line in its own words, sometimes followed by a tip or a usage line, thenFor more information, try '--help'.Batect prints a single message of its own instead, such asInvalid option '--bogus'. Run './batect --help' for a list of valid options.The exit code is125on a line meant to run a task,docker run’s code for its own failure, and2on one that replaces the task with--list-tasks,--clean,--clean-cacheor--upgrade, the usage-error conventionclapand the POSIX utilities share. So is an option value that fails its own check, such as a-for--config-vars-filenaming no file, abatect.local.ymlthat isn’t a file, or aBATECT_CACHE_TYPEthat is no cache type. Batect’s is-1(255) for both, the same as for any other failure (decisions/0016). --helpand--versionexit0even when an option’s value or default is invalid — a--docker-confignaming no directory, abatect.local.ymlthat isn’t a file, or a badBATECT_CACHE_TYPE, say: they act before any value they don’t need is checked. Batect checks its options and their defaults first, so an invalid one makes--helpexit-1(255) instead (decisions/0016).- Short options combine, and take an attached value:
-Tf batect.yml,-fbatect.ymland-oquietare accepted. Batect looks an option up by its exact text up to any=, and rejects each of those as an invalid option. - An option’s value can’t start with
-when it’s given as the next argument:--use-network -xand--clean-cache --list-tasksare usage errors, whose tip is the=form (--use-network=-x), which is accepted. Batect takes the next argument as the value whatever it starts with, so a forgotten value silently swallows the flag after it, while no Docker network, volume or context name and no Batect task name can start with-, and a path that does can be written./-x.
Runtime behavior gaps
Batect behavior not implemented in task execution, beyond what’s covered by the field tables above:
-
The home directory is
$HOMEfirst, when it is set and absolute, then the passwd entry’s, as in the Docker CLI. Batect uses the JVM’suser.home, which is the passwd entry’s whenever there is one, so where it and$HOMEdiffer Batect reads a different~/.dockerfrom the onedocker loginwrote, and the credentials and contexts there go missing. It also expands~in a path to that directory, where a shell would use$HOME. With no passwd entry,user.homedepends on the JDK:$HOMEon Java 21,?on Java 11. Not copied, as a Batect bug, under 0013’s rule 3. -
Cleanup on a termination signal (Ctrl+C,
SIGTERM,SIGHUP): four deliberate differences from Batect, which trapsSIGINTonly:- Ratect also traps
SIGTERMandSIGHUP, down the same cleanup path — a task runner is stopped by more than a keystroke (an editor closing its subprocess,docker stop,systemd, most CI cancel buttons), and under Batect each leaks a container and network. - The exit code names the signal: 128 + the signal’s own number (
130/143/129for Ctrl+C/SIGTERM/SIGHUP). Batect returns-1/255 for an interrupted run, as for any failure other than the task’s own command exiting non-zero. - A further signal during cleanup hurries it, then Ctrl+C stops it: a second
signal of any kind switches whatever is left to forced removal (kill and remove, no
grace period), and a
SIGINTafter that abandons cleanup. Batect instead lets cleanup finish and then prints manual cleanup commands. OnlySIGINTabandons because a keyboard is the one thing that sends it twice — a supervisor’s timed follow-up is aSIGTERM, which only ever means “exit” — so a supervisor that escalatesSIGINT→SIGTERM→SIGKILLon a timer usually gets a finished cleanup before theSIGKILL, though a slow daemon can still lose that race. A run that had already finished when the signal arrived keeps its own exit code, since the signal ended nothing — unless the cleanup is then abandoned with something still to remove, which turns a0into125(decisions/0016). Batect fails such a run with-1(255) whatever its code was. Whatever an abandoned cleanup leaves still carries Ratect’s ownership labels, soratect resources list/cleanfinds it (ratect-only;ratect-compathas no equivalent verb, so from it the sweep isdockeritself, filtering the same labels). - The notice names the signal and the next step: a line on stderr such as
Interrupted; cleaning up. Press Ctrl+C again to force-remove what's left, and Ctrl+C after that to stop cleaning up., printed in every style whateverRUST_LOGsays. Once cleanup ends,Cleanup complete.follows, and noError: Interrupted— the exit code says the run was signalled, and a cleanup that left something behind is reported, in place ofCleanup complete., as the error it is, naming what was left and thedockercommand that removes it. Batect printsTask cancelled: Interrupt received during execution.and that it is waiting for outstanding operations, then its manual-cleanup commands.
SIGKILLremains untrappable by either tool, same underlying OS limitation — the same labels are what a post-hocratect resources cleanneeds to find what it left. - Ratect also traps
-
A closed stdout cleans up: a run whose stdout reader goes away (
| head -n 1) stops its containers, removes them and the task network, and exits141, with a notice on stderr saying why. Batect’s container output is written by its Go wrapper straight to its stdout, and Go’s runtime ends a process whose write to stdout meets a closed pipe bySIGPIPE— from reading its source rather than running it, the same141, with nothing cleaned up. Ratect matches the code and declines the leak (decisions/0013 rule 3). -
A run that fails without its task’s command exiting exits
125: a config that doesn’t load, an unknown task, an unreachable daemon, a failed image pull or build, a dependency that never becomes ready, a setup command that fails.125isdocker run’s own code for its own failure. Batect returns-1(255) for all of these, as for every failure other than the task’s own command exiting non-zero. Every other command —--list-tasks,--clean,--clean-cache— exits1on failure, or2for a usage error or an invalid option value; Batect’s is-1there too. See Exit codes and error reporting and decisions/0016. -
A cleanup that fails after a passing run exits
125; after a failing one, the task’s own code stands: the daemon refusing to remove a container or the task network fails a run whose containers all exited0, and leaves a run that already failed with its own code. Batect fails both with-1(255), so the task’s own code is lost whenever its cleanup fails. See decisions/0016. -
Ownership labels: every container and network Ratect creates carries
eu.orican.ratect.*labels; Batect labels nothing of its own. An additive divergence — changes no behavior. See decisions/0002. -
Task run locks: every task run holds a lock file,
~/.ratect/runs/<run>.lock, for as long as its process drives it, so thatratect resourcescan tell a leftover from a task run still going; Batect writes nothing per run. A task run that cleans up fully deletes its file. A run with no home directory, or one it can’t write, takes none and runs as before. Seeresourcesoptions and decisions/0025. -
Interactive mode: two known divergences. Batect’s real-TTY gate checks only whether its output is a real terminal; Ratect’s requires both stdin and stdout to be real terminals. Live terminal-resize tracking is also Unix-only — synced once at session start elsewhere, not tracked further. See Interactive Mode.
-
Proxy support: three deliberate differences — see Proxies for the full mechanics.
- A
localhostproxy is rewritten on Linux too. Batect rewrites on macOS/Windows only; on Linux it propagates the URL verbatim, wherelocalhostmeans the container itself. This is Batect’s oldest open issue, eight years old. - A proxy bound to loopback only is diagnosed, not left to fail — Batect’s own roadmap notes the same warning is needed and never shipped one.
--no-proxy-varskeeps the proxies in Docker’sconfig.jsonout of a build too. Batect’s flag only stops its own proxy build arguments; its Docker client adds theconfig.jsonones to every build regardless.
Batect’s Docker-version-gated hostname fallback chain, which reaches back to Docker 17.06, isn’t ported: its first choice,
host.docker.internal, is the one for Docker 18.03 and later, so every Docker release Ratect connects to would get it (see the Docker 20.10 entry under Runtime behavior gaps). - A
-
Private registry credentials: on a pull or a classic build, Batect’s own Go client swallows a credential-helper error (under BuildKit, BuildKit’s own auth provider passes it back to the daemon instead); Ratect warns, naming the registry that failed to resolve, or, for a build, the
credsStorewhose helper couldn’t list what it holds. See Private registry credentials. -
A dependency exiting unexpectedly is reported, not silent. Batect has no equivalent: a dependency that dies after becoming ready — while the task’s own command, or a later dependency’s own health/setup wait, is still going — is otherwise invisible until whatever depended on it fails for a confusing, unrelated-looking reason (a connection refused, a timeout). Ratect prints a progress line naming the container and its exit code instead, in every output style except
quiet. See Dependency Readiness. -
A control character from your configuration is printed escaped. In a name or value from your configuration (a task, container, image or cache name, a path, a command, a Git include’s
repoorref), in image build output, and in a value an error message quotes, ESC prints as\u{1b}and a carriage return as\r, so neither a config file nor a Git bundle can send your terminal escape sequences. Batect prints them as they are. A container’s own output is printed as written. Which line breaks and tabs are escaped as well is in Output Styles. -
allmode splits on a lone carriage return too, not just\n. Batect’sInterleavedContainerOutputSinksplits on\nonly, so a container using\rto redraw progress in place (pip/curl/apt-style) produces no output at all until its next\n, then dumps everything since as one giant concatenated line — or produces none at all, if the stream ends first. A deliberate divergence: Ratect also ends a line at a lone\r(one not immediately followed by\n— a CRLF pair still folds to a single line break), so a real progress bar prints one interleaved line per redraw tick instead of staying silent — spammier, but never silent-then-dumped. The split never adds an empty line: a\rwith nothing before it since the last line ended — a line’s first byte, or one of a run of them — ends no line, and an empty line is printed only if no\rhas ended a line since the previous\n. So10%\r\r20%prints10%and20%, and Ratect prints as many empty lines as Batect. A setup command’s output and an image build’sImage build |lines follow the same rule; a failed classic build’sBuild output:keeps each\ras Docker sent it. -
allmode prints a container’s last line even without a trailing newline. Batect prints a line only once its\narrives, so a container whose output ends without one loses that last line. Image build output follows the same rule. -
BuildKit build output leaves out plain-progress’s clock. Like Batect, Ratect shows a BuildKit build in BuildKit’s plain-progress form: a
#N <step>header as each step starts, steps that start together in docker-client’s order,#N CACHEDand#N ERROR: …, and every line of a step’s output labelled with its#N. It leaves out elapsed times (#4 0.412 …),DONE <duration>lines and status lines (transferring context: …), so a build prints the same lines from run to run. A failed BuildKit build’sBuild output:is the same labelled lines, so in it, unlike a classic build’s, a lone\rends a line. -
Failure messages are Ratect’s own. A task fails at the same step as under Batect — an image that won’t pull or build, a task network that can’t be created, a container that can’t be created, set up for
run_as_current_user, or started, a dependency that doesn’t become healthy, a failing setup command, a dependency cycle — but Batect’s headline and wording aren’t reproduced:Failed to pull image Xand itsCaused by:list, for example, rather thanCould not pull image X.and the daemon’s message — which, where the daemon refused a request, followsDocker responded with status code N:rather thanError response from daemon:— a failed build’s output underBuild output:rather thanOutput from Docker was:, andFailed to start container 'X'rather thanCould not run container X.. Arun_as_current_useror network failure is reported as itself, not, as Batect frames it, as a failure to create the container; either way the container is named as configured. See Load errors for the cause chain. The message is an unprefixedError: …line on stderr in every output style,allincluded, where Batect’sallprints<task> !or<container> !lines on stdout; andallreports a failed setup command or network check, two failures Batect’salldoesn’t print at all. A setup command’s output is trimmed, so output that is only whitespace counts as none. -
A failed task ends with a summary line, not Batect’s footer. Where Batect ends a task that failed to run with a red
The task X failed. See above for details.(on stderr, or on stdout as a<task> !line underall), Ratect ends it with<task> failed after <duration>., the counterpart offinished with exit code N, in the same place: the progress console, on the task’s prefix underall, and not at all underquiet. Nor does Ratect print Batect’s blank line before the error: the bold redError:marker separates it, and underquieta leading newline would be the first byte on stderr. -
No white text. Batect paints its
simplestatus lines,all’s task-level prefix,all’s innerSetup command N |andImage build |labels, and every linefancydraws (the startup block, the cleanup line,Running <task>...and the summary), in the terminal palette’s white (SGR 37) — light grey on a dark theme, near-invisible on a light one. Ratect’s own lines are the terminal’s default foreground, with bold for emphasis, and it never sets the palette’s white or black (decisions/0017). The interrupt notice, the--no-cleanup*reminder and a cleanup that left something behind are printed on stderr in every style rather than logged; Batect prints its equivalents on stderr too, except underall, which prints them on stdout with the task’s prefix, andquiet, which prints the interrupt notice and a failed cleanup’s error but no cleanup instructions. -
Cleanup says what it follows, and
allreports every step. After a failure,simpleandallopen cleanup by naming it —Cleaning up after <task> exited with code <N>..., or the step and container that failed, such asCleaning up after db did not become healthy...— rather than Batect’sCleaning up.... Underall, each container the run started saysContainer stopped.and thenContainer removed.on its own prefix, and the task’s prefix saysRemoving task network...andTask network removed.; Batect’sallprints each container’sContainer stopped.only (decisions/0017). -
all‘s prefix colours. Container prefixes cycle five colours — cyan, yellow, green, magenta, blue — assigned by the containers’ sorted names, so a container keeps its colour whatever order its task’s graph lists it in, and the task’s own prefix is bold in the default foreground. Batect cycles six starting at black, assigns them in its dependency graph’s order, and paints the task prefix white (decisions/0017). -
An unhealthy dependency’s error can lack the last health check’s details. If the container, or the daemon, goes away between Docker’s unhealthy verdict and Ratect looking up that check’s exit code and output, the error gives the verdict alone. Batect reports the failed lookup instead, or crashes.
-
A startup failure drops the rest of startup at once. When one of a task’s containers can’t be started — its image won’t pull or build, or it doesn’t become ready — whatever else was starting alongside it is dropped there and then, and cleanup begins. Batect cancels that work and waits for it to wind down first. A container whose create the daemon already had is still removed: cleanup waits for that create’s answer before it removes anything, as Batect waits for its creates to finish. A further signal ends that wait as it would a graceful stop — everything else is force-removed — and a warning names the container and the run label that finds it.
-
Docker 20.10 or newer is required. Ratect refuses a daemon whose API is older than 1.41 (Docker 20.10) when it connects — before any task runs, whether or not BuildKit is asked for — because its proxy support needs 20.10’s
host-gatewayaddress (see Installation). Batect’s floor is API 1.37 (Docker 18.03), so Docker 18.03 to 19.03 runs under Batect and is refused by Ratect. Below API 1.37 both refuse, in different words: Ratect’s error names the API version the daemon supports and the 1.41 it requires; Batect’s, in red, names the daemon’s Docker version. The exit code is any failure’s (see Exit codes and error reporting) —125on a run — where Batect’s is-1(255). Batect’s refusals of BuildKit on a daemon too old for it, or without experimental features turned on, apply only below Docker 18.09, so none could fire on a daemon Ratect accepts, and they aren’t ported. -
A task network name collision on Docker 20.10 to 24 fails later, and leaves the second run’s network behind. Batect sets the network create request’s
CheckDuplicateoption, which has the daemon refuse a second network with the same name. Ratect’s Docker client has no such option: API 1.44 deprecated it, since Docker 25’s daemon refuses a duplicate name without being asked. So on an older daemon a run that draws another run’s suffix creates a second network of that name, then fails at container creation or start rather than at network creation. Its network stays, anddocker network rm <name>refuses to remove either. Docker 25 and later refuse the duplicate network under Batect and Ratect alike. See Cross-task isolation. -
The daemon is first asked for its version, not pinged. Ratect’s first request is
/version; Batect sends/_pingand then asks for the version, before running anything. The image builder — BuildKit or the classic one — is chosen only once a run first builds an image, from a/_pingmade then (see--enable-buildkitunder CLI flags). And a daemon that can’t be reached, or is too old, is reported in Ratect’s own words, not Batect’sDocker is not installed, not running or not compatible with Batect: …— for an unreachable one, naming the host tried (see What is checked on connecting). -
A daemon running Windows containers is refused. Ratect checks the operating system the daemon reports and refuses
windowsbefore running anything, since it only supports Linux containers. Batect accepts a Windows daemon, and refuses only one reporting neither Linux nor Windows, which Ratect doesn’t check. -
The task network is ready before any image work starts. Ratect creates it — or, under
--use-network, checks that it exists — and only then pulls or builds an image, where Batect does both at once. So a network problem, such as a missing--use-networknetwork or an exhausted address pool, fails the task straight away, rather than once the pulls and builds already in flight have finished. -
Cleanup carries on past a container it fails to stop or remove. A container whose stop fails isn’t removed, as under Batect, but cleanup still stops and removes the task’s other containers, including the ones it depends on; Batect’s cleanup stalls there and leaves them running. Ratect also still goes on to remove the task network, where Batect keeps it and lists it among the manual cleanup commands it prints. While that container is still attached to the network, Docker refuses, and that refusal is reported in the same
Cleanup failed:error as the container’s, which lists both as left behind. -
A container or network already gone at cleanup isn’t a failure. When something else has already removed one — a dependency
docker rm -f’d mid-run, say — Docker answers cleanup’s stop or removal with404, and Ratect counts it as removed, since nothing is left behind: a passing run still exits0, andratect resources cleancounts one that disappears mid-sweep as removed. Batect fails the task’s cleanup on any error from that stop or removal,404included. -
A task with only
prerequisitessays so in every style butquiet. Once its prerequisites have run,The task <name> only defines prerequisite tasks, nothing more to do.is printed as under Batect, but not under-o quiet, which prints only errors, warnings and notices; Batect prints it in every style. -
What cleanup leaves is reported in one line, in every style. A
--no-cleanup*run reportsLeft in place (--no-cleanup): …, and a cleanup that failedError: Cleanup failed: …; left behind: …, each naming the containers by config name and short id and endingRemove with:onedocker rm -f -vfor every container, thendocker network rmfor the network. After a--no-cleanup*run, a line per kept container gives Batect’sdocker logsanddocker exec -ithints, withdocker startfirst for one that isn’t running. Where they differ from Batect’s:- They are printed under
-o quiettoo; Batect’squietprints none of them. - After a failed cleanup only what was actually left behind is listed; Batect lists a command for every container and network the run created, removed or not, and says “some or all” of them may be needed.
- Containers are named by the twelve-character id
docker psshows, and the network by its name; Batect gives each container’s full id and the network’s id, onedocker rm --force --volumesper container. - Under
-o alla failed cleanup is that oneError:line, with no container prefix; Batect printsCould not stop container <name>.orCould not remove container <name>.on each container’s own prefix, andCould not delete the task network.on the task’s.
- They are printed under
-
A crash skips cleanup. If Ratect itself crashes mid-run — a bug, which exits
101and asks for a report — the run’s containers and network are left behind. Batect catches an internal error in a step and still cleans up. What a crash leaves carries Ratect’s ownership labels:ratect resources cleanremoves it (ratect-only), and fromratect-compat, which has no such command,dockerdoes, filtering on the project’s label —docker rm -f -v $(docker ps -aq --filter label=eu.orican.ratect.project=<project>), then the same filter ondocker network ls -qfordocker network rm. -
No pull lines for an image that’s already local. Under
image_pull_policy: IfNotPresent, an image that’s already present prints noPulling X.../Pulled X.lines; Batect prints both even though nothing is pulled. See Task Lifecycle. -
Under
image_pull_policy: Always, an image is pulled once per run, not again for each task in a prerequisite chain that uses it, as Batect does. Abuild_directoryimage is likewise built once per run, where Batect builds it again for each task — and, underAlways, pulls its base image again each time. See Task Lifecycle. -
fancymode draws a fresh block after the terminal’s width changes. The terminal has re-wrapped the old lines by then, so moving the cursor back up over as many lines as were drawn, as Batect does, lands it in the wrong place on common terminals and corrupts the display. Ratect leaves the old block where it is and draws the new one below it, at the cost of that leftover block. -
fancymode names the image it pulls, and calls a ready dependencyready. A container’s line readsready to pull image <image>and thenpulling image <image>..., where Batect’s readsready to pull imageandpulling <image>.... A dependency that has passed its readiness gate — healthy, and its setup commands done — readsready, where Batect’s readsrunning, which would fit a container that has started but isn’t yet healthy just as well. -
fancymode shows no cleanup line when cleanup is off. Under--no-cleanupor--no-cleanup-after-success, Batect briefly showsCleaning up: N containers (...) left to remove...when the task’s container exits, though nothing will be removed. Ratect shows none. -
fancymode draws a multi-line setup command on one row. Each line break in it is shown as a space, and the command runs as usual. Batect can’t draw it, and fails the task with an unexpected-exception error and exit code 255 before the command runs — which a|block’s trailing newline is enough to cause, even for a one-line command. -
fancymode treats a reported terminal width of 0 as unknown. Some pseudo-terminals report it (script‘s, some CI runners’), and lines are then printed unclipped; Batect clips every line to nothing. -
Under
run_as_current_user, a mount point nested inside alocalmount is created with the type its source needs. For a file or socket mounted inside alocalmount —./config.jsonat/code/config.jsonunder.at/code— Ratect creates an empty file at the mount point, and the mount works. Batect always creates a directory there, which fails the run: a file or socket can’t be mounted over a directory, and an existing file at the mount point fails the creation itself. Ratect also follows a symlink on the way to a mount point only while it stays inside the enclosing mount’s host directory, leaving the mount point to the daemon otherwise; Batect follows it even out of that directory, creating the mount point outside the project. See User mapping.
Next steps
The behaviour both binaries share is documented in its own right rather than against Batect: Task Lifecycle for what a run does step by step, Dependency Readiness for when a dependency counts as ready, Includes for how included files combine and what a Git bundle may do, and the FAQ.