> ## Documentation Index > Fetch the complete documentation index at: https://site.aspect.build/llms.txt > Use this file to discover all available pages before exploring further. # File system `function` **FileSystem.copy** 
        
          def FileSystem.copy(
          from: str,
          to: str,
          /
          ) -> int
Copies the contents of one file to another. This function will also copy the permission bits of the original file to the destination file. This function will overwrite the contents of to. Note that if from and to both point to the same file, then the file will likely get truncated by this operation. On success, the total number of bytes copied is returned and it is equal to the length of the to file as reported by metadata. This function will return an error in the following situations, but is not limited to just these cases: * from is neither a regular file nor a symlink to a regular file. * from does not exist. * The current process does not have the permission rights to read from or write to. * The parent directory of to doesn’t exist. `function` **FileSystem.create** 
        
          def FileSystem.create(
          path: str,
          /
          ) -> std.io.Writable
Creates (or truncates) a file for writing and returns it as a writable stream. Mirrors `std::fs::File::create` — the file is opened write-only and truncated to zero length, or created if it does not exist. `function` **FileSystem.create\_dir** 
        
          def FileSystem.create\_dir(
          path: str,
          /
          ) -> None
Creates a new, empty directory at the provided path. This function will return an error in the following situations, but is not limited to just these cases: * User lacks permissions to create directory at path. * A parent of the given path doesn’t exist. (To create a directory and all its missing parents at the same time, use the createidirlall function.) * path already exists. NOTE: If a parent of the given path doesn’t exist, this function will return an error. To create a directory and all its missing parents at the same time, use the createidirlall function. `function` **FileSystem.create\_dir\_all** 
        
          def FileSystem.create\_dir\_all(
          path: str,
          /
          ) -> None
Recursively create a directory and all of its parent components if they are missing. This function is not atomic. If it returns an error, any parent components it was able to create will remain. If the empty path is passed to this function, it always succeeds without creating any directories. The function will return an error if any directory specified in path does not exist and could not be created. There may be other error conditions; see create\_dir for specifics. `function` **FileSystem.exists** 
        
          def FileSystem.exists(
          path: str,
          /
          ) -> bool
Returns `true` if the path points at an existing entity. This function will traverse symbolic links to query information about the destination file. In case of broken symbolic links this will return `false`. Note that while this avoids some pitfalls of the `exists()` method, it still can not prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios where those bugs are not an issue. `function` **FileSystem.hard\_link** 
        
          def FileSystem.hard\_link(
          original: str,
          link: str,
          /
          ) -> None
Creates a new hard link on the filesystem. The link path will be a link pointing to the original path. Note that systems often require these two paths to both be located on the same filesystem. If original names a symbolic link, it is platform-specific whether the symbolic link is followed. On platforms where it’s possible to not follow it, it is not followed, and the created hard link points to the symbolic link itself. This function will return an error in the following situations, but is not limited to just these cases: * The original path is not a file or doesn’t exist. * The ‘link’ path already exists. `function` **FileSystem.is\_dir** 
        
          def FileSystem.is\_dir(
          path: str,
          /
          ) -> bool
Returns true if this path is for a directory. This function will return an error in the following situations, but is not limited to just these cases: * The user lacks permissions to perform metadata call on path. * path does not exist. `function` **FileSystem.is\_file** 
        
          def FileSystem.is\_file(
          path: str,
          /
          ) -> bool
Returns true if this path is for a regular file. This function will return an error in the following situations, but is not limited to just these cases: * The user lacks permissions to perform metadata call on path. * path does not exist. `function` **FileSystem.metadata** 
        
          def FileSystem.metadata(
          path: str,
          /
          ) -> fs.Metadata
Returns the metadata about the given file or directory. This function will return an error in the following situations, but is not limited to just these cases: * The user lacks permissions to perform metadata call on path. * path does not exist. The modified, accessed, created fields of the Metadata result might not be available on all platforms, and will be set to None on platforms where they is not available. The executable field reflects the Unix execute bit; it is always false on non-Unix platforms. `function` **FileSystem.mkdtemp** 
        
          def FileSystem.mkdtemp(
          \*,
          prefix: str = "",
          parent: str = ""
          ) -> str
Creates a new temporary directory with a unique name and returns its path. The directory is created inside `parent` (defaults to the system temp dir). The caller is responsible for removing it when done. `function` **FileSystem.open** 
        
          def FileSystem.open(
          path: str,
          /
          ) -> std.io.Readable
Opens a file for reading and returns it as a readable stream. The returned stream can be passed directly as the `data` argument to `ctx.http().post()` or `ctx.http().put()` for streaming uploads, or iterated over / read directly. `function` **FileSystem.read\_dir** 
        
          def FileSystem.read\_dir(
          path: str,
          /
          ) -> list\[fs.DirEntry]
