Skip to content

Latest commit

 

History

History
133 lines (103 loc) · 13.4 KB

README.md

File metadata and controls

133 lines (103 loc) · 13.4 KB

appdir documentation

appdir architecture

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.

Learning path

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

Start from your goal

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

All pages

Start

Homes

  • 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.

Pointers

  • Pointer keys: home: and db:, committed or local, one hop, the dev profile, ConfigFiles under a broken pointer, an empty local home:.

Layout

  • 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: ConfigFiles read order, the dev profile's own file, the JSONC reader seam, a dropped config kind.

Profiles

Runtime

  • 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

Choosing

  • 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.

Reference

  • Feature index: every feature with its guide and example.
  • Options: every Option and KindOption with 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.

All examples

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 broken home.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: and db: pointer keys and their errors, the dev profile, ConfigFiles under a broken pointer, an empty local home:.
  • 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: ConfigFiles in 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: CheckDB for prod and dev databases, <APP>_ALLOW_PROD, a db: pointer, a relative path, a prod home that does not exist yet.
  • daemon-paths: RunPath, Socket, EnsureSocketDir, the socket fallback, DaemonDiscovery.
  • legacy-move: MoveLegacy and every outcome, ErrBusy.
  • testing-setup: seams, ForTest, the guard.
  • doctor: paths --json, the appdir part of doctor, a --home run, invalid option sets, ErrUnknownKind, errors mapped to exit codes.
  • demo: a small tool that prints everything appdir resolves where you run it.