fsman describes a filesystem selection as a tree. A manifest can name exact
paths, select the children of a directory, recurse through a subtree, and
exclude paths. The workspace provides a reusable Rust library, a validator and
resolver CLI, an LSP server, and editor extensions for VS Code and Zed.
Manifest format
.config {
fish {
config.fish
functions {
*
!legacy.fish
}
}
hypr {
**
!cache
}
}
Work {
**
assets {
***
}
}
.hidden
Each directive occupies its own line:
| Syntax | Meaning |
|---|---|
path |
Select an exact file or directory. |
path { ... } |
Descend into a directory and apply nested directives. |
* |
Select every immediate child of the current directory. |
** |
Select recursively, respecting .gitignore files and global Git ignores inside repositories. |
*** |
Select recursively without applying Git ignore rules. |
!path |
Exclude a path and everything below it. |
Paths are relative to the current block. Absolute paths and parent traversal
with .. are rejected during resolution. Missing literal paths are ignored,
and symbolic links are selected without being followed. Git-aware recursion
also skips repository .git metadata. Both recursive forms honor
--depth <LEVELS>.
See examples/basic.fsman for a larger example.
Getting started
Build the workspace with a current Rust toolchain:
Validate a manifest:
Resolve it against a directory and print the selected tree:
The resolver also supports --depth <LEVELS> for bounded recursion,
--short for collapsed paths, --json for structured output, and --flat
for a path list. Flags can be combined, including --json --flat.
To install the published binaries from crates.io:
Node.js and TypeScript
The fsmanifest package provides a typed, promise-based API
backed by an in-process Neon addon:
import { FSMan } from "fsmanifest";
const config = await FSMan.load("./dots.fsman");
if (await FSMan.validate()) {
const paths = await FSMan.resolve(config, { short: true, flat: true });
}
The package requires Node.js 20 or newer. See its README for resolution options and local development commands.
Editor support
- Visual Studio Code provides syntax highlighting and live parser diagnostics.
- Zed registers the language and provides live parser diagnostics.
Both extensions launch fsman-lsp, which must be available on PATH or
configured explicitly in the editor.
Publishing
Publishing is handled by the manually triggered Publish release GitHub
Actions workflow. Create and push a semantic-version tag such as v0.1.0, then
run the workflow for that tag from the Actions tab. The workflow verifies that
the tag matches all Cargo and npm versions before publishing anything.
The release GitHub environment needs a CRATES_IO_TOKEN secret. npm packages
use OIDC trusted publishing configured for publish.yml and the release
environment, so no npm token is stored in GitHub. Configure that trusted
publisher on fsmanifest and on each @okei/fsmanifest-* native package. The
npm account must own the @okei scope. Cargo and npm
publishing can be enabled independently in the workflow form.
Workspace layout
crates/fsman— typed manifest model, Pest parser, and filesystem resolver.crates/fsman-cli— command-line validation and resolution.crates/fsman-lsp— stdio language server for syntax diagnostics.crates/fsman-node— Neon bindings for the Node package.node— TypeScript API for loading, validation, and resolution.vscodeandzed— editor integrations.examples— representative manifests.
Development
License
fsman is available under the MIT License.