Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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 include types beyond file/git are 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:

FieldNotes
config_variablesdescription: is recognized but inert — Ratect has no help/usage output to show one in.
includeRatect 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_telemetryRecognized, 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_directory has its . and .. components resolved: -f ../proj/batect.yml gives /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 — in environment or build_args.

Container fields

Every other container field is supported field-for-field — see config reference for the full list. The exceptions:

FieldNotes
imageAn 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.
volumesA 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.
portsA 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.
dependenciesA 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_dropAlso 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_commandsA 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.
dockerfileA 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_optionsAn 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_sizeA 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_userA .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-tasks included — 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 under dependencies in Container fields, they include a run_as_current_user home_directory that isn’t an absolute path, and a relative cache mount destination under run_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’s customise naming a container its task doesn’t start, or its run.container also listed in its dependencies, checked for every task rather than only the ones run. --tag-image on 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_check duration, 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 than The file '<absolute path>' does not exist., and likewise for malformed volumes, ports, devices and includes, expressions, durations, duplicate build_ssh ids, an undeclared config variable given a value — which names the variable but neither which of --config-var and --config-vars-file gave 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 sets forbid_telemetry to true. 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.yml or 1.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 the Failed 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: X with no list of the known ones, missing field: X, and for a value of the wrong type the path and the mismatch, with no Value for 'X' is invalid: prefix — a refused null is invalid type: null, expected <what the field takes>, as in containers.app.shm_size: invalid type: null, expected a size like '128', ..., where Batect says Unexpected 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 is tasks.t: duplicate key "t" at line 9, column 3, giving only the second occurrence’s line, where Batect’s Duplicate 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 a Caused by: list when there is a cause, where Batect prints one message. A parse error’s own reason is in that list, under Failed 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 customise entries 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-image container name is looked up, a duplicate build_ssh id 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. A command, entrypoint or setup command that can’t be tokenized is reported after every error raised while the files are parsed, after every container’s image source, image expressions, dns entries and fields its file’s format doesn’t allow are checked, and after the same container’s volumes, build_directory and build_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:

