Overview

Projects

Notes must belong to a project, and most commands operate on the current project. wwid discovers projects by walking upward from the starting path and looking for one of a configured list of root globs ([".git", ".hg"] by default).

Project discovery and creation is automatic, and there is no requirement for repository names to be unique. A unique project ID is derived from the root directory’s name, and users are prompted to provide a “hint” to better describe the project.

For example, a project located at ~/dev/foo may be assigned an ID of foo-1, while another project at ~/Documents/foo would be assigned ID foo-2. Users can set any string as the project hint; the point is to contextualize its purpose in case there are many projects with similar names & IDs.

Projects are only aware of paths relative to themselves. In other words, projects hold no information about their roots’ actual locations on the system. This is instead part of configuration, where users map project IDs to project root paths.

The actual data for projects, including their notes, are stored in your system’s standard data directory in a plain-text format. On Linux, this is probably ~/.local/share/wwid. Please see BaseDirs for more details.

Notes

A note is a plain text file that is attached to some path inside its project. This is usually a file or a directory. For example, a note could be attached to ., which is called the root note. It could be attached to some file src/main.rs, a directory src/lib/, etc. Any valid, existing path is allowed.

In other words, You point wwid at a target inside your project, and it resolves the associated externally-stored note. The storage is abstracted away; wwid instead provides tools to interact with the notes (like deletion, reading, editing), detailed in the commands section.

Warning

Like projects, notes will be automatically created as needed. But unlike projects, empty notes are automatically deleted.