Skip to main content
A Filetrace version tells you when its release line was cut, which patch of that line it is, and how far it is from the release before it. This page explains the version format, the stable and lts channels, release candidates and untagged builds, how the installer, the package repositories and Homebrew map to the channels, and what happens on an upgrade.

​
Version format

A version reads year.month.patch.build. 26.11.1.80 is the first release of the line cut in November 2026, 80 commits after the release before it. One line opens per month. A second release in the same month is a patch of that line.

​
Tags and files

A release is tagged with its version and the channel of its line, such as v26.11.1.80-stable. Its files are published as the assets of the GitHub release and under https://filetrace.eorlov.org/dist/<tag>/: A published release is never changed. A bad release is followed by a patch. Security explains how to verify the files.

​
Release lines and channels

Each release line is either a stable line or an lts line, an lts line being one that keeps receiving patches. The tags of its releases say which (-stable or -lts). The package repositories and the installer offer two channels built from them: Fixes go into the newest release line and into the lts lines. Follow lts to receive only the releases of those lines, or stable to follow the newest release.

​
Release candidates

A release tagged -prestable is a candidate. It is published as a GitHub pre-release and its files appear under https://filetrace.eorlov.org/dist/<tag>/, but it reaches no package repository, no Homebrew formula and no installer channel. The release that follows counts its build number as if the candidate were not there. To try a candidate, download its archive from the pre-release.

​
Builds without a release tag

A build from a commit that carries no release tag reports the release before it and the distance from it: 26.11.1.80+5.gabc1234 is 5 commits after 26.11.1.80, at commit abc1234. A build from a tree with no release in its history reports 0.0.0.<commits>+g<commit>, and uncommitted changes add dirty after the +.

​
Which version is installed

filetrace version prints the version of the command, and whether the agent is running:
filetrace-agent --version prints the version of the agent binary, and the version field of filetrace stats --json that of the running agent.

​
Channels by install method

The installer accepts FILETRACE_CHANNEL and FILETRACE_VERSION in place of --channel and --version:
The package version is the Filetrace version, so the package manager’s own commands show and pin it. To move a host to another channel, change stable to lts (or back) in its repository definition, or run the installer again with --channel. Installation shows the repository definitions in full.

​
Homebrew

The tap orlovevgeny/filetrace has a formula filetrace for the newest release and a formula filetrace@<line> for each release line, which follows the releases of that line only and is keg-only:
Homebrew installs the programs only, on macOS 15 or later and on Linux, without a service.

​
Upgrades

  • An upgrade never overwrites /etc/filetrace/config.toml.
  • The command and the agent speak one protocol version, so an upgrade restarts a running agent. The deb, rpm and apk packages, and the installer when it upgrades an archive installation, first run filetrace config validate. If the new version does not accept the configuration file, they leave the running agent alone and warn:
    Fix what filetrace config validate reports, then restart filetrace-agent.
  • An upgrade does not start an agent that was stopped.
  • A command that reaches an agent of another protocol version fails with exit code 1:
  • Homebrew installs no service. Restart an agent that you run yourself after upgrading the formula.