Overview
Projects
Notes must belong to a project, and most commands operate on the current project. It is not currently possible for notes to exist outside of projects.
Roots
wwid discovers projects by walking upward from the starting path and looking
for one of a configured list of root globs (.git
and .hg by default). Consider adding common roots like .venv or Cargo.toml
to this list if you want wwid to work without a VCS repository.
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.
Paths & storage
Projects are only aware of paths relative to their root. 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
Targets
A note is a plain text file that is attached to some object inside the
project. For example, a note attached to . is the root note. You could
attach a note to src/main.rs (a file), src/lib/ (a directory), etc. As long
as it’s a real path, it’s 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.
Extensions
You may want to assign some file extension to a note; such as md or
adoc. wwid offers two ways to do this. Setting the editor extension
means the temporary file opened by your editor will have that extension, but the
extension won’t persist. Setting a note extension means the extension will
persist, but only for that note, and is overridden by an editor extension.
Metadata
Notes can store a limited set of metadata. However, currently these are meant to
be used internally by wwid, not user-facing. Thus, we recommend against
modifying a note’s headers directly. f you use wwid’s commands to interact
with notes, you will only ever see the body. Despite that, we describe the
note format for transparency:
- Any number of headers, where the header key is followed by a colon, then its value, and each header occupies one line.
- A single blank line to denote the end of headers.
- The body.
For example:
HEADER_A: val1
HEADER_B: val2
This is the body!
A note is considered to be empty if the body contains only whitespace.