The diagram shows how New reads your flags, the <APP>_* variables, the working folder and the build info, picks a profile, resolves the global home, the project home and its pointers, and gives every kind one path with the rule that picked it; the methods on the immutable *Dirs then read those paths, and only Ensure, InitProject, InitHome, WriteGitignore, EnsureSocketDir and MoveLegacy write.
appdir uses the Go standard library only and runs on macOS, Linux and Windows. A *Dirs is immutable and safe for concurrent use: resolve once at start-up and share it. The design contract is SPEC.md; the guides below show how to use it, each with complete snippets taken from a tested example, the real output, and the pitfalls.
Read in this order to go from a first call to a tool that is ready for production. Each step names what you learn, the guide, and the example you can run with go run ./examples/<name>.
| Step | What you learn | Guide | Example |
|---|---|---|---|
| 1 | Resolve every path with New, read with Path, PathIn and Paths, create on first use with Ensure |
First use | quickstart |
| 2 | Create a project home with InitProject, and homes anywhere with InitHome; what a relative folder and a broken home.jsonc do |
Init, relative folder and broken home.jsonc | project-init |
| 3 | The global home and the project home, and how the project home is found by walking up | Global and project homes, Lookup | lookup |
| 4 | Linked git worktrees share the main checkout's home; submodules do not | Worktrees | worktree |
| 5 | Let users move homes with --home, <APP>_HOME and <APP>_<KIND>_DIR, report a broken override; what happens with no home folder |
Overrides, broken override, Fallbacks | overrides, fallbacks |
| 6 | Let a team move the project home or the database with home: and db: pointer keys |
Pointer keys | pointers |
| 7 | Shape the layout: kinds, the mode, scopes, Ignore(), unknown kinds, dropping the home file |
Kinds, drop the home file | custom-layout |
| 8 | What goes to git, how folders and files are created, WithPerm, and checking a user-given file with VerifyFile |
The .gitignore block, Files and permissions, VerifyFile | custom-layout |
| 9 | Which config files to read, in which order | Config files | config-files |
| 10 | Keep dev builds away from prod: profiles, release detection, names and the banner | Profiles, Release detection, Names and banner | profiles |
| 11 | Refuse the prod database in a dev build (relative paths and a prod home that does not exist yet included), and pass the profile to child processes | Prod-db guard, Child processes | prod-db-guard, profiles |
| 12 | Daemon run files and sockets, and moving an old home on first run | Run files and sockets, Legacy move | daemon-paths, legacy-move |
| 13 | Keep tests out of your real homes with seams and ForTest |
Testing setup | testing-setup |
| 14 | Ship paths --json and doctor, and map errors (bad options, unknown kinds) to exit codes |
paths --json and doctor, Errors, step 4: exit codes | doctor |
| I want to... | Guide | Example |
|---|---|---|
| decide which options my kind of tool needs | Choosing by app type | quickstart |
| keep data per user instead of per repo | Choosing the mode | custom-layout |
| add my own folder or file to the home | Kinds | custom-layout |
write an init command |
Init | project-init |
| keep project data outside the repo | Pointer keys, Choosing how a home is moved | pointers |
| put the cache or the database on another disk | Overrides: APP_KIND_DIR | overrides |
| make my release binary use the real homes | Release detection, Choosing profiles | profiles |
| stop a dev build from opening prod data | Prod-db guard | prod-db-guard |
| run a daemon and let clients find it | Run files and sockets | daemon-paths |
| rename my tool without losing users' data | Legacy move | legacy-move |
| test my tool without touching my home | Testing setup | testing-setup |
| tell a user where everything is and why | paths --json and doctor | doctor |
tell a user their --home or <APP>_HOME is broken |
Overrides: report a broken override | overrides |
| open a file a user named without following a symlink out of the home | Files and permissions: VerifyFile | custom-layout |
| show which config files apply when a pointer is broken | Pointer keys: ConfigFiles under a broken pointer | pointers |
| turn a bad option set into a usage error | Errors: ErrInvalidOption | doctor |
| run in a container with no home folder | Fallbacks | fallbacks |
- First use: resolve, read, ensure:
New,Path,PathIn,Paths,Ensure, the app name rule. - Create a home with init:
InitProject,InitHome,home.jsonc, refusing the global home, a relative folder, a brokenhome.jsonc.
- Global and project homes: the two homes,
Global,Project,HasProject, which home a kind uses,WithDirName. - How the project home is found: the walk-up and its stop rules, ceiling dirs,
HereOnly,ErrNoProject. - Worktrees and submodules: linked worktrees use the main checkout; submodules and bare repos do not.
- Overrides:
--home,<APP>_HOME,<APP>_<KIND>_DIR, how~and${VAR}expand, the variable names, a broken override. - Fallbacks: no home folder, the temp fallback, a read-only home, the root guard.
- Pointer keys:
home:anddb:, committed or local, one hop, the dev profile,ConfigFilesunder a broken pointer, an empty localhome:.
- Kinds: the standard layout,
WithKind,WithoutKind, kind options,Ignore(), mode and scopes,ErrUnknownKind, dropping the home file. - The .gitignore block:
GitignoreBlock,WithGitCommit,WithGitIgnore,WriteGitignore. - Files and permissions: 0700 and 0600, Windows ACLs,
CACHEDIR.TAG, the symlink rule, the layout version guard,WithPerm,WithCacheTag(false),VerifyFile. - Config files:
ConfigFilesread order, the dev profile's own file, the JSONC reader seam, a dropped config kind.
- Profiles: detection order,
<APP>_PROFILElimits, custom profiles, profile folders. - Release detection:
WithRelease, the go-install rule,ReleaseReason. - Names and banner:
Name,NameWith,Banner. - Prod-db guard:
CheckDB,<APP>_ALLOW_PROD, adb:pointer, relative paths, a prod home that does not exist yet. - Child processes and env leaks: the env-leak filter,
ChildEnv,CleanEnv,ForProfile.
- Run files and sockets:
RunPath,Socket,EnsureSocketDir, the socket fallback,DaemonProfile,DaemonDiscovery. - Legacy move:
MoveLegacy, its outcomes, the old daemon lock, moving across disks.
- Testing setup: seams,
ForTest, the test-binary guard. - Real-OS test workflow: running the manual workflow,
APPDIR_TEST_SECOND_DISK. - Promise table: every promise in the SPEC and these docs, with the test that proves it.
- Choosing: index of the decision guides.
- Mode and scopes: project or global mode, the scope of each kind, and dropping a kind or keeping it out of git.
- Finding the home: walk-up or here-only, ceiling dirs, and the five ways to move a home.
- Profiles: release flag or the go-install rule, custom profiles,
ForProfile,DaemonProfile,CheckDB. - By app type: the option set for a project CLI, a global tool, a daemon, a desktop app and a test suite.
- Feature index: every feature with its guide and example.
- Options: every
OptionandKindOptionwith its default. - Errors and exit codes: every sentinel error, when it happens, its message, a suggested exit code.
- paths --json and doctor: the result types, rules and warning codes, and how to build both reports.
- Platforms: what differs on macOS, Linux and Windows, file by file.
- SPEC: the design contract.
Each example except demo runs inside a temp folder and never touches your real home; demo resolves for the folder you run it in. Run one with go run ./examples/<name>; go test ./examples/... runs them all and checks their output.
- quickstart:
New,App,Path,PathIn,Paths,Ensure. - project-init:
InitProject,InitHome,ErrNotHome, refusing the global home, a relative folder, a brokenhome.jsonc. - lookup: the walk-up, repo-root wall, ceiling dirs, symlinked working folder, monorepo,
HereOnly,ErrNoProject. - worktree: linked worktrees, a main checkout with no home, submodules, a bare repo's worktree.
- overrides:
--home,<APP>_HOME,<APP>_<KIND>_DIR, the variable names, path expansion, a broken override. - fallbacks: no home folder,
WithTempFallback(false), a read-only home. - pointers:
home:anddb:pointer keys and their errors, the dev profile,ConfigFilesunder a broken pointer, an empty localhome:. - custom-layout:
WithKind,WithoutKind,Ignore(),ErrUnknownKind, init without a home file, the modes, the gitignore block, permissions,WithPerm,WithCacheTag(false), the symlink rule,VerifyFile, the layout guard. - config-files:
ConfigFilesin each case, merging,WithConfigReader, a dropped config kind. - profiles: profile detection, release reasons, a custom profile, names and banner,
ChildEnv,CleanEnv,ForProfile. - prod-db-guard:
CheckDBfor prod and dev databases,<APP>_ALLOW_PROD, adb:pointer, a relative path, a prod home that does not exist yet. - daemon-paths:
RunPath,Socket,EnsureSocketDir, the socket fallback,DaemonDiscovery. - legacy-move:
MoveLegacyand every outcome,ErrBusy. - testing-setup: seams,
ForTest, the guard. - doctor:
paths --json, the appdir part ofdoctor, a--homerun, invalid option sets,ErrUnknownKind, errors mapped to exit codes. - demo: a small tool that prints everything appdir resolves where you run it.