Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install wwid

It will make the wwid command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall wwid uninstalls.

Back to the crate overview.

Readme

wwid

Portable, ad-hoc, project-relative notes.

wwid (what was I doing?) is intentionally simple: it maps notes to paths. It makes no further assumptions, and does not attempt to manage your workflow for you.

The simplicity is what makes it powerful. Notes stay contextual, portable, flexible, and as ephemeral or durable as your workflow demands. wwid is just a utility that enables your own productivity.

More precisely, wwid associates externally stored text files with relative paths inside projects. As such, you can tether notes directly to their context without polluting the source tree, while remaining viable to sync with tools like SyncThing.

Design

Goals

Notes are always attached to paths so context is implicit.
Do not impose a note format, editor, or workflow; make it easy for users to apply their own preferences.
Notes are stored in a "system-agnostic" way, making them suitable for syncing between machines where the same project may be located at different paths.
Creating, opening, and deleting notes should be cheap enough to do ad-hoc.

Non-goals

wwid does not aim to be:

A task manager or TODO system.
A personal knowledge management (PKM) tool or "second brain".
A note format or schema.
A workflow framework or productivity methodology.
A replacement for your current productivity tooling.

wwid does not structure, prioritize, or interpret notes. Its only function is to map notes to paths and provide utilities for managing them; everything else is left to the user.

Who is this for?

wwid is likely useful if you:

Frequently stop work mid-task and struggle with forgetting context.
Prefer plain-text, bring-your-own-editor note taking.
Work across many projects & files simultaneously.

This tool probably works best for people who think in terms of files & directories, and who want to leave short, contextual notes without committing to a larger system. It is less suitable if you want long-lived knowledge storage or rich metadata.

Installation

Cargo

# from source
cargo install --git https://codeberg.org/ficd/wwid
# crates.io
cargo install wwid

Prebuilt binaries

Prebuilt binaries are available on Codeberg releases.

Usage

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.

Every note is attached to (or owned by) some path relative to the project root. For example, a note could be attached to . (the project root), some file (like src/main.rs), a directory, and so on. You point wwid at a target, it resolves the correct note by its root-relative path and loads it in your preferred editor. Like project discovery, notes are created automatically as needed.

Commands

# open the note for CWD
wwid note .
# relative paths are resolved
wwid note ../Cargo.toml
# absolute paths work as long as
# they resolve within a project
wwid note ~/dev/foo/src/main.rs

A common workflow may be to keep a general, project-wide task list attached to the root, while more granular reminders and implementation details may be linked to files. As a convenience, wwid without any args will always open the root note as long as you're inside a project:

# open the root note
wwid

wwid makes no further assumptions about your workflow. We just provide the means to map notes to project files; the rest is up to the user. We do provide some other commands, but they are considered supplementary to the core feature. For example, you may want to query some information about the project and its notes:

# see the notes in this project
wwid list
# see various stats on this project
wwid status

There are ways to delete notes, too. Besides specifying a target by path, you can also automatically prune "orphaned" notes (those whose owners are no longer present in) the project. Users will be prompted for confirmation of any potentially destructive action (like note deletion). The --force option can usually be used to bypass this check.

# delete a specific note
wwid rm src/main.rs
# delete all orphans, skip confirmation
wwid prune --force

We also provide some commands that operate on all projects:

# equivalent to 'wwid status', but on ALL projects
wwid projects list
# delete a project by its ID
wwid projects rm <ID>

The commands discussed here may not be exhaustive. You can always consult the built-in help with wwid help to see what's available in your installed version.

Workflow Ideas

Listed here are some loose workflow ideas to get you started. They all rely on the same simple idea: attach a note to a path, and let your editor and habits do the rest.

Project journal:
- Attach a note the root and use it as a running journal: what you were doing when you stopped, what to do next, etc.
File-level "why" notes:
- Add notes to implementation heavy or non-obvious files to capture invariants and assumptions, tradeoffs that aren't obvious from the code, "don't forget to refactor XYZ", etc.
Low-friction scratchpads:
- TODOs that aren't ready for issues
- dead ends you might want to revisit
Directory scoped task lists:
- refactors scoped to that subtree
- cleanup reminders
- (avoids one giant project TODO list and keeps tasks in their domain)
Debugging breadcrumbs
- attach notes to files where symptoms manifest, what hypotheses you've tried, etc.

And finally, don't forget to use wwid prune periodically! wwid works best with temporary notes that are intentionally disposable. Think of it like a stack, and don't be afraid to pop notes when you're done with them!

Configuration

wwid has two configuration files: config.toml and roots.toml. They're expected to be in the standard config directory, which is most likely ~/.config/wwid. See BaseDirs for more details.

A sample config.toml is provided here. Omit keys to use the defaults.

# prioritized if present; omit to use $EDITOR
editor = "nano"
# sets the extension of the temp file when editing
# useful if your editor can provide syntax highlighting based on filetype
# (default is None)
extension = "md"
# list of globs to identify project roots
root-globs = [".git", ".hg"]

roots.toml holds the mapping of project IDs to absolute root paths. This file will be automatically created and populated as you initialize new projects. For reference, here's my roots.toml:

wwid-1 = "/home/fic/dev/wwid"
kaklang-1 = "/home/fic/dev/ocaml/kaklang"

config.toml should be safe to sync across machines, but it's recommended to exclude roots.toml and maintain a mapping per-system.

Development

wwid is written in Rust and developed on Codeberg. CI is through a self-hosted instance of woodpecker. We use prek for pre-commit hooks, which we recommend setting up with prek install.

Contributions are very welcome. This is my first Rust project, so there is a lot of room for improvement. The codebase is currently a bit messy and you'll see a mishmash of different "styles" as I've been experimenting with Rust's features.

As such, I'm happy to accept contributions from experienced and beginner Rust programmers alike. However, PRs suspected of being vibe-coded will be closed immediately.

License & Maintenance

wwid is maintained by Daniel Fichtinger, and licensed under 0BSD. Its source code is published on Codeberg.