commit e4e1272daf7324bdd4f417d61e3c03f13f5a6dde from: mtmn date: Tue Sep 15 23:15:28 2026 UTC add manpage commit - 76ebdf31b4f697c5f276b1e8d23c153f21de0a1b commit + e4e1272daf7324bdd4f417d61e3c03f13f5a6dde blob - 6cbfc90996f0b0b60d8faf73d688c16ce443c780 blob + fa69aa2573f9b282ebfdb5c21f505f436af8198c --- build.zig +++ build.zig @@ -35,6 +35,11 @@ pub fn build(b: *std.Build) void { b.installArtifact(exe); + const scdoc = b.addSystemCommand(&.{"scdoc"}); + scdoc.setStdIn(.{ .lazy_path = b.path("magdalena.1.scd") }); + const man_page = scdoc.captureStdOut(.{}); + b.getInstallStep().dependOn(&b.addInstallFile(man_page, "share/man/man1/magdalena.1").step); + const run_cmd = b.addRunArtifact(exe); run_cmd.step.dependOn(b.getInstallStep()); if (b.args) |args| { blob - edb96e7ef81d8c9e34deb222032ff870f2ac593b blob + 95e40ed421db307b41c3bfee591673b0704dfc28 --- build.zig.zon +++ build.zig.zon @@ -17,6 +17,7 @@ "build.zig", "build.zig.zon", "src", + "magdalena.1.scd", "LICENSE", "README.md", }, blob - /dev/null blob + cfd2e953e514edfafdc1aaa971d517f9f215ce74 (mode 644) --- /dev/null +++ magdalena.1.scd @@ -0,0 +1,196 @@ +MAGDALENA(1) "magdalena" "User commands" + +# NAME + +magdalena \- navigate shell history with a fuzzy picker + +# SYNOPSIS + +*magdalena* *recent-directories* + +*magdalena* *recent-files* + +*magdalena* *favorites* + +*magdalena* *goto-directory* + +*magdalena* *goto-file* + +*magdalena* *log-directory* _path_ + +*magdalena* *log-file* _path_ [_type_] [_action_] + +*magdalena* *search* _query_ + +*magdalena* *look-file* [_--depth_ _n_] + +*magdalena* *look-directory* [_--depth_ _n_] + +*magdalena* *grep* [_query_] + +*magdalena* *git-status* + +*magdalena* *select* + +*magdalena* *-c* | *--clean* + +*magdalena* *-h* | *--help* + +# DESCRIPTION + +*magdalena* logs visited directories and opened files. It reopens them +through a full-screen fuzzy picker. Logging subcommands append to the +history. Picker subcommands open the finder. Listing subcommands print to +standard output for scripts. + +With no subcommand, *magdalena* prints usage and exits. Unknown +subcommands do the same. + +## Logging history + +*log-directory* records _path_ with the current timestamp. *log-file* +records _path_ with an optional file _type_ and _action_. The defaults are +_other_ and _open_. *magdalena* resolves relative paths against the working directory +before storing them. + +Shell integration calls these after each directory change or file open. +You can also call them by hand. + +## Picking + +*goto-directory* picks from recent directories. *goto-file* picks from +recent files. *favorites* picks from the configured favorites list. +*look-file* and *look-directory* pick below the working directory. They +stop at the configured depth. *git-status* picks from files changed in +the current repository. *grep* searches file contents with *ugrep*(1). +It picks from the matches. *select* reads newline-separated candidates +from standard input. It picks from them. + +The picker opens the selection in the configured editor or opener. +If you abort the picker, it exits 1 and opens nothing. + +Use *--choose-file* _path_ to embed the picker in editors. It writes +the selection to _path_ and starts no editor. File pickers write the +path. *grep* writes _file:line_. *magdalena* skips history logging. +The embedding editor owns the open event. + +## Searching and listing + +*recent-directories* prints _timestamp_|_path_ lines, newest last. +*recent-files* prints _timestamp_|_type_|_action_|_path_ lines. A dash +marks a missing timestamp. + +*search* matches one query against both logs. It prints directories as +_D_|_path_. It prints files as _F_|_type_|_action_|_path_. + +# OPTIONS + +*--depth* _n_, *--depth*=_n_, *-d* _n_ + +Search depth for *look-file* and *look-directory*. Put the flag before +or after the subcommand. The default is the configured *max_depth*. +Without configuration it is 3. + +*--choose-file* _path_, *--choose-file*=_path_ + +Write the pick to _path_ instead of opening it. Put it before or +after the subcommand. + +*-c*, *--clean* + +Drop entries with missing paths. Drop entries *magdalena* cannot +check. Collapse duplicates. Newest entries win. + +*-h*, *--help* + +Print usage and exit. + +# ENVIRONMENT + +*HOME* + +Required. *magdalena* finds the configuration file and history store +under it. + +*EDITOR* + +Fallback editor. *magdalena* uses it when the configuration names no +editor. + +*NO_COLOR* + +When set, the picker disables colour. + +# FILES + +_~/.config/magdalena/config.json_ + +Optional JSON configuration. Supported keys are: + + editor "vim" + max_depth 5 + ignored_patterns [".git", ".zig-cache"] + favorites ["~/src"] + openers [{"extensions": ["mp4"], "action": "media_player", "command": "mpv"}] + theme {"prompt": "9"} + overrides [{"path": "/work", "editor": "nvim", "max_depth": 9}] + +An opener runs _command_ for files with a listed extension. A folder +override replaces only its given keys. It applies only on exact path +match. The first matching override wins. *magdalena* ignores unknown keys. + +_~/.magdalena_ + +History store holding the directory and file logs. + +# EXIT STATUS + +0 on success. A completed listing or log write returns 0. It returns +1 when you abort the picker or when the action fails. Usage errors +also return nonzero. + +# EXAMPLES + +Show recent directories: + + $ magdalena recent-directories + +Log the current directory from shell integration: + + $ magdalena log-directory "$PWD" + +Log a file open with its type and action: + + $ magdalena log-file ./src/main.zig zig open + +Search history for one query: + + $ magdalena search "main" + +Explore files three levels deep: + + $ magdalena look-directory --depth 3 + +Pick a changed file from git status: + + $ magdalena git-status + +Grep with a starting query prefilled: + + $ magdalena grep "todo" + +Fuzzy pick from any piped list: + + $ git ls-files | magdalena select + +Embed the picker in an editor without opening anything: + + $ magdalena --choose-file /tmp/pick look-file + +# SEE ALSO + +*ugrep*(1) + +# AUTHORS + +mtmn