format

Every folder you ask ARMED to watch gets a standard git history inside it, created and maintained by the engine. It is not a database, not a private container and not a format we invented: any git client on any platform opens it, with or without ARMED, now or in ten years.

1. a saveA point on the history of the variation it was made on, carrying the same sentence ARMED showed you as its message — ~ track volume “Drums MAIN” 1.00 → 0.85.
2. a variationA line of history under refs/heads/, named song/<file-slug>/<variation>. One per song, so two songs in one folder never share a history.
3. a named version of a songA marker named armed/song/<file-slug>/<name> under refs/tags/.
4. an album versionA frozen list on refs/armed/versions, pinning every song in the folder to one variation and one point on it. The safety snapshot ARMED takes before restoring an album version is named auto/<timestamp>.
5. a mergeAn ordinary point with two parents. Nothing about it is special to ARMED.

Three commands, run against your own project folder. The first lists a variation's history; the second writes any past version of the file out beside it; the third lists every named song version.

git -C "~/Music/My Project" log --oneline song/Track.als/main
git -C "~/Music/My Project" show <id>:Track.als > old-version.als
git -C "~/Music/My Project" for-each-ref refs/tags/armed

An .als is gzipped XML, and ARMED stores the exact bytes Ableton wrote — the original gzip, unmodified. Any version you pull out this way opens in Live like the file it is.

In it: your .als project files. Every save ARMED records is the whole file as Ableton wrote it. A save ARMED could not parse is stored whole as well, and still comes back.

Not in it: your audio. ARMED does not version samples, recordings or renders. Samples/, and any .wav, .aif, .mp3, .flac, .ogg or .asd file beside your project, is left exactly where it is on disk and is never copied into the history. This is a real limit and not a detail:

1. restoring rewrites the .als onlyRestoring a version, or switching to another variation, changes the project file and nothing else. The audio beside it does not move.
2. and ARMED will not warn youIf the version you restore expects a sample you have since deleted, renamed or re-rendered, Live opens the restored set pointing at the wrong file or at none at all. ARMED cannot detect this and does not warn you about it.
3. so keep your own backups of Samples/ARMED's history is not one. Back your audio up the way you already do.

One folder, ~/.armed, on your own Mac: which folders you asked it to watch and your settings (config.toml), the projects it found while scanning (discovery.json), which variation each song is on (state/), a cache it uses to work out what changed between saves (ast_cache/), the local socket the app and the engine talk over (daemon.sock), a lock file, and the engine's own log (daemon.log, daemon.err).

All of it is settings or working state. None of it is your history. Delete ~/.armed and you lose which folders ARMED was watching; every version inside every project folder is untouched. What each of those files holds, and where else ARMED writes, is on the privacy page.

Changes to this format will be additive, or migrated for you automatically. This page changes in the same release as the format it describes — not the next time somebody notices.

Clause 2 of the license says everything ARMED writes lives on your disk in a documented format and is yours. This is that document. The point of closing the source and opening the format is that none of this has to be taken on trust: the layout above is checkable against your own project folder in about a minute.