Returns an iterator over the entries within a directory. This function will return an error in the following situations, but is not limited to just these cases: * The provided path doesn’t exist. * The process lacks permissions to view the contents. * The path points at a non-directory file. `function` **FileSystem.read\_link** 
        
          def FileSystem.read\_link(
          path: str,
          /
          ) -> str
Reads a symbolic link, returning the file that the link points to. This function will return an error in the following situations, but is not limited to just these cases: * path is not a symbolic link. * path does not exist. `function` **FileSystem.read\_to\_string** 
        
          def FileSystem.read\_to\_string(
          path: str,
          /
          ) -> str
Reads the entire contents of a file into a string. This function will return an error under a number of different circumstances. Some of these error conditions are: * The specified file does not exist. * The user lacks permission to get the specified access rights for the file. * The user lacks permission to open one of the directory components of the specified path. `function` **FileSystem.remove\_dir** 
        
          def FileSystem.remove\_dir(
          path: str,
          /
          ) -> None
Removes an empty directory. If you want to remove a directory that is not empty, as well as all of its contents recursively, consider using remove\_dir\_all instead. This function will return an error in the following situations, but is not limited to just these cases: * path doesn’t exist. * path isn’t a directory. * The user lacks permissions to remove the directory at the provided path. * The directory isn’t empty. `function` **FileSystem.remove\_dir\_all** 
        
          def FileSystem.remove\_dir\_all(
          path: str,
          /
          ) -> None
Removes a directory at this path, after removing all its contents. Use carefully! This function does not follow symbolic links and it will simply remove the symbolic link itself. See remove\_file and remove\_dir for possible errors. `function` **FileSystem.remove\_file** 
        
          def FileSystem.remove\_file(
          path: str,
          /
          ) -> None
Removes a file from the filesystem. Note that there is no guarantee that the file is immediately deleted (e.g., depending on platform, other open file descriptors may prevent immediate removal). This function will return an error in the following situations, but is not limited to just these cases: * path points to a directory. * The file doesn’t exist. * The user lacks permissions to remove the file. `function` **FileSystem.rename** 
        
          def FileSystem.rename(
          from: str,
          to: str,
          /
          ) -> None
Renames a file or directory to a new name, replacing the original file if to already exists. This will not work if the new name is on a different mount point. This function will return an error in the following situations, but is not limited to just these cases: * from does not exist. * The user lacks permissions to view contents. * from and to are on separate filesystems. `function` **FileSystem.symlink\_metadata** 
        
          def FileSystem.symlink\_metadata(
          path: str,
          /
          ) -> fs.Metadata
Queries the metadata about a file without following symlinks. This function will return an error in the following situations, but is not limited to just these cases: * The user lacks permissions to perform metadata call on path. * path does not exist. The modified, accessed, created fields of the Metadata result might not be available on all platforms, and will be set to None on platforms where they is not available. The executable field reflects the Unix execute bit; it is always false on non-Unix platforms. `function` **FileSystem.try\_append** 
        
          def FileSystem.try\_append(
          path: str,
          content: str,
          /
          ) -> bool
Appends a string to the end of a file, creating it if it does not exist. Opens the file with `OpenOptions::append(true)` so concurrent writers see their bytes interleaved at record boundaries rather than racing. POSIX `O_APPEND` is atomic for writes ≤ `PIPE_BUF`, which covers the short single-line records this is designed for (the `runner_job_history` lines fit comfortably). The parent directory must exist; this function will not create intermediate directories. Returns `True` on success and `False` on any I/O error (parent directory missing, permissions denied, target is a directory, etc.). Errors are swallowed because the primary caller is the runner job history hook, where a write failure must never fail the task. `function` **FileSystem.try\_read\_to\_string** 
        
          def FileSystem.try\_read\_to\_string(
          path: str,
          /
          ) -> str
Reads the entire contents of a file into a string, or returns `""` on any I/O error (missing file, permission denied, non-UTF-8 content, transient read failure). Companion to `try_append`: the silent fall-through lets callers handle never-fail invariants without try/except — e.g. the runner job history dedup read, where a failed read must degrade to "assume empty file" rather than fail the task. `function` **FileSystem.write** 
        
          def FileSystem.write(
          path: str,
          content: str,
          /
          ) -> None
Writes a string as the entire contents of a file. This function will create a file if it does not exist, and will entirely replace its contents if it does. Depending on the platform, this function may fail if the full directory path does not exist. This is a convenience function for using fs.create and \[write\_all] with fewer imports.