The guides under docs/ show how each feature works. These pages answer the question before that: which option do I want? Each one gives a decision table, short "if this, then that" rules, the traps people fall into, and for every option the guide that explains it and the example that runs it. Every rule here was checked against the code; where the design in SPEC and the code differ, these pages describe the code.
| Page | Read it when you are deciding |
|---|---|
| Mode and scopes | whether your tool keeps its data per project or per user, which home one kind lives in, and what dropping a kind (WithoutKind) costs |
| Finding the home | how far the lookup walks, and which way a user or a team should move a home: --home, <APP>_HOME, <APP>_<KIND>_DIR, or a home: / db: pointer |
| Profiles | how a binary becomes prod or dev, whether you need your own profiles, and when to call ForProfile, DaemonProfile and CheckDB |
| By app type | the option set for a project CLI, a daemon, a desktop app, a global tool, and a test suite |
- Data that belongs to a repo: keep the default
ModeProject. Data that belongs to the user:WithMode(appdir.ModeGlobal). - Always pass your
--homeand--profileflags withWithHomeandWithProfile; an empty string means "not given". - Pass
WithReleaseonly when your release variable was set by-ldflags, so a plaingo install module@vXstill counts as a release. - Call
CheckDBbefore you open a database or migrate it, even when the prod home does not exist yet. Newfails only on bad input (ErrInvalidOption,ErrUnknownProfile); a broken--homeor pointer shows up as an error fromPath, so check one kind at start-up.- In tests, use the seams or
ForTest; never the real home.
- Learning path and the feature index.
- Options reference: every option with its default.