Skip to content

Support readable path filters for notes diff #146

Description

@brownie-ricon

Problem

While editing a single readable note in a notes-managed repo, the obvious command failed:

notes diff notes/scratch-mise-workbench.md

Observed output:

Error: not a tree-ish ref: notes/scratch-mise-workbench.md
[diff] ERROR task failed

notes diff currently treats positional arguments as refs/ranges. That makes sense for BASE, BASE..HEAD, and BASE...HEAD, but a readable note path is also a natural thing to pass when reviewing one modified note.

Why this would help

The working-tree diff without arguments works, but it shows all readable note changes. During note-only edits, agents often want to inspect exactly one note before notes commit / notes stage.

Desired shape could be either:

notes diff notes/scratch-mise-workbench.md

or, if avoiding ambiguity with refs is preferable:

notes diff -- notes/scratch-mise-workbench.md
notes diff --path notes/scratch-mise-workbench.md

Acceptance sketch

  • A readable note path can be used to filter the working-tree readable diff.
  • If a positional argument is neither a valid ref/range nor an existing readable note path, the error explains both accepted forms.
  • Existing ref/range and --pr behavior remains unchanged.

Provenance

Hit by Brownie while adding a fold scratch-mise-workbench dogfood note on 2026-06-20. Or immediately said this would be nice to support.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions