Oda's home folder and settings files

DataMind Oda keeps the settings it saves, the caches it builds and the paths it watches on your computer inside one home folder. This page shows how Oda chooses that folder, how it shows the location, and what keeps a settings save safe. What the settings file itself contains is on The Oda settings file.

How Oda chooses the home folder

Oda uses the first of these that is actually set:

1. A folder path chosen for the run.
2. The home folder named in the environment Oda starts in.
3. The default: a folder inside your user folder.

• Blank values do not count. A value that is empty, or only spaces, is ignored, and Oda falls through to the next choice. An empty value never resolves the home to the folder Oda was started from.
• A leading ~ stands for your user folder. A configured path may begin with ~ or ~/, and Oda expands it to your user folder; a name after the tilde, such as ~name, is taken as written.
• Caches live there too. The caches Oda builds as it works sit in a cache folder under the chosen home. Oda derives cache paths from the same home as the settings files, and working out a path creates nothing on the computer.

How the folder is shown

• A short form. Oda writes the home folder in a short form such as ~/<folder>, where ~ stands for your user folder. A home you set yourself is shown by the name of the setting you used.
• Never the full path. The full path on your computer is not written into what Oda shows you, so a message you copy or share does not reveal your machine's layout.
• The ~ shorthand is for POSIX-style paths. Where Oda shortens a displayed path with ~, a Windows-style path is not abbreviated this way; it is shown as it is.
• Links are built from text. When Oda builds a path into a link or a preview, it works by text alone: it does not look the path up on the computer, and a . or .. part stays as written.

What keeps a settings save safe

When Oda saves a settings file, it does not rewrite the file in place. It works in three steps:

1. It takes the lock. Oda creates a lock file beside the settings file: the file's name plus .lock. The lock file records the process that is writing, so a second save waits instead of writing at the same time; reading is never blocked, because only writers contend. If another write holds the lock, Oda waits with pauses that start small and grow, up to about two seconds by default, and then stops waiting instead of writing. A save that has a slower step to wait for, such as a network round trip, can be given more time.
2. It writes beside the target. Oda writes the new content to a temporary file next to the settings file, then renames it over the target. Anyone reading at that moment sees the old file or the new one, never something written halfway.
3. It cleans up. Oda removes the lock when the save ends, and removes the temporary file if the save could not finish. A failed save leaves the settings file as it was, and a waiting save never removes a lock it did not create.

Two more behaviours you may meet:

• Windows retries. On Windows, a brief sharing error, such as another program holding the file open for a moment, is retried before the save gives up; if the file still cannot be replaced, the save does not happen and the file keeps its old content.
• Links and permissions. If the path is a symbolic link, Oda replaces the link itself and leaves the file it points to alone. A replacement is created with the permissions Oda sets for settings files, so a file that had wider permissions is narrowed to them.

Changes you save in settings forms are written this way; Live plugin settings covers those forms. For what the settings file contains and when you may edit it, see The Oda settings file.

When a save waits too long

If the wait for the lock runs out, the save does not happen, and Oda reports that it timed out waiting for the writer lock, naming the lock file's path. Try the change again. If it keeps failing, follow Updates and troubleshooting.

What a crash leaves behind

• The settings file stays whole. The switch to the new content is a single step, so after a crash the file holds the old content or the new one, never something half-written.
• The lock can survive. A crash can leave the lock file behind, and later saves then wait for it and time out. A stale lock is removed only after checking that no writer still owns it.

• One case it does not cover. The replacement is not flushed for a sudden power loss, so the very newest save can be lost that way.

Where start values come from

Oda reads its start values from three places, in order:

1. The environment Oda is launched with.
2. A settings file in the folder Oda is launched from.
3. A settings file in the home folder.

A value from a higher place wins over one from a lower place. Oda takes this snapshot once, when it starts, so a later folder change does not affect the run in front of you.

A settings file cannot make Oda treat a run as an SSH run. Oda decides that from the environment it was launched in, never from a settings file. See SSH remote execution. The full rules for these files, including the values a file may not set, are on Startup and diagnostics.

Watching a path before it exists

Oda also watches paths for changes. A path does not have to exist yet: Oda resolves the deepest folder in the path that already exists and keeps the rest, so the path is under watch from the moment it is created. If the nearest part of the path that exists is a file rather than a folder, the path is refused. What a watch does with a change is on Hot reload.

Questions, answered

Where is Oda's home folder?

By default it is a folder inside your user folder; it can also be chosen for the run or named in the environment Oda starts in. The settings files Oda saves and the caches it builds live under it. Oda shows the location in a short form, never the full path.

Can I move Oda's home folder?

Yes. Name the folder you want in the home setting of the environment you start Oda in, and Oda uses it the next time it starts. A blank or spaces-only value is ignored, so an empty setting moves nothing. The caches Oda builds live under the folder as well.

Why does Oda shorten folder paths when it shows them?

Oda writes the home folder in a short form such as ~/<folder>, where ~ stands for your user folder, and a home you set yourself is shown by the name of the setting you used. The full path on your computer is never written into what Oda shows you. The ~ shorthand covers POSIX-style paths; a Windows-style path is shown as it is.

A save timed out waiting for the writer lock. What should I do?

Another save was in progress, or a crashed writer left its lock file behind. Try the change again. If it keeps failing, do not remove the lock file yourself; follow Updates and troubleshooting.

What happens if two settings saves run at the same time?

One takes the lock and writes; the other waits with pauses that start small and grow, up to about two seconds by default, and only then stops instead of writing. The two saves never write at the same time, and a waiting save never removes a lock it did not create. Reading is never blocked.

Can a settings file be left half-written?

No. Oda writes the new content to a temporary file beside the target and renames it over the target in a single step, so a reader sees the old file or the new one. A save that fails removes its temporary file and leaves the settings file as it was.

What happens if Oda or my computer crashes during a save?

The settings file holds the old content or the new one, never something half-written. The lock file can survive the crash, and later saves then wait for it and time out until it is removed. A sudden power loss is the one case Oda does not cover: the replacement is not flushed for it, so the very newest save can be lost.

How does Oda combine values from the environment and from settings files?

It reads them in order: the environment Oda is launched with, then a settings file in the folder you launch from, then a settings file in the home folder. A value from a higher place wins over one from a lower place.

Why did changing the folder I launch Oda from not change anything?

Oda takes its snapshot of these values when it starts, so a later folder change does not affect the run in front of you. Start Oda again from the new folder to use its values.

Can a settings file make Oda treat my run as an SSH run?

No. Oda treats a run as remote only when the environment it was launched in says so; a settings file cannot establish an SSH session. See SSH remote execution.

Can a path be watched before it exists?

Yes. Oda resolves the deepest folder in the path that already exists and keeps the rest, so the path is under watch from the moment it is created. If the nearest existing part is a file rather than a folder, the path is refused.