dodder-usage

# Dodder Usage ## dodder and der `dodder` and `der` are the same tool. `der` is a shortname alias that behaves identically. Every command and flag documented here works with either binary. `madder` is a separate low-level tool for internal repository operations and is not covered by this skill. ## Creating Content Create new zettels with `dodder new`. By default, the command creates one empty zettel and opens it in the configured editor (`$EDITOR` or `$VISUAL`). ```bash dodder new # create one empty zettel, open editor dodder new -edit=false # create one empty zettel, no editor dodder new -edit=false file.txt # import content from a file dodder new -tags project -type md # set metadata at creation time dodder new -count=5 -edit=false # create 5 empty zettels at once dodder new -shas # treat arguments as already-checked-in blob SHAs dodder new -organize # create zettel(s), then open organize UI dodder new -delete # delete source file after import ``` The `-filter` flag accepts a script path that transforms each input file into the standard zettel triple-hyphen format before import. When creating from files, pass one or more file paths as positional arguments. Each file becomes a separate zettel with its content as the blob. Combine with `-description`, `-tags`, and `-type` to set metadata on all created zettels. ## Viewing and Querying Use `dodder show` to query and display objects. The default output format is `log` (one-line summary per object). Query syntax uses positional arguments with genre, sigil, tag, and type selectors. ```bash dodder show :z # all zettels (latest versions) dodder show one/uno # specific zettel by ID dodder show -format text one/uno # detailed multi-line view dodder show -format json one/uno # JSON output for scripting dodder show tag-name:z # zettels carrying a specific tag dodder show !md:z # zettels of type md dodder show :?z # include dormant/hidden zettels dodder show :t # all types dodder show :e # all tags dodder show :z,t # zettels and types dodder show :r # all repos dodder show -before 2024-01-01 :z # zettels before a date dodder show -after 2024-01-01 :z # zettels after a date dodder show -repo remote-id :z # query a remote repository ``` The `-format` flag supports `log` (default, one-line), `text` (detailed multi-line), and `json` (machine-readable). Use `dodder cat` for raw blob output, and `dodder last` to display the most recently changed objects from the latest inventory list. ## Configuration Repository configuration is not a queryable object. It cannot be selected with `show` or any genre filter; a query naming `konfig` or `config` errors with `config is no longer an object; use show-config / edit-config`. Use the dedicated commands instead. ```bash dodder show-config # print the latest config (bare TOML) dodder show-config <digest> # print a historical config state's blob dodder show-config -history # list config history (oldest to newest) dodder edit-config # open the config TOML in the editor ``` `edit-config` opens the bare config TOML in `$EDITOR`; on save it records the new state in a repo-local config log. Configuration is repo-local and is not transferred by `push` or `pull`. A `clone` seeds the new repository's config from the source. ## Editing Open a zettel for editing in the configured editor with `dodder edit`. The `-mode` flag controls what to edit. ```bash dodder edit one/uno # edit metadata and blob (default) dodder edit -mode metadata-only one/uno # edit metadata only dodder edit -mode blob-only one/uno # edit blob only dodder edit -delete one/uno # delete after editing dodder edit -organize one/uno # open organize after editing ``` After external edits (outside the editor), use `dodder checkin` to commit changes back to the store. `checkin` has two aliases: `add` and `save`. ```bash dodder checkin one/uno # commit changes from working copy dodder checkin -ignore-blob one/uno # update metadata only, keep blob dodder checkin -each-blob "cmd" :z # run command on each blob dodder checkin -tags project :z # add tags during checkin dodder checkin -type md :z # set type during checkin dodder checkin -delete :z # delete working copy after checkin dodder checkin -organize :z # open organize after checkin ``` ## Checkout and Working Copy The checkout system syncs objects from the store to the filesystem. Use `dodder checkout` to materialize objects as files. ```bash dodder checkout :z # checkout all zettels dodder checkout one/uno # checkout a specific zettel dodder checkout -organize :z # checkout then open organize UI dodder checkout :?z # include dormant objects ``` View the current state of checked-out objects with `dodder status`. ```bash dodder status # show all checked-out objects and their state dodder status one/uno # show state for specific object ``` Remove checked-out files from the working directory with `dodder clean`. ```bash dodder clean # remove unchanged checked-out files dodder clean -force # remove all checked-out files regardless of changes dodder clean -organize # open organize UI to select files to remove dodder clean -recognized-blobs # also remove recognized but not checked-out blobs ``` View differences between the store and working copy with `dodder diff`. ```bash dodder diff # diff all checked-out objects dodder diff one/uno # diff a specific object ``` ## Organizing `dodder organize` opens a text-based bulk editing interface. It generates a structured text file listing objects, which can be edited to rename, retag, retype, or reorganize objects. Changes are committed when the editor closes. ```bash dodder organize :z # organize all zettels dodder organize -mode output-only :z # preview the organize file (stdout) dodder organize -mode commit-directly :z # apply changes from stdin, no editor dodder organize -mode interactive :z # open vim to edit (default for TTY) dodder organize -filter script.lua :z # transform via script dodder organize tag-name:z # organize zettels with a specific tag dodder organize !md:z # organize zettels of a specific type ``` The organize interface represents objects as a hierarchical text document. Move lines to change tag assignments, edit descriptions, and retype objects. Deleting a line from the organize file does not delete the object from the store. ## Remote Sync Dodder supports push/pull synchronization with remote repositories. Remotes are registered objects within the local store. ### Add a remote ```bash dodder remote-add remote:///path/to/repo remote-id ``` The first argument is the remote URI and the second is the local name. The `-tags` and `-description` flags set metadata on the remote object. ### Clone a repository ```bash dodder clone backup remote:///path/to/source # new local repo "backup" (XDG-user) dodder clone .backup remote:///path/to/source # new local repo as .dodder in CWD dodder clone -organize backup remote:///path/to/source !md:z # filter what gets cloned first ``` Clone creates a new local repository and pulls all inventory lists from the remote. Additional query arguments filter what to clone. `-organize` opens an editable outline of the matched objects before pulling — delete an entry to exclude it (not supported over the websocket transport). ### Push and pull ```bash dodder push remote-id # push local changes to remote dodder pull remote-id # pull remote changes to local dodder pull-blob-store path config # pull blobs from a blob store ``` Push and pull transfer inventory lists and their referenced objects. Both commands accept query arguments to limit what to transfer. ## Workspaces A workspace is a directory linked to a dodder repository. It provides default tags, type, and query for operations within that directory. ```bash dodder init-workspace # create workspace in current directory dodder init-workspace subdir # create workspace in a subdirectory dodder init-workspace -tags work # set default tags for the workspace dodder init-workspace -type md # set default type for the workspace dodder init-workspace -query "project:z" # set default query dodder init-workspace -organize -parent /path/to/parent workspace-id # filter what gets pulled first dodder info-workspace # show workspace configuration dodder info-workspace query # show default query dodder info-workspace defaults.tags # show default tags dodder info-workspace defaults.type # show default type ``` When a workspace exists, `checkin`, `new`, and `organize` automatically apply the workspace's default tags. `show` uses the workspace's default query when no arguments are given. `-organize` on `init-workspace` opens an editable outline of the objects that would be pulled from the parent repo before initializing (requires `-experimental-repo`, the default). ## Query Syntax Queries are positional arguments passed to commands like `show`, `checkout`, `organize`, `edit`, and `checkin`. The syntax combines object IDs, genre selectors, sigils, tag filters, and type filters. | Syntax | Meaning | |--------|---------| | `:z` | All zettels (latest) | | `:t` | All types | | `:e` | All tags | | `:r` | All repos | | `:b` | All inventory lists | | `:z,t` | Zettels and types | | `one/uno` | Specific object by ID | | `tag-name:z` | Zettels with a specific tag | | `!md:z` | Zettels of a specific type | | `:?z` | Including dormant/hidden | Sigil characters modify selection scope: | Sigil | Character | Scope | |-------|-----------|-------| | Latest | `:` | Current versions only (default) | | Hidden | `?` | Include dormant objects | | History | `+` | Include historical versions | | External | `.` | Include checked-out/external objects | Refer to `references/querying.md` for the complete query syntax reference with compound queries, time filtering, and practical examples. ## Working Copy vs Store The `.dodder/` directory (or XDG-based equivalent) is the store. It contains all blobs, inventory lists, indices, and configuration. The filesystem outside `.dodder/` is the working copy. - `checkout` syncs store to filesystem (read from store, write to working copy). - `checkin` syncs filesystem to store (read from working copy, write to store). - `status` shows the relationship between store and working copy. - `diff` shows differences between the two. - `clean` removes working copy files. The store is always the source of truth. The working copy is ephemeral and can be fully recreated from the store at any time. ## Tags and Types Tags and types are first-class objects in dodder, each with their own IDs and metadata stored in the repository. **Tags** organize and categorize objects, similar to labels. A zettel can carry any number of tags. Tags are referenced in queries by name (e.g., `project:z` matches all zettels tagged `project`). Tag prefixes carry special meaning: | Prefix | Meaning | |--------|---------| | (none) | Regular tag | | `-` | Dependent tag (implicit, derived from parent) | | `%` | Virtual tag (computed, not stored directly) | **Types** define the format of a zettel's blob content, similar to file extensions. A zettel has at most one type. Types are referenced in queries with the `!` prefix (e.g., `!md:z` matches all markdown zettels). A zettel's type is supplied by the repo's **default type** when you omit one on `new` (or `checkin`). A standard `init` repo sets a default type (commonly `!md`). **Workspace repos and clones have no default type**, so `new` and `checkin` there require an explicit `-type`; omitting it errors with `no type given and repo has no default type; pass -type`. (Older data may also be typeless — it displays as a bare `!` — and typeless objects break `push`/`import`, so always give a new zettel a type.) Set or change a workspace's default with `init-workspace -type <type>`. Both tags and types can be viewed with `dodder show :t` (types) and `dodder show :e` (tags). ## Dormant Objects Dormant objects are hidden from default queries. Mark objects as dormant to archive or suppress them without deleting. ```bash dodder dormant-add tag-name # hide objects matching this tag dodder dormant-remove tag-name # unhide objects matching this tag dodder dormant-edit # open dormant configuration in editor ``` Dormant objects reappear in queries that use the `?` sigil: ```bash dodder show :?z # all zettels including dormant dodder checkout :?z # checkout including dormant ``` The dormant index is part of the repository configuration. Use `dormant-edit` to directly edit the configuration blob that controls which tags trigger dormancy. A type can also make its objects dormant by state: an `enum` field in the type blob may list `terminal` values (a subset of its `values`), and any object whose field holds one of them is dormant, with no tag involved. The built-in `!task` is dormant at `status` `done` or `cancelled`; `!chore` and `!habit` only at `cancelled` (their `done` recurs back to `todo`). ```toml [[fields]] name = "status" kind = "enum" values = ["open", "closed", "wontfix"] terminal = ["closed", "wontfix"] ``` ## Maintenance ```bash dodder reindex # rebuild all indices from inventory lists dodder fsck # verify integrity of objects and blobs dodder fsck -skip-blobs # skip blob content verification dodder fsck -skip-probes # skip probe index verification dodder repo-fsck # verify repository-level integrity dodder find-missing sha1 sha2 # check if blob SHAs exist in the store dodder revert one/uno # revert object to previous version dodder revert -last # revert all changes from last inventory list dodder transform -script f.lua # bulk-rewrite queried objects via a Lua script dodder transform -dry_run -script f.lua # report the rewrite plan without committing dodder info store-version # show current store version dodder info compression-type # show blob compression type dodder info age-encryption # show encryption status dodder info env # show environment variables dodder info xdg # show XDG directory paths dodder deinit # remove dodder repository (requires confirmation) dodder deinit -force # remove without confirmation ``` `reindex` rebuilds the stream index and other derived data structures from the authoritative inventory lists. Run it after a suspected corruption or after manual edits to the store. `fsck` verifies that every object's metadata, digest, and blob content are consistent. It reports errors but does not modify data. `transform` runs a Lua script over the queried objects as one batch (see the commands reference for the script surface). Use `-dry_run` first; the output is validated against the store's blob-integrity checks before anything commits. ## Repository Initialization ```bash dodder init my-repo # XDG-user repo named "my-repo" dodder init .my-repo # create .dodder in current dir dodder init -yin words.txt my-repo # custom left-part word list dodder init -yang words.txt my-repo # custom right-part word list ``` The required positional is the new repo's location handle; its scope comes from the spelling. A handle that starts with `.` (e.g. `.my-repo`) creates a `.dodder/` directory in the current working directory instead of using XDG base directories. This is useful for self-contained repositories. (`-repo_id` / `DODDER_REPO_ID` address an *existing* repo and are rejected on `init` / `clone`.) ## Global Flags These flags apply to all commands: | Flag | Purpose | |------|---------| | `-dir-dodder` | Override the dodder directory path | | `-ignore-workspace` | Ignore workspace defaults | | `-ignore-hook-errors` | Continue despite hook failures | | `-hooks` | Path to hooks configuration | | `-checkout-cache-enabled` | Enable checkout caching | | `-predictable-zettel-ids` | Generate IDs in order (testing) | | `-comment` | Attach a comment to the inventory list | | `-debug` | Enable debug output | | `-dry-run` | Preview changes without applying | | `-verbose` | Increase output verbosity | ## Reference Documents - `references/commands.md` -- Complete command reference organized by workflow, with flags and one-line examples. - `references/querying.md` -- Full query syntax reference with genres, sigils, filters, compound queries, and practical examples.