commit - 76ebdf31b4f697c5f276b1e8d23c153f21de0a1b
commit + e4e1272daf7324bdd4f417d61e3c03f13f5a6dde
blob - 6cbfc90996f0b0b60d8faf73d688c16ce443c780
blob + fa69aa2573f9b282ebfdb5c21f505f436af8198c
--- build.zig
+++ build.zig
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
"build.zig",
"build.zig.zon",
"src",
+ "magdalena.1.scd",
"LICENSE",
"README.md",
},
blob - /dev/null
blob + cfd2e953e514edfafdc1aaa971d517f9f215ce74 (mode 644)
--- /dev/null
+++ magdalena.1.scd
+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 <miro@haravara.org>