FlagNotes
--versionPrints 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 / -hThe 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 / -TThe 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-imageA 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_ARGSWhen 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 / -oAn 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-colorA 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-successBatect’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-keyBatect’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-keyA 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-contextA 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-hostAn 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-hostA 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-configA 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-contextAn 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-buildkitAn 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-pathA 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-buildkitAn 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-typeUnlike 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-cacheUnder --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-parallelismBatect’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-fileBatect’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-infoNot 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-cleanupRecognized, 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: an error: … line in its own words, sometimes followed by a tip or a usage line, then For more information, try '--help'. Batect prints a single message of its own instead, such as Invalid option '--bogus'. Run './batect --help' for a list of valid options. The exit code is 125 on a line meant to run a task, docker run’s code for its own failure, and 2 on one that replaces the task with --list-tasks, --clean, --clean-cache or --upgrade, the usage-error convention clap and the POSIX utilities share. So is an option value that fails its own check, such as a -f or --config-vars-file naming no file, a batect.local.yml that isn’t a file, or a BATECT_CACHE_TYPE that is no cache type. Batect’s is -1 (255) for both, the same as for any other failure (decisions/0016).
  • --help and --version exit 0 even when an option’s value or default is invalid — a --docker-config naming no directory, a batect.local.yml that isn’t a file, or a bad BATECT_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 --help exit -1 (255) instead (decisions/0016).
  • Short options combine, and take an attached value: -Tf batect.yml, -fbatect.yml and -oquiet are 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 -x and --clean-cache --list-tasks are 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 $HOME first, when it is set and absolute, then the passwd entry’s, as in the Docker CLI. Batect uses the JVM’s user.home, which is the passwd entry’s whenever there is one, so where it and $HOME differ Batect reads a different ~/.docker from the one docker login wrote, 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.home depends on the JDK: $HOME on 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 traps SIGINT only:

    • Ratect also traps SIGTERM and SIGHUP, 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/129 for 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 SIGINT after that abandons cleanup. Batect instead lets cleanup finish and then prints manual cleanup commands. Only SIGINT abandons because a keyboard is the one thing that sends it twice — a supervisor’s timed follow-up is a SIGTERM, which only ever means “exit” — so a supervisor that escalates SIGINT → SIGTERM → SIGKILL on a timer usually gets a finished cleanup before the SIGKILL, 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 a 0 into 125 (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, so ratect resources list/clean finds it (ratect-only; ratect-compat has no equivalent verb, so from it the sweep is docker itself, 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 whatever RUST_LOG says. Once cleanup ends, Cleanup complete. follows, and no Error: Interrupted — the exit code says the run was signalled, and a cleanup that left something behind is reported, in place of Cleanup complete., as the error it is, naming what was left and the docker command that removes it. Batect prints Task cancelled: Interrupt received during execution. and that it is waiting for outstanding operations, then its manual-cleanup commands.

    SIGKILL remains untrappable by either tool, same underlying OS limitation — the same labels are what a post-hoc ratect resources clean needs to find what it left.

  • 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 exits 141, 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 by SIGPIPE — from reading its source rather than running it, the same 141, 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. 125 is docker 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 — exits 1 on failure, or 2 for a usage error or an invalid option value; Batect’s is -1 there 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 exited 0, 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 that ratect resources can 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. See resources options 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 localhost proxy is rewritten on Linux too. Batect rewrites on macOS/Windows only; on Linux it propagates the URL verbatim, where localhost means 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-vars keeps the proxies in Docker’s config.json out of a build too. Batect’s flag only stops its own proxy build arguments; its Docker client adds the config.json ones 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).

  • 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 credsStore whose 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 repo or ref), 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.

  • all mode splits on a lone carriage return too, not just \n. Batect’s InterleavedContainerOutputSink splits on \n only, so a container using \r to 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 \r with 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 \r has ended a line since the previous \n. So 10%\r\r20% prints 10% and 20%, and Ratect prints as many empty lines as Batect. A setup command’s output and an image build’s Image build | lines follow the same rule; a failed classic build’s Build output: keeps each \r as Docker sent it.

  • all mode prints a container’s last line even without a trailing newline. Batect prints a line only once its \n arrives, 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 CACHED and #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’s Build output: is the same labelled lines, so in it, unlike a classic build’s, a lone \r ends 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 X and its Caused by: list, for example, rather than Could not pull image X. and the daemon’s message — which, where the daemon refused a request, follows Docker responded with status code N: rather than Error response from daemon: — a failed build’s output under Build output: rather than Output from Docker was:, and Failed to start container 'X' rather than Could not run container X.. A run_as_current_user or 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 unprefixed Error: … line on stderr in every output style, all included, where Batect’s all prints <task> ! or <container> ! lines on stdout; and all reports a failed setup command or network check, two failures Batect’s all doesn’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 under all), Ratect ends it with <task> failed after <duration>., the counterpart of finished with exit code N, in the same place: the progress console, on the task’s prefix under all, and not at all under quiet. Nor does Ratect print Batect’s blank line before the error: the bold red Error: marker separates it, and under quiet a leading newline would be the first byte on stderr.

  • No white text. Batect paints its simple status lines, all’s task-level prefix, all’s inner Setup command N | and Image build | labels, and every line fancy draws (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 under all, which prints them on stdout with the task’s prefix, and quiet, which prints the interrupt notice and a failed cleanup’s error but no cleanup instructions.

  • Cleanup says what it follows, and all reports every step. After a failure, simple and all open cleanup by naming it — Cleaning up after <task> exited with code <N>..., or the step and container that failed, such as Cleaning up after db did not become healthy... — rather than Batect’s Cleaning up.... Under all, each container the run started says Container stopped. and then Container removed. on its own prefix, and the task’s prefix says Removing task network... and Task network removed.; Batect’s all prints each container’s Container 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-gateway address (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) — 125 on 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 CheckDuplicate option, 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, and docker 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 /_ping and 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 /_ping made then (see --enable-buildkit under CLI flags). And a daemon that can’t be reached, or is too old, is reported in Ratect’s own words, not Batect’s Docker 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 windows before 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-network network 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 with 404, and Ratect counts it as removed, since nothing is left behind: a passing run still exits 0, and ratect resources clean counts one that disappears mid-sweep as removed. Batect fails the task’s cleanup on any error from that stop or removal, 404 included.

  • A task with only prerequisites says so in every style but quiet. 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 reports Left in place (--no-cleanup): …, and a cleanup that failed Error: Cleanup failed: …; left behind: …, each naming the containers by config name and short id and ending Remove with: one docker rm -f -v for every container, then docker network rm for the network. After a --no-cleanup* run, a line per kept container gives Batect’s docker logs and docker exec -it hints, with docker start first for one that isn’t running. Where they differ from Batect’s:

    • They are printed under -o quiet too; Batect’s quiet prints 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 ps shows, and the network by its name; Batect gives each container’s full id and the network’s id, one docker rm --force --volumes per container.
    • Under -o all a failed cleanup is that one Error: line, with no container prefix; Batect prints Could not stop container <name>. or Could not remove container <name>. on each container’s own prefix, and Could not delete the task network. on the task’s.
  • A crash skips cleanup. If Ratect itself crashes mid-run — a bug, which exits 101 and 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 clean removes it (ratect-only), and from ratect-compat, which has no such command, docker does, filtering on the project’s label — docker rm -f -v $(docker ps -aq --filter label=eu.orican.ratect.project=<project>), then the same filter on docker network ls -q for docker network rm.

  • No pull lines for an image that’s already local. Under image_pull_policy: IfNotPresent, an image that’s already present prints no Pulling 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. A build_directory image is likewise built once per run, where Batect builds it again for each task — and, under Always, pulls its base image again each time. See Task Lifecycle.

  • fancy mode 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.

  • fancy mode names the image it pulls, and calls a ready dependency ready. A container’s line reads ready to pull image <image> and then pulling image <image>..., where Batect’s reads ready to pull image and pulling <image>.... A dependency that has passed its readiness gate — healthy, and its setup commands done — reads ready, where Batect’s reads running, which would fit a container that has started but isn’t yet healthy just as well.

  • fancy mode shows no cleanup line when cleanup is off. Under --no-cleanup or --no-cleanup-after-success, Batect briefly shows Cleaning up: N containers (...) left to remove... when the task’s container exits, though nothing will be removed. Ratect shows none.

  • fancy mode 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.

  • fancy mode 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 a local mount is created with the type its source needs. For a file or socket mounted inside a local mount — ./config.json at /code/config.json under . 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.