# fs

Built-in library for filesystem access

### Example usage

```lua
local fs = require("@lune/fs")

-- Reading a file
local myTextFile: string = fs.readFile("myFileName.txt")

-- Reading entries (files & dirs) in a directory
for _, entryName in fs.readDir("myDirName") do
    if fs.isFile("myDirName/" .. entryName) then
        print("Found file " .. entryName)
    elseif if fs.isDir("myDirName/" .. entryName) then
        print("Found subdirectory " .. entryName)
    end
end
```

***

## Functions

### isDir

```lua
function FS.isDir(path: string)
```

Checks if a given path is a directory.

An error will be thrown in the following situations:

* The current process lacks permissions to read at `path`.
* Some other I/O error occurred.

### isFile

```lua
function FS.isFile(path: string)
```

Checks if a given path is a file.

An error will be thrown in the following situations:

* The current process lacks permissions to read at `path`.
* Some other I/O error occurred.

### move

```lua
function FS.move(from: string, to: string, overwriteOrOptions: (boolean | WriteOptions)?)
```

Moves a file or directory to a new path.

Throws an error if a file or directory already exists at the target path. This can be bypassed by passing `true` as the third argument, or a dictionary of options. Refer to the documentation for `WriteOptions` for specific option keys and their values.

An error will be thrown in the following situations:

* The current process lacks permissions to read at `from` or write at `to`.
* The new path exists on a different mount point.
* Some other I/O error occurred.

### readDir

```lua
function FS.readDir(path: string)
```

Reads entries in a directory at `path`.

An error will be thrown in the following situations:

* `path` does not point to an existing directory.
* The current process lacks permissions to read the contents of the directory.
* Some other I/O error occurred.

### readFile

```lua
function FS.readFile(path: string)
```

Reads a file at `path`.

An error will be thrown in the following situations:

* `path` does not point to an existing file.
* The current process lacks permissions to read the file.
* The contents of the file cannot be read as a UTF-8 string.
* Some other I/O error occurred.

### removeDir

```lua
function FS.removeDir(path: string)
```

Removes a directory and all of its contents.

An error will be thrown in the following situations:

* `path` is not an existing and empty directory.
* The current process lacks permissions to remove the directory.
* Some other I/O error occurred.

### removeFile

```lua
function FS.removeFile(path: string)
```

Removes a file.

An error will be thrown in the following situations:

* `path` does not point to an existing file.
* The current process lacks permissions to remove the file.
* Some other I/O error occurred.

### writeDir

```lua
function FS.writeDir(path: string)
```

Creates a directory and its parent directories if they are missing.

An error will be thrown in the following situations:

* `path` already points to an existing file or directory.
* The current process lacks permissions to create the directory or its missing parents.
* Some other I/O error occurred.

### writeFile

```lua
function FS.writeFile(path: string, contents: string)
```

Writes to a file at `path`.

An error will be thrown in the following situations:

* The file's parent directory does not exist.
* The current process lacks permissions to write to the file.
* Some other I/O error occurred.

***

## Types

### WriteOptions

```lua
type WriteOptions = {
	overwrite: boolean?,
}
```

Options for filesystem APIs what write to files and/or directories.

This is a dictionary that may contain one or more of the following values:

* `overwrite` - If the target path should be overwritten or not, in the case that it already exists


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lune.gitbook.io/lune/api-reference/fs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.