Skip to content

Allow relocating Aegisub's files with environment variables - #731

Draft
CoffeeFlux wants to merge 1 commit into
TypesettingTools:masterfrom
CoffeeFlux:env-path-overrides
Draft

CoffeeFlux wants to merge 1 commit into
TypesettingTools:masterfrom
CoffeeFlux:env-path-overrides

Conversation

@CoffeeFlux

@CoffeeFlux CoffeeFlux commented Oct 9, 2026 •

Copy link
Copy Markdown
Member

Adds three environment variables, read once at startup:

Variable Effect
AEGISUB_DATA_DIR Replaces ?data, the bundled files (automation includes and autoload, etc.)
AEGISUB_USER_DIR Used for all per-user files (settings, user scripts, logs, autosaves, caches) instead of the platform's default locations
AEGISUB_CONFIG The config file to use instead of the one in the user dir

Empty values count as unset, and relative paths are resolved against the working directory at startup.

Why

  • Running an uninstalled build. On Linux ?data is compiled in as the install prefix. Since the Lua support modules (moonscript.lua etc.) are now only loaded from ?data, an uninstalled build can't run automation scripts. AEGISUB_DATA_DIR=<source tree> fixes that, and the CLI end-to-end tests in Headless CLI #670 need it.
  • Clean or separate profiles. AEGISUB_USER_DIR gives a throwaway or per-project profile without touching the real one, the way BLENDER_USER_RESOURCES, KICAD_CONFIG_HOME or Chrome's --user-data-dir do. Headless CLI #670 will add matching command-line flags for CLI mode, using the same code.

Details

One place for the per-user directories. AEGISUB_USER_DIR and Windows portable mode both go through the new agi::Path::SetUserDir, which currently points ?user and ?local at the given directory. Caches move along with everything else; mpv's --config-dir is a known trap for not doing that. Any per-user directories added later then only need adding there. For example, #264's ?state needs to be, or AEGISUB_USER_DIR and portable mode would leave logs and autosaves in the default location.

Precedence: AEGISUB_USER_DIR, then Windows portable mode (a config.json next to the executable), then the platform default. AEGISUB_CONFIG applies whichever user dir wins, so it can be combined with a clean user dir.

?dictionary isn't moved by AEGISUB_DATA_DIR, even on platforms where it's derived from ?data.

Directories that are files. If AEGISUB_DATA_DIR or AEGISUB_USER_DIR points at a file, it's ignored with a warning in the log. Otherwise agi::Path would silently use the file's parent directory.

Testing

Tested on macOS with the GUI:

  • With all three set, the log and hotkey.json were created in the given user dir, the config was read from the given file, and an autoload script in the given data dir's automation/autoload was loaded. Nothing new appeared in the real profile.
  • With AEGISUB_USER_DIR pointing at a file, the warning was logged and the default location used.

The Windows-specific bits (_wgetenv and the portable-mode precedence) are only compile-tested by CI.

🤖 Generated with Claude Code

@CoffeeFlux
CoffeeFlux marked this pull request as draft October 9, 2026 04:52
AEGISUB_DATA_DIR replaces ?data (the bundled files), AEGISUB_USER_DIR is
used for all per-user files (settings, scripts, logs and caches) instead
of the platform's default locations, and AEGISUB_CONFIG is the config
file to use instead of the one in the user dir. This makes it possible
to run an uninstalled build against the source tree, which the upcoming
CLI tests need now that the Lua support modules are only loaded from
?data, and to run Aegisub with a clean profile without touching the
real one.

An explicit AEGISUB_USER_DIR takes precedence over portable mode on
Windows. Both now go through Path::SetUserDir, so that any per-user
directories added in the future only need to be handled in one place.
The directory variables are ignored with a warning if they point at a
file, since agi::Path would otherwise silently use its parent directory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant