Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Quick Start

Setup

If you haven’t already, begin by installing wwid. If you want, create the configuration file config.toml in the standard config directory (most likely ~/.config/wwid). wwid requires no initialization. It works immediately inside any project as soon as you create a note.

Creating your first note

Enter a git repository and open the root note, a special note that covers the whole project:

cd my-project
wwid

This will:

  • Create a note file (or open the existing one).

    Important

    All notes are stored in the user data directory. Your project will never be directly modified.

  • Link it to the project root.
  • Open your configured editor.
  • Save your changes to the note.

Writing notes

Besides the root note, you can attach notes to files and directories inside the project. For example, you can add a note to a Rust project’s main file:

wwid edit src/main.rs
# to set a persistent extension for this note:
wwid edit -x md src/main.rs

The edit command is used for both creating new notes and editing existing ones. It’s handled automatically, so you don’t need to worry about it. Like the previous command, it will open your preferred editor and wait for your changes.

Later, you can print the note to standard output:

wwid print src/main.rs

You can also create or overwrite notes non-interactively:

wwid write src/main.rs --content "This goes in the body!"

Omit the --content flag to use standard input. This allows wwid to be used in pipelines. For example, let’s use sed to replace occurrences of TODO with DONE:

wwid print foo/bar | sed 's/TODO/DONE/g' | wwid write foo/bar

Managing notes

Use the list command to see which notes exist in the project:

wwid list

You can also delete unwanted notes:

wwid rm src/main.rs
# or skip the confirmation prompt
wwid rm --force src/main.rs

Using the edit command to empty the note also automatically deletes it.

Important

orphan
A note whose target no longer exists in the project.

Finally, you can use the prune command to clean up notes that are orphaned or empty:

wwid prune
# or skip the confirmation prompt
wwid prune --force

Project-relative paths

All paths given to wwid are resolved relative to the project root. You can reference files using ., .., etc, but the stored note is always normalized. Thus:

cd src
wwid edit ../README.md

Even though you used ../README.md, the note is associated with the path README.md. You can verify this with the list command, whose output should include README.md.