---
title: Module fs
description: filesystem interaction and functionality library
layout: doc
menu:
docs:
parent: "API"
---
## Introduction
The fs module provides filesystem functions to Hilbish. While Lua's standard
library has some I/O functions, they're missing a lot of the basics. The `fs`
library offers more functions and will work on any operating system Hilbish does.
## Functions
|||
|----|----|
|abs(path) -> string|Returns an absolute version of the `path`.|
|basename(path) -> string|Returns the "basename," or the last part of the provided `path`. If path is empty,|
|cd(dir)|Changes Hilbish's directory to `dir`.|
|dir(path) -> string|Returns the directory part of `path`. If a file path like|
|glob(pattern) -> matches (table)|Match all files based on the provided `pattern`.|
|join(...path) -> string|Takes any list of paths and joins them based on the operating system's path separator.|
|mkdir(name, recursive)|Creates a new directory with the provided `name`.|
|fpipe() -> File, File|Returns a pair of connected files, also known as a pipe.|
|readdir(path) -> table[string]|Returns a list of all files and directories in the provided path.|
|stat(path) -> {}|Returns the information about a given `path`.|
## Static module fields
|||
|----|----|
|pathSep|The operating system's path separator.|
fs.abs(path) -> string
Returns an absolute version of the `path`.
This can be used to resolve short paths like `..` to `/home/user`.
#### Parameters
`string` **`path`**
fs.basename(path) -> string
Returns the "basename," or the last part of the provided `path`. If path is empty,
`.` will be returned.
#### Parameters
`string` **`path`**
Path to get the base name of.
fs.cd(dir)
Changes Hilbish's directory to `dir`.
#### Parameters
`string` **`dir`**
Path to change directory to.
fs.dir(path) -> string
Returns the directory part of `path`. If a file path like
`~/Documents/doc.txt` then this function will return `~/Documents`.
#### Parameters
`string` **`path`**
Path to get the directory for.
fs.glob(pattern) -> matches (table)
Match all files based on the provided `pattern`.
For the syntax' refer to Go's filepath.Match function: https://pkg.go.dev/path/filepath#Match
#### Parameters
`string` **`pattern`**
Pattern to compare files with.
#### Example
```lua
--[[
Within a folder that contains the following files:
a.txt
init.lua
code.lua
doc.pdf
]]--
local matches = fs.glob './*.lua'
print(matches)
-- -> {'init.lua', 'code.lua'}
```
fs.join(...path) -> string
Takes any list of paths and joins them based on the operating system's path separator.
#### Parameters
`string` **`path`** (This type is variadic. You can pass an infinite amount of parameters with this type.)
Paths to join together
#### Example
```lua
-- This prints the directory for Hilbish's config!
print(fs.join(hilbish.userDir.config, 'hilbish'))
-- -> '/home/user/.config/hilbish' on Linux
```
fs.mkdir(name, recursive)
Creates a new directory with the provided `name`.
With `recursive`, mkdir will create parent directories.
#### Parameters
`string` **`name`**
Name of the directory
`boolean` **`recursive`**
Whether to create parent directories for the provided name
#### Example
```lua
-- This will create the directory foo, then create the directory bar in the
-- foo directory. If recursive is false in this case, it will fail.
fs.mkdir('./foo/bar', true)
```
fs.fpipe() -> File, File
Returns a pair of connected files, also known as a pipe.
The type returned is a Lua file, same as returned from `io` functions.
#### Parameters
This function has no parameters.
fs.readdir(path) -> table[string]
Returns a list of all files and directories in the provided path.
#### Parameters
`string` **`dir`**
fs.stat(path) -> {}
Returns the information about a given `path`.
The returned table contains the following values:
name (string) - Name of the path
size (number) - Size of the path in bytes
mode (string) - Unix permission mode in an octal format string (with leading 0)
isDir (boolean) - If the path is a directory
#### Parameters
`string` **`path`**
#### Example
```lua
local inspect = require 'inspect'
local stat = fs.stat '~'
print(inspect(stat))
--[[
Would print the following:
{
isDir = true,
mode = "0755",
name = "username",
size = 12288
}
]]--
```