Beagle SCM

Nav: editing one slot of a (verb · URI) address

Between Beagle CLI and the Bro pager, there is a unified navigation framework. Its mission is to make a versioned repo as navigable as a regular filesystem (cd, ls, cat, grep, etc). So moving around in the pager must not be any more complicated than moving around in the regular Unix shell. The general idea is that the current position is saved in the context URI (like $PWD), while movements mutate one axis at a time: path, revision, worktree, etc.

• in the CLI, the context URI is defined by the current dir (worktree, path, branch all come from pwd-based detection),
• in the pager, the current URI is displayed in the address bar,
• relative-path arguments get resolved against the context URI, e.g. //ABC-123/path/file.c + .. = //ABC-123/path/,
• resolution is the verb's job — resolve(context, base, rel) at the verb's entry; the pager is arg-blind and never pre-merges,
• authority-only arguments switch the worktree, e.g. //beagle/main.js + //ABC-123 = //ABC-123/main.js; the target worktree supplies its own revision, irrespective of the old context,
• a ?rev context means: ignore the worktree files, read repo objects; verbs are free to ignore/drop context parts that don't apply (e.g. a write verb drops ?rev),
• query-only arguments: the same,
• query arguments can be relative as well, e.g. //ABC-123? + ?./branch = //ABC-123?branch,
• fragment-only arguments: the same,
• multipart URIs are taken verbatim, e.g. git@github.com:gritzko/libdog.git is context-independent,
• pager commands are called spells; they come in several formats:
  1. context-mutating relative ./paths,
  2. context-mutating relative ?queries,
  3. context-mutating //TREES,
  4. verb-and-arguments command invocations.

Verb-args-context

All Beagle commands get implemented as JavaScript modules exporting one command(context_uri, args...) function. So, CLI and pager invocations are very much alike: they take the context from the environment, find the module, call the function, pass the arguments verbatim. On top of that, the pager has context-mutating spells, so the user may rerun the last command in a slightly different context, e.g. change the directory, revision, or a worktree. E.g. with cat file.c rendered, the spell ://ABC-123 reruns it as //ABC-123/file.c — the same file from another worktree.

Every command emits {ts,verb,uri} hunks containing token streams. Hunk tokens can be click-targets containing URIs (U) or verb args spells (O).