Namespace fs

Module for filesystem operations. hs.fs provides a comprehensive set of filesystem operations covering file I/O, directory management, path manipulation, metadata access, symbolic links, Finder tags, and macOS-specific features like file bookmarks and Uniform Type Identifiers. It replaces both Hammerspoon v1's hs.fs module and the functionality that was previously available through Lua's built-in io and file modules.

Reading and writing files

const contents = hs.fs.read("/etc/hosts");           // entire file
const chunk    = hs.fs.read("/etc/hosts", 100, 50);  // 50 bytes from offset 100

hs.fs.readLines("/etc/hosts", function(line) {
   console.log(line);
   return true; // return false to stop early
});

hs.fs.write("/tmp/hello.txt", "Hello, world!\n");
hs.fs.append("/tmp/hello.txt", "More content\n");
Copy

Directory operations

hs.fs.mkdir("~/Projects/new-thing");

const files = hs.fs.list("~/Documents");
const all   = hs.fs.listRecursive("~/Documents");
Copy

Path utilities

const abs  = hs.fs.pathToAbsolute("~/Library");
const tmp  = hs.fs.temporaryDirectory();
const home = hs.fs.homeDirectory();
Copy

Metadata

const info = hs.fs.attributes("/etc/hosts");
// { size: 1234, type: "file", permissions: 420,
//   ownerID: 0, groupID: 0,
//   creationDate: 1700000000.0, modificationDate: 1700001000.0 }
Copy