Files and environment variables

The files Oak reads in a repo and in your home directory, and every environment variable.

Markdown

All pages

In a repository#

PathVersioned?Purpose
.oak/—The local repository: its database (.oak/oak.db), in-progress merge state, and hooks. Never committed, except the file below.
.oak/attributesYesReserved for per-path attributes.
.oak/hooks/pre-commit, post-commitNoLocal hooks.
.oakignoreYesFiles Oak should ignore, in .gitignore syntax.
.gitignoreYesUsed only when there's no .oakignore.
AGENTS.md, CLAUDE.mdYesInstructions for coding agents; oak init offers to write them.
.claude/skills/oak-vcs/YesThe agent skill, from oak skill install.

In your home directory#

PathPurpose
~/.local/bin/oakThe CLI, where the installer puts it.
~/.config/oak/credentialsSaved logins, one per server (from oak login).
~/.config/oak/version_checkWhen the CLI last checked for an update.
~/.config/oak/feedback.jsonThe contact email oak feedback remembers.
~/.claude/skills/oak-vcs/The agent skill, from oak skill install --global.

If XDG_CONFIG_HOME is set to an absolute path, Oak uses $XDG_CONFIG_HOME/oak instead of ~/.config/oak. Versions before 0.118 kept these files in ~/.oak/; the CLI moves each one the first time it needs it, and removes ~/.oak/ once nothing else is left in it.

Environment variables#

oak environment (or oak env) prints every variable below with its effective value — secrets as set/unset only.

Server and credentials#

VariableEffect
OAK_REMOTEServer URL for this invocation, overriding the checkout's linked server.
OAK_API_KEYToken to authenticate with. Beats every stored credential. See API keys.
OAK_REPOorg/repo to link on a first push — the same as oak push --repo.
OAK_BROWSERCommand oak login runs to open its URL instead of the system browser. A command that fails (such as false) switches to pasting a code.

Identity#

VariableEffect
OAK_AUTHORAuthor name on commits, and the prefix of generated branch names. Defaults to your login, then USER / USERNAME.
OAK_EMAILContact email for oak feedback.

Network#

VariableEffect
OAK_NO_UPDATE_CHECKTurn off the daily check for a new CLI version.
OAK_URLWhere oak upgrade and the update check download releases (default https://oak.space).
OAK_UPLOAD_CONCURRENCYParallel uploads during push.
OAK_PRELOAD_CONCURRENCYContent uploads in flight before a large push publishes (default 3).
OAK_DOWNLOAD_CONCURRENCYParallel downloads during clone and pull (default 32).
OAK_PROBE_TIMEOUT_SECSTimeout in seconds for read-only server probes, 1–300 (default 20; 5 for the main head check in oak start, oak switch -c and oak merge --dry-run).
OAK_ALLOW_PARTIAL_CLONERecovery only: skip files a broken server can't send instead of failing.
HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, NO_PROXYStandard proxy settings (lowercase forms too).

Output#

VariableEffect
OAK_TIMINGSPrint per-phase timings, like --timings.
OAK_LOGLog filter for debugging (for example OAK_LOG=debug).
OAK_PROGRESSalways, never, or auto progress display.
OAK_SPINNERSpinner style: line, pulse, arc, minimal, oak.
NO_COLOR, CLICOLOR_FORCEDisable or force color.
CIWhen set, progress display is off by default.

Tools#

VariableEffect
OAK_DIFF_TOOLExternal program to use instead of oak diff's viewer.
PAGERPager for long output.
VISUAL, EDITOREditor for oak feedback (falls back to vi).

Set by Oak#

VariableWhere
OAK_HOOKIn hooks: the event name.
OAK_COMMIT, OAK_MARK and the restIn the script oak mark follow runs: see Following a mark.

Installer#

VariableEffect
INSTALL_DIRWhere install.sh / install.ps1 put the binary.
OAK_NO_LOGINSkip the installer's login prompt.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].