Every user-visible capability of github.com/ubgo/appdir, read from the code, with the guide section that explains it and the example that runs it. An example is linked only when its code calls the feature's API (checked by searching the example's Go files for the identifier, variable or file the feature is about). A dash with a reason means the feature cannot run here (Windows only, root only, two disks, a property); a plain dash means no example calls it yet. For the order to read the guides in, see the learning path.
| Feature | Package | Guide | Example |
|---|---|---|---|
New(app, opts...) resolves every home and path in one call and creates nothing |
appdir |
First use: resolve with New | quickstart |
App name must match ^[a-z0-9][a-z0-9._-]*$, else ErrInvalidOption |
appdir |
First use: pick an app name | quickstart |
Reads never create: New, Path, Paths only stat folders and read home.jsonc and pointer keys |
appdir |
First use: resolve with New | quickstart |
Path(kind) returns a kind's path in its effective home |
appdir |
First use: Path and PathIn | quickstart |
PathIn(kind, scope) returns a kind's path in one named home (global or project) |
appdir |
First use: Path and PathIn | quickstart, prod-db-guard |
Ensure(kind) creates a kind's folder (or a file kind's parent) on first use and returns the path |
appdir |
First use: Ensure | quickstart |
InitProject(dir) creates .<app>/ with home.jsonc: the only way a project home is made |
appdir |
Init: InitProject | project-init |
InitProject refuses to turn the global home into a project home |
appdir |
Init: refuse the global home | project-init |
InitHome(path, scope) creates a home anywhere (<app> init --home X, pointer targets) |
appdir |
Init: InitHome | project-init, pointers |
InitHome on a folder holding another app's home.jsonc fails with ErrNotHome; on this app's home it is a no-op; a home.jsonc that does not parse is ErrBadHomeFile and stays untouched |
appdir |
Init: InitHome | project-init |
home.jsonc (app, layout, scope) is written atomically: temp file, fsync, rename, Windows retry |
appdir |
Init: InitProject | project-init |
InitProject(dir) with a relative dir resolves it against the working folder New used (WithWorkDir), not the process's current folder |
appdir |
Init: relative folder and broken home.jsonc | project-init |
InitProject and InitHome refuse a home whose home.jsonc exists but cannot be parsed; they never overwrite it |
appdir |
Init: relative folder and broken home.jsonc | project-init |
With WithoutKind(KindHome), init creates only the home folder and writes no home.jsonc; a home: pointer target is then recognised by its name .<app> |
appdir |
Kinds: drop the home file | custom-layout |
App() returns the app name |
appdir |
First use: resolve with New | quickstart, demo |
New validates the whole option set: an empty env prefix, an unknown mode or lookup, a layout version or socket length below 1, a nil seam, an empty profile list, a release or dev profile not in the list, a run-file or legacy folder name that is not one plain path segment are each ErrInvalidOption |
appdir |
Errors: ErrInvalidOption, Options reference | doctor |
| Feature | Package | Guide | Example |
|---|---|---|---|
Global home is ~/.<app> (rule global); XDG variables are not read |
appdir |
Global and project homes: the global home | quickstart |
Global(), Project() and HasProject() give both homes at once, with Base, Data, Rule, Fallback, Note, Info |
appdir |
Global and project homes: inspect both | quickstart |
Walk-up finds the nearest .<app>/ from the working folder (rule project) |
appdir |
Lookup: the walk | lookup |
Walk-up stops at a repo root: an entry named .git, file, folder or symlink (a dangling link counts) |
appdir |
Lookup: the walk | lookup |
Walk-up checks $HOME itself, then stops; it also stops at the filesystem root |
appdir |
Lookup: the walk | lookup |
| Walk-up stops at a change of disk (device id, Windows volume serial) | appdir |
Lookup: the walk | — (needs a second mount) |
<APP>_CEILING_DIRS stops the walk (a walk that starts inside a ceiling stops there); relative entries are ignored with warning ceiling-relative (WarnCeilingRelative); entries that do not expand to an absolute path with ceiling-dropped (WarnCeilingDropped) |
appdir |
Lookup: ceilings | lookup |
The global home is never taken as a project home (compared with os.SameFile) |
appdir |
Lookup: the walk | lookup |
| The walk follows the real path of the working folder; folders compare by identity, not by string | appdir |
Lookup: the walk | lookup |
| Nearest wins in a monorepo; a nested repo is a wall | appdir |
Lookup: the walk | lookup |
WithLookup(HereOnly) looks only in the working folder |
appdir |
Lookup: HereOnly | lookup |
HereOnly still translates a linked worktree to its main checkout first, by design (SPEC 4.4 step 4) |
appdir |
Worktrees: pitfalls | worktree |
A linked git worktree uses the main checkout's .<app>/ (rule worktree), read from gitdir: and commondir, git never run |
appdir |
Worktrees: translate the working folder | worktree |
Main checkout without .<app>/: the worktree's own lookup runs, with warning worktree-main-missing when it finds a home (none when neither has one) |
appdir |
Worktrees: main checkout with no home | worktree |
| A submodule is its own project; a worktree of a bare repo uses itself | appdir |
Worktrees: cases that are not shared | worktree |
No project home: project kinds fail with ErrNoProject ("no ./ here; run ' init' or pass --home") |
appdir |
Lookup: no project home | lookup, project-init |
WithHome(path) (--home) is one home for every scope (rule flag) |
appdir |
Overrides: --home | overrides |
<APP>_HOME is one home for every scope (rule env-home) |
appdir |
Overrides: APP_HOME | overrides |
<APP>_<KIND>_DIR moves one non-anchored kind (rule env-kind); a file kind keeps its file name |
appdir |
Overrides: APP_KIND_DIR | overrides |
KindEnv(kind), EnvName(suffix) and EnvPrefix() give the variable names a tool should print |
appdir |
Overrides: print the variable names | overrides |
WithEnvPrefix(p) changes the env prefix (default: app upper-cased, - and . to _) |
appdir |
Overrides: print the variable names | overrides |
WithDirName(name) changes the home folder name (default .<app>); it must be one plain folder name, else ErrInvalidOption |
appdir |
Global and project homes: rename the home folder | overrides |
User paths expand ~, ~/… and ${VAR}; $VAR stays literal; ~user is refused; relative paths resolve against the working folder |
appdir |
Overrides: how user paths expand | overrides |
An unset or empty ${VAR} is ErrEnvVar naming the variable, never a path at / |
appdir |
Overrides: how user paths expand | overrides |
A broken --home or <APP>_HOME (an unset ${VAR}) fails every kind with its error, the cache included: no temp fallback and no code defaults |
appdir |
Overrides: report a broken override, Fallbacks: pitfalls | overrides |
Under --home or <APP>_HOME, a both kind is listed once by Paths(), labelled global |
appdir |
paths --json: print it | doctor |
| A variable that is set but empty counts as unset | appdir |
Overrides: how user paths expand | overrides |
No $HOME: global config kinds use code defaults (rule defaults), global data kinds fail with ErrNoHome |
appdir |
Fallbacks: no user home | fallbacks |
Disposable kinds with no $HOME use <tmp>/<Name(app)>-<uid>/ (rule temp, fallback) |
appdir |
Fallbacks: no user home | fallbacks |
Ensure on a disposable kind falls back to the temp folder when creating fails read-only or with a permission error |
appdir |
Fallbacks: read-only home | fallbacks |
WithTempFallback(false) turns both temp fallbacks off |
appdir |
Fallbacks: turn the temp fallback off | fallbacks |
The temp folder is created 0700 and refused when it is a symlink or owned by someone else (ErrUnsafeTemp) |
appdir |
Fallbacks: no user home | fallbacks |
Running as root in another user's home is refused (ErrRootOwned) unless WithAllowRoot(true) |
appdir |
Fallbacks: the root guard | — (needs root) |
A read-only home fails with the OS error, the path and a hint to set <APP>_HOME or <APP>_<KIND>_DIR |
appdir |
Fallbacks: read-only home | fallbacks |
| Feature | Package | Guide | Example |
|---|---|---|---|
home: pointer key moves the project home to another folder (rule pointer) |
appdir |
Pointer keys: relative home: | pointers |
db: pointer key moves only the database (rule pointer); backups/ stays |
appdir |
Pointer keys: db: | pointers, prod-db-guard |
Pointer keys are read from the marker's config.jsonc then config.local.jsonc; local wins per key |
appdir |
Pointer keys: before you start | pointers |
Absolute pointer refused in the committed file: only relative or ~/ (ErrPointerAbsolute) |
appdir |
Pointer keys: absolute paths in config.local.jsonc | pointers |
| Relative pointers resolve against the folder holding the config file | appdir |
Pointer keys: relative home: | pointers |
Missing home: target or missing db: folder fails with ErrPointerMissing |
appdir |
Pointer keys: relative home: | pointers |
home: target must hold this app's home.jsonc (ErrPointerNotHome); with WithoutKind(KindHome) it must be a folder named .<app> |
appdir |
Pointer keys: create the target | pointers |
Pointers go one hop only; the target's own keys are ignored with warning pointer-chain-ignored |
appdir |
Pointer keys: one hop | pointers |
A pointer error fails every kind that can live in the project: project-only kinds, project-else-global kinds (logs) and the project side of both kinds; nothing falls back to the marker or the global home, and only global kinds such as the cache keep working |
appdir |
Pointer keys: ConfigFiles under a broken pointer, pitfalls | pointers |
A pointer value that is not a string fails with ErrInvalidOption |
appdir |
Pointer keys: a value must be a string | pointers |
A local "home": "" does not clear a home: pointer in the committed file |
appdir |
Pointer keys: an empty local home: | pointers |
Dev profile: home: data goes to <target>/profiles/<profile>/, db: is ignored with warning pointer-ignored-for-profile |
appdir |
Pointer keys: the dev profile | pointers |
| Feature | Package | Guide | Example |
|---|---|---|---|
Standard kinds: home, config, config-local, gitignore, shared, db, backups, cache, run, logs (constants KindHome … KindLogs) |
appdir |
Kinds: read the layout in effect, before you start | custom-layout |
WithMode(ModeGlobal) makes data kinds global; the default ModeProject fails safe; Mode() reports it |
appdir |
Kinds: pick the mode, choosing: mode and scopes | custom-layout, fallbacks, daemon-paths |
Scopes global, project, project-else-global, both (ScopeGlobal, ScopeProject, ScopeProjectElseGlobal, ScopeBoth); logs is project-else-global in project mode |
appdir |
Kinds: pick the mode | custom-layout |
WithKind(name, …) adds a kind: starts as a folder, ignored by git, in the data scope, with its own <APP>_<KIND>_DIR |
appdir |
Kinds: declare the layout | custom-layout |
WithKind on an existing kind changes it in place (rename = new path, keeps git rule and scope) |
appdir |
Kinds: declare the layout | custom-layout |
WithoutKind(name) drops a kind from paths, the gitignore block and Ensure |
appdir |
Kinds: declare the layout | custom-layout |
Kind options Folder, File, Commit, Scoped, Disposable, Anchored |
appdir |
Kinds: declare the layout | custom-layout |
Kind option Ignore() turns a committed kind back to ignored |
appdir |
Kinds: flip a git rule | custom-layout |
Kind names and paths are validated (relative, slash-separated, no ..), else ErrInvalidOption |
appdir |
Kinds: invalid names and paths | custom-layout |
Kinds() returns the layout in effect, in stable order, as KindSpec (Name, Path, Type TypeFile/TypeFolder, Git GitCommit/GitIgnore, Scope, Disposable, Anchored) |
appdir |
Kinds: read the layout in effect | custom-layout, doctor |
GitignoreBlock() builds the marker block: *, then re-includes of committed kinds, parents first |
appdir |
Gitignore: see the block | custom-layout, doctor |
WithGitCommit adds committed patterns; WithGitIgnore wins over every commit rule, even a pattern equal to a generated re-include line |
appdir |
Gitignore: see the block | custom-layout |
WriteGitignore() replaces only the text between # <app>:begin / # <app>:end; broken markers are ErrGitignoreMarkers |
appdir |
Gitignore: write it, broken markers | custom-layout |
The .gitignore block is written only inside a git work tree (InitProject does it too) |
appdir |
Gitignore: write it, before you start | project-init |
| Folders are created 0700 and files 0600; existing permissions are left alone | appdir |
Files and permissions: private folders | custom-layout |
WithPerm(dir, file) changes the modes Ensure creates with |
appdir |
Files and permissions: WithPerm and the cache tag | custom-layout |
| Windows: a protected ACL for the current user and SYSTEM only | appdir |
Files and permissions: platform extras | — (Windows only) |
Disposable folders get CACHEDIR.TAG |
appdir |
Files and permissions: private folders | custom-layout |
WithCacheTag(false) turns the cache tag and the platform no-index markers off |
appdir |
Files and permissions: WithPerm and the cache tag | custom-layout |
macOS .metadata_never_index and Time Machine exclusion; Windows not-content-indexed attribute |
appdir |
Files and permissions: platform extras | — (macOS and Windows only) |
A home may be a symlink; Ensure of a file kind refuses a link whose real path is outside its home, or a broken link (ErrSymlinkEscape) |
appdir |
Files and permissions: the symlink rule | custom-layout |
VerifyFile(path) applies the symlink rule to a file the tool did not get from Ensure; inside is decided by whole path segments (a folder named ..x is inside) |
appdir |
Files and permissions: VerifyFile | custom-layout |
A home whose home.jsonc layout is newer than WithLayoutVersion refuses writes (ErrLayoutTooNew) |
appdir |
Files and permissions: the layout version guard | custom-layout, doctor |
A kind that is not in the layout (never declared, or dropped by WithoutKind) is ErrUnknownKind from Path, PathIn and Ensure |
appdir |
Errors: ErrUnknownKind, Kinds: ask for a kind that is gone | doctor, custom-layout |
| Feature | Package | Guide | Example |
|---|---|---|---|
ConfigFiles() lists config files in read order: global, project marker, home: target; later wins per key |
appdir |
Config files: list and merge | config-files, doctor |
Each ConfigFile says its home, whether it is local, and whether it is committed (inside a git work tree) |
appdir |
Config files: list and merge | config-files |
Dev profile reads the shared project config, then its own profiles/<profile>/config.local.jsonc last (ConfigFile.Profile) |
appdir |
Config files: the dev profile's own file | config-files |
With a home: pointer the target's two files are read after the marker's |
appdir |
Config files: with a home: pointer | config-files |
Missing files are still listed; --home lists one home's two files; no $HOME drops the global files |
appdir |
Config files: --home and no $HOME | config-files |
With a broken pointer, ConfigFiles() still lists the marker's own two files so doctor can name the bad key |
appdir |
Pointer keys: ConfigFiles under a broken pointer | pointers |
A config kind dropped with WithoutKind is left out of ConfigFiles() |
appdir |
Config files: drop a config kind | config-files |
WithConfigReader replaces the JSONC reader used for home.jsonc and pointer keys |
appdir |
Config files: replace the reader | config-files |
Built-in JSONC reader: // and /* */ comments, trailing commas, strings handled; a top-level null and a backslash before a raw newline are errors |
appdir/internal/jsonclite |
Config files: replace the reader | pointers, config-files |
| Feature | Package | Guide | Example |
|---|---|---|---|
Profile order: WithProfile (--profile), then <APP>_PROFILE, then the build; Profile() reports it |
appdir |
Profiles: let appdir pick, choosing: profiles | profiles |
<APP>_PROFILE limits: a dev build ignores prod unless <APP>_ALLOW_PROD=1, a release build ignores others (warning profile-env-ignored) |
appdir |
Profiles: let appdir pick | profiles |
An unknown profile from flag or env is ErrUnknownProfile, never a fallback |
appdir |
Profiles: let appdir pick | profiles, daemon-paths |
Custom profiles: WithProfiles, WithReleaseProfile, WithDevProfile (defaults ProfileProd, ProfileDev) |
appdir |
Profiles: add your own | profiles |
WithRelease(bool) states release or dev from the tool's -ldflags -X variable |
appdir |
Release detection: flag or build info | profiles |
Without the flag, a release is a clean tagged build with no vcs.revision (only go install module@vX) |
appdir |
Release detection: flag or build info | profiles, testing-setup |
IsRelease() and ReleaseReason() say what was decided and why |
appdir |
Release detection: report the decision | profiles, doctor |
A non-release profile uses ~/.<app>-<profile> and .<app>/profiles/<profile>/ for data; anchored files stay shared |
appdir |
Profiles: where each profile keeps its files | profiles |
Name(base) and NameWith(base, sep) add the profile suffix to labels |
appdir |
Names: Name and NameWith | profiles |
Banner() gives the one stderr line for a non-release profile |
appdir |
Names: print the banner | profiles |
CheckDB(path) prod-db guard: a dev build refuses the prod database (ErrProdDB) |
appdir |
Prod-db guard: check before you open | prod-db-guard |
CheckDB returns AccessReadWrite, or with <APP>_ALLOW_PROD=1 on the prod db AccessReadOnly (DBAccess.String(): read-write, read-only) |
appdir |
Prod-db guard: prod and dev databases | prod-db-guard |
CheckDB follows a release-profile db: pointer in the prod view |
appdir |
Prod-db guard: follow a db: pointer | prod-db-guard |
CheckDB resolves a relative path against WithWorkDir, runs VerifyFile, ignores every <APP>_* variable in the prod view, and catches the prod db before the prod home exists |
appdir |
Prod-db guard: relative path, no folders yet | prod-db-guard |
Env-leak filter: in a non-release profile, <APP>_HOME or <APP>_<KIND>_DIR inside the prod home is ignored (warning env-points-to-prod) |
appdir |
Child processes: the env-leak filter | profiles, prod-db-guard |
ChildEnv(environ) sets <APP>_PROFILE for child processes |
appdir |
Child processes: pass the profile | profiles |
CleanEnv(environ, prefix) drops every <PREFIX>_* variable |
appdir |
Child processes: pass the profile | profiles |
ForProfile(p) resolves another profile's paths without opening its files |
appdir |
Child processes: pass the profile | profiles |
Warnings() returns what the tool should print once |
appdir |
paths --json: doctor, warning codes | doctor, lookup, pointers |
| Feature | Package | Guide | Example |
|---|---|---|---|
RunPath(file) gives run/lock, run/daemon.lock, run/<app>.pid, run/discovery.json, run/<app>.sock, run/socket (RunLock … RunSocketFile); WithRunFile renames one to one plain file name |
appdir |
Run files: get the run files | daemon-paths |
Socket() returns run/<app>.sock when the path is short enough |
appdir |
Run files: socket and its folder | daemon-paths |
Socket fallback over WithSocketMaxLen (100): $XDG_RUNTIME_DIR/<name>/ on Linux, else /tmp/<name>-<uid>/, <hash>.sock, path written to run/socket |
appdir |
Run files: the fallback for long paths | daemon-paths |
Windows: always a named pipe \\.\pipe\<name>-<user>-<hash> |
appdir |
Run files: the fallback for long paths | — (Windows only) |
EnsureSocketDir() creates run/ on every OS, plus the fallback folder 0700 with owner and symlink checks when the socket falls back |
appdir |
Run files: socket and its folder | daemon-paths |
DaemonProfile(): WithDaemonProfile (--daemon-profile), then <APP>_DAEMON_PROFILE, then the own profile |
appdir |
Run files: the daemon of another profile | daemon-paths |
DaemonDiscovery() gives the daemon profile's discovery file |
appdir |
Run files: the daemon of another profile | daemon-paths |
MoveLegacy(ctx) moves an old global home named by WithLegacyHome(LegacyHome{Dir, DaemonLocks}) on first run; same disk is one rename, then MOVED.txt (status moved, MoveDone) |
appdir |
Legacy move: move on the first run | legacy-move |
MoveLegacy outcomes: none, already, both-exist, skipped (MoveNone, MoveAlready, MoveBothExist, MoveSkipped; non-release profile, or home set by --home/<APP>_HOME) |
appdir |
Legacy move: cases that do not move | legacy-move |
MoveLegacy cross-disk copy: verify file count and bytes plus WithLegacyVerify, keep the old folder as .moved-<date> |
appdir |
Legacy move: moving across disks | — (needs two disks) |
MoveLegacy takes a lock and probes old daemon locks without creating files (ErrBusy) |
appdir/internal/flock |
Legacy move: wait for the old daemon | legacy-move |
MoveLegacy crash safety: a partial copy is redone, a finished copy is completed, a move stopped after the old folder was renamed is finished on the next run |
appdir |
Legacy move: moving across disks | — (needs two disks) |
| Feature | Package | Guide | Example |
|---|---|---|---|
ForTest(t, app) points HOME, <APP>_HOME, XDG, TMPDIR and the agent config folder variables into a temp root and unsets every other <APP>_* variable and the leaking GIT_* variables |
appdir |
Testing: isolate the process with ForTest | testing-setup |
In a test binary, New panics on any path outside the test root, the socket fallback folder included; WithTestGuard(false) turns it off |
appdir |
Testing: the guard | testing-setup |
Seams WithEnv, WithHomeDir, WithWorkDir, WithBuildInfo replace every outside input |
appdir |
Testing: seams | testing-setup |
| Feature | Package | Guide | Example |
|---|---|---|---|
Paths() lists every kind (both homes for both kinds) for paths --json and doctor |
appdir |
paths --json: print it, First use: Paths | doctor, quickstart |
Paths() never fails: a kind whose home is unusable carries the message in Entry.Error and the failing rule in Rule |
appdir |
paths --json: print it | doctor |
Every path records its Rule: flag, env-home, env-kind, project, worktree, pointer, global, temp, defaults (RuleFlag … RuleDefaults) |
appdir |
paths --json: print it, rules | quickstart, overrides |
JSON tags on Home, Entry, ConfigFile, Socket, Warning, MoveResult |
appdir |
paths --json: result types | doctor |
Warning codes: profile-env-ignored, env-points-to-prod, pointer-chain-ignored, pointer-ignored-for-profile, ceiling-relative, ceiling-dropped, worktree-main-missing (WarnProfileEnvIgnored … WarnWorktreeMainMissing) |
appdir |
paths --json: warning codes | doctor |
Sentinel errors checked with errors.Is, each wrapped in a full sentence; exit codes stay the tool's job |
appdir |
Errors: suggested exit codes | doctor |
| Every default is an option (the full option table) | appdir |
Options reference | — (reference table) |
Dirs is immutable and safe for concurrent use; no package-level mutable state |
appdir |
Options: Dirs is immutable | — (a property, not a call) |
| Standard library only; macOS, Linux and Windows | appdir |
Platforms: platform table | — (a property, not a call) |