### Start babashka fs development REPL

Source: https://github.com/babashka/fs/blob/master/README.md

Command to launch a REPL environment for developing and testing babashka.fs.

```shell
bb dev
```

--------------------------------

### babashka.fs/starts-with?

Source: https://github.com/babashka/fs/blob/master/API.md

Checks if a given path starts with another path. This is useful for path prefix checks.

```APIDOC
## babashka.fs/starts-with?

### Description
Returns `true` if `this-path` starts with `other-path` via [Path#startsWith](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Path.html#startsWith(java.nio.file.Path)).

See also: [`ends-with?`](#babashka.fs/ends-with?)

### Function Signature
```clojure
(starts-with? this-path other-path)
```

### Parameters
* `this-path` - The path to check.
* `other-path` - The path prefix to look for.

### Returns
`true` if `this-path` starts with `other-path`, `false` otherwise.

### Example
```clojure
(fs/starts-with? "/usr/local/bin" "/usr/local") ;=> true
(fs/starts-with? "/usr/local" "/usr/local/bin") ;=> false
```
```

--------------------------------

### Get XDG Config Home Directory

Source: https://github.com/babashka/fs/blob/master/API.md

Returns the path to the user's configuration directory. Optionally appends an application name to the path.

```clojure
(xdg-config-home)
(xdg-config-home app)
```

--------------------------------

### Check Path Prefix

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Returns `true` if the first path starts with the second path. Use this for prefix matching.

```clojure
(starts-with? this-path other-path)
```

--------------------------------

### Handle NoSuchFileException

Source: https://github.com/babashka/fs/blob/master/_autodocs/errors.md

Catch and handle the NoSuchFileException when reading a file. This example provides default content if the configuration file is not found.

```clojure
(try
  (fs/read-all-lines "config.txt")
  (catch java.nio.file.NoSuchFileException e
    (println "Config file not found, using defaults")
    ["default"
     "config"])))
```

--------------------------------

### Get XDG State Home Directory

Source: https://github.com/babashka/fs/blob/master/API.md

Returns the path to user-specific state files. Uses XDG_STATE_HOME env-var if set, otherwise defaults to ~/.local/state. Optionally appends an application name.

```clojure
(xdg-state-home)
```

```clojure
(xdg-state-home app)
```

--------------------------------

### Path Coercion Examples

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Demonstrates how to coerce path objects to different types: String, Path, or File. These functions are useful when you need a specific representation of a path.

```clojure
(str (fs/cwd))      ;; String
(fs/path (fs/cwd))  ;; Path
(fs/file (fs/cwd))  ;; File
```

--------------------------------

### Handle FileAlreadyExistsException

Source: https://github.com/babashka/fs/blob/master/_autodocs/errors.md

Catch and handle the FileAlreadyExistsException when creating a file. This example shows how to overwrite the existing file after backing it up.

```clojure
(try
  (fs/create-file "output.txt")
  (catch java.nio.file.FileAlreadyExistsException e
    (println "File exists, overwriting...")
    (fs/copy "output.txt" "output.bak" {:replace-existing true})
    (fs/create-file "output.txt")))
```

--------------------------------

### Get XDG Data Home Directory

Source: https://github.com/babashka/fs/blob/master/API.md

Returns the path to the user's data directory. Optionally appends an application name to the path.

```clojure
(xdg-data-home)
(xdg-data-home app)
```

--------------------------------

### Find Executable in PATH

Source: https://github.com/babashka/fs/blob/master/README.md

Locate an executable file, such as 'java', by searching through the directories listed in the system's PATH environment variable. This example demonstrates filtering for existing and executable files.

```clojure
(str (first (filter fs/executable? (fs/list-dirs (filter fs/exists? (fs/exec-paths)) "java"))))
```

--------------------------------

### Expand Tilde in Path

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Expands a tilde (~) at the beginning of a path string to the user's home directory. Handles paths starting with ~user.

```clojure
(fs/expand-home "~/projects/my-app")
```

```clojure
(fs/expand-home "~root/config")
```

--------------------------------

### Get XDG Cache Home Directory

Source: https://github.com/babashka/fs/blob/master/API.md

Returns the path to the user's cache directory. Optionally appends an application name to the path.

```clojure
(xdg-cache-home)
(xdg-cache-home app)
```

--------------------------------

### Access Home and XDG Directories

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Get the current user's home directory with fs/home, or a specific user's home. Expand tilde paths using fs/expand-home. Access XDG standard directories like config, cache, data, and state homes, which respect environment variables like $XDG_CONFIG_HOME.

```clojure
(fs/home)                         ;; Current user home
```

```clojure
(fs/home "root")                  ;; Specific user home
```

```clojure
(fs/expand-home "~/projects")     ;; Expand ~ in path
```

```clojure
(fs/xdg-config-home)              ;; ~/.config or $XDG_CONFIG_HOME
```

```clojure
(fs/xdg-config-home "myapp")      ;; ~/.config/myapp
```

```clojure
(fs/xdg-cache-home)               ;; ~/.cache or $XDG_CACHE_HOME
```

```clojure
(fs/xdg-data-home)                ;; ~/.local/share or $XDG_DATA_HOME
```

```clojure
(fs/xdg-state-home)               ;; ~/.local/state or $XDG_STATE_HOME
```

--------------------------------

### Handle DirectoryNotEmptyException

Source: https://github.com/babashka/fs/blob/master/_autodocs/errors.md

Catch and handle the DirectoryNotEmptyException when attempting to delete a directory. This example demonstrates falling back to deleting the entire directory tree.

```clojure
(try
  (fs/delete "directory")
  (catch java.nio.file.DirectoryNotEmptyException e
    (println "Directory not empty, deleting tree instead...")
    (fs/delete-tree "directory")))
```

--------------------------------

### Creating Files & Dirs

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Demonstrates how to create files, directories, and temporary files/directories using the fs/create-* functions. It also shows how to set POSIX file permissions and use temporary directories with automatic cleanup.

```APIDOC
## Creating Files & Dirs

### Description
Functions for creating files, directories, and temporary file system objects.

### Functions
- `fs/create-file`
- `fs/create-dir`
- `fs/create-dirs`
- `fs/create-temp-file`
- `fs/create-temp-dir`
- `fs/with-temp-dir`

### Examples
```clojure
(fs/create-file "f.txt")          ;;
(fs/create-file "f.txt" {:posix-file-permissions "rw-------"})
(fs/create-dir "dir")             ;;
(fs/create-dirs "a/b/c")          ;;
(fs/create-temp-file)
(fs/create-temp-file {:prefix "tmp-" :suffix ".log"})
(fs/create-temp-dir)
(fs/with-temp-dir [d]             ;;
  (fs/create-file (fs/path d "f.txt")))
```
```

--------------------------------

### Get File Separator Constant (file-separator)

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Access the `file-separator` constant to get the OS-specific file separator character as a string (e.g., '/' on Unix, '\' on Windows).

```clojure
fs/file-separator
```

--------------------------------

### File I/O

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Provides examples for reading and writing file content, including lines, bytes, and appending to files, with support for character sets and file updates.

```APIDOC
## File I/O

### Description
Functions for reading from and writing to files.

### Functions
- `fs/read-all-lines`
- `fs/read-all-bytes`
- `fs/write-lines`
- `fs/write-bytes`
- `fs/update-file`

### Examples
```clojure
(fs/read-all-lines "f.txt")       ;;
(fs/read-all-lines "f.txt" {:charset "utf-8"})
(fs/read-all-bytes "f.bin")       ;;
(fs/write-lines "f.txt" ["a" "b"])
(fs/write-bytes "f.bin" bytes)
(fs/write-bytes "f.txt" bytes {:append true}) ;; 
(fs/update-file "f.txt" clojure.string/upper-case)
```
```

--------------------------------

### Create a directory with babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `create-dir` to create a single directory. It does not create parent directories. POSIX file permissions can be specified.

```clojure
(create-dir dir)
```

```clojure
(create-dir dir {:keys [:posix-file-permissions]})
```

--------------------------------

### Get System Temporary Directory (temp-dir)

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `temp-dir` to get the system's temporary directory path, sourced from the `java.io.tmpdir` property. It returns a `java.nio.file.Path` object.

```clojure
(fs/temp-dir)
```

--------------------------------

### Get File Owner with babashka.fs/owner

Source: https://github.com/babashka/fs/blob/master/API.md

Retrieves the owner of a file path. Supports an option to ignore symbolic links. Call `str` on the result to get the owner's name.

```clojure
(owner path)
(owner path {:keys [:nofollow-links]})
```

--------------------------------

### Create Files and Directories

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Use `fs/create-file` to create empty files or files with specific permissions. `fs/create-dir` creates a single directory, while `fs/create-dirs` creates a directory and any necessary parent directories. Temporary files and directories can be created with `fs/create-temp-file` and `fs/create-temp-dir`, respectively. `fs/with-temp-dir` provides an automatically cleaned-up temporary directory.

```clojure
(fs/create-file "f.txt")          ;; Create empty file
(fs/create-file "f.txt" {:posix-file-permissions "rw-------"))
(fs/create-dir "dir")             ;; Create single dir (parent must exist)
(fs/create-dirs "a/b/c")          ;; Create dir and parents
(fs/create-temp-file)             ;; Random temp file
(fs/create-temp-file {:prefix "tmp-" :suffix ".log"})
(fs/create-temp-dir)              ;; Random temp dir
(fs/with-temp-dir [d]             ;; Auto-cleanup temp dir
  (fs/create-file (fs/path d "f.txt")))
```

--------------------------------

### Get Home Directory Path

Source: https://github.com/babashka/fs/blob/master/API.md

Retrieves the current user's home directory. An optional user argument can be provided to get another user's home directory.

```clojure
(home)
(home user)
```

--------------------------------

### cwd

Source: https://github.com/babashka/fs/blob/master/API.md

Gets the current working directory of the process.

```APIDOC
## cwd

### Description
Returns current working directory path.

### Function Signature
```clojure
(cwd)
```
```

--------------------------------

### Basic File System Operations in Babashka

Source: https://github.com/babashka/fs/blob/master/_autodocs/README.md

Demonstrates common file system tasks like checking existence, creating directories, listing files, copying, moving, deleting, reading, and writing files. Also includes archive operations like zipping and unzipping.

```clojure
(require '[babashka.fs :as fs])

;; Check path existence
(fs/exists? "README.md")           ;; => true
(fs/directory? ".")                ;; => true

;; Create directories
(fs/create-dirs "a/b/c")
(fs/with-temp-dir [tmpdir]
  (fs/create-file (fs/path tmpdir "file.txt")))

;; List files
(fs/glob "." "**/*.clj")
(fs/list-dir "src")

;; File operations
(fs/copy "source.txt" "dest.txt")
(fs/move "old.txt" "new.txt")
(fs/delete-tree "directory")

;; Read/write
(fs/read-all-lines "config.txt")
(fs/write-lines "output.txt" ["line1" "line2"])

;; Archives
(fs/zip "archive.zip" ["src" "README.md"])
(fs/unzip "archive.zip" "extracted/")
```

--------------------------------

### Create a temporary file with default options

Source: https://github.com/babashka/fs/blob/master/API.md

Use this to create a temporary file with default settings. The file is not automatically deleted.

```clojure
(create-temp-file)
```

--------------------------------

### Get System Path Separator

Source: https://github.com/babashka/fs/blob/master/API.md

Retrieves the system-dependent path-separator character as a string.

```clojure
(fs/path-separator)
```

--------------------------------

### Get Current Working Directory

Source: https://github.com/babashka/fs/blob/master/API.md

Returns the path of the current working directory.

```clojure
(cwd)
```

--------------------------------

### Create Directories Recursively with Permissions

Source: https://github.com/babashka/fs/blob/master/API.md

Creates a directory and any necessary parent directories. This is similar to the `mkdir -p` command. It does not throw an error if the directory already exists and supports specifying POSIX file permissions.

```clojure
(create-dirs dir)
```

```clojure
(create-dirs dir {:keys [:posix-file-permissions]})
```

--------------------------------

### Create a temporary file with babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `create-temp-file` to create a temporary file. Options include specifying the parent directory, a prefix for the file name, a suffix, and POSIX file permissions.

```clojure
(fs/create-temp-file {:prefix "tmp-" :suffix ".log"})
```

--------------------------------

### Get File Extension

Source: https://github.com/babashka/fs/blob/master/API.md

Retrieves the file extension from a given path using the split-ext function.

```clojure
(extension path)
```

--------------------------------

### Copying Files and Directories

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Use `fs/copy` for individual files and `fs/copy-tree` for recursive directory copies. Options like `:replace-existing` can be provided.

```clojure
(fs/copy "src.txt" "dst.txt")     ;; Copy file
```

```clojure
(fs/copy "src.txt" "dir/")        ;; Copy into dir
```

```clojure
(fs/copy "src.txt" "dst.txt" {:replace-existing true})
```

```clojure
(fs/copy in-stream "out.bin")     ;; From InputStream
```

```clojure
(fs/copy-tree "src/" "dst/")      ;; Recursive copy
```

```clojure
(fs/copy-tree "src/" "dst/" {:replace-existing true})
```

--------------------------------

### Extract Filename: babashka.fs/file-name

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `fs/file-name` to get the final component of a path, which is the file or directory name.

```clojure
(fs/file-name "foo/bar/baz.txt")
;; => "baz.txt"

(fs/file-name ".")
;; => "."
```

--------------------------------

### Type Conversion Utilities for Paths and Files

Source: https://github.com/babashka/fs/blob/master/_autodocs/types.md

Demonstrates conversion functions for creating Path and File objects, and converting the current working directory to a string.

```clojure
(def p "/home/user/file.txt")

;; To Path
(fs/path p)

;; To File
(fs/file p)
```

```clojure
;; To String
(str (fs/cwd))
```

--------------------------------

### match

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Finds paths matching a pattern with an explicit prefix (glob or regex) starting from a root directory.

```APIDOC
## match

### Description
Returns paths matching a pattern with explicit prefix (glob, regex).

### Parameters
#### Path Parameters
- **root-dir** (string | File | Path) - Required - Root directory
- **pattern** (string) - Required - Pattern with prefix like `"glob:*.clj"` or `"regex:.*\\.clj"`
- **opts** (map) - Optional - Options map
  - **:hidden** (boolean) - Default: false - Include hidden files
  - **:follow-links** (boolean) - Default: false - Follow symbolic links
  - **:recursive** (boolean) - Default: false - Recursively search subdirectories
  - **:max-depth** (integer) - Default: Integer.MAX_VALUE - Maximum directory depth

### Returns
`vector` of `java.nio.file.Path`

### Example
```clojure
(fs/match "." "glob:*.clj")
(fs/match "." "regex:.*\\.clj$" {:recursive true})
```
```

--------------------------------

### babashka.fs/create-dirs

Source: https://github.com/babashka/fs/blob/master/API.md

Creates a directory, including any necessary but nonexistent parent directories. Uses Java's Files#createDirectories() method.

```APIDOC
## create-dirs

### Description
Creates `dir` via [Files/createDirectories](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Files.html#createDirectories(java.nio.file.Path,java.nio.file.attribute.FileAttribute...)).

### Parameters
#### Path Parameters
- **dir** (string | Path) - The directory to create.
- **attrs** (optional Repeatable) - File attributes to set during creation.

### Response
#### Success Response (Path)
- Returns the created directory path.
```

--------------------------------

### POSIX File Permissions in Babashka FS

Source: https://github.com/babashka/fs/blob/master/_autodocs/README.md

Shows how to set and read POSIX file permissions on Unix-like systems using `fs/create-file` with permission options and `fs/set-posix-file-permissions`. Also demonstrates converting permissions to a string representation.

```clojure
;; On Unix-like systems
(fs/create-file "secret.txt" {:posix-file-permissions "rw-------
ě})
(fs/set-posix-file-permissions "file.txt" "rwx------")
```

```clojure
;; Read as string
(fs/posix->str (fs/posix-file-permissions "file.txt"))
;; => "rw-r--r--"
```

--------------------------------

### Create nested directories with babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `create-dirs` to create a directory and all its parent directories. This function is idempotent and does not throw an error if the directory already exists, similar to `mkdir -p`.

```clojure
(fs/create-dirs "a/b/c/d")
```

--------------------------------

### Get Temporary Directory Path

Source: https://github.com/babashka/fs/blob/master/API.md

Returns the path to the system's temporary directory, as defined by the java.io.tmpdir property.

```clojure
(temp-dir)
```

--------------------------------

### Get Parent Directory with babashka.fs/parent

Source: https://github.com/babashka/fs/blob/master/API.md

Returns the parent directory of a given path. This is analogous to the `dirname` command in bash.

```clojure
(parent path)
```

--------------------------------

### Create an empty file with babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `create-file` to create an empty file at the specified path. Optionally, you can set POSIX file permissions.

```clojure
(fs/create-file "new-file.txt")
```

```clojure
(fs/create-file "secret.txt" {:posix-file-permissions "rw-------ად"})
```

--------------------------------

### Path Basics

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Common operations for creating and manipulating paths.

```clojure
(fs/cwd)                          ;; Current working directory
```

```clojure
(fs/path "a" "b" "c")             ;; Combine: "a/b/c"
```

```clojure
(fs/path "/abs/path")             ;; Parse any path format
```

```clojure
(str path)                         ;; Convert Path to string
```

--------------------------------

### Get File Attribute

Source: https://github.com/babashka/fs/blob/master/API.md

Retrieves a specific attribute for a given file path. Supports options like :nofollow-links.

```clojure
(get-attribute path attribute)
(get-attribute path attribute {:keys [:nofollow-links]})
```

--------------------------------

### Create a temporary file with custom options

Source: https://github.com/babashka/fs/blob/master/API.md

Create a temporary file with specified options like POSIX permissions. The file is not automatically deleted.

```clojure
(create-temp-file {:keys [:dir :prefix :suffix :posix-file-permissions], :as opts})
```

--------------------------------

### Get XDG State Home

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieves the XDG Base Directory for user state files. Defaults to ~/.local/state.

```clojure
(fs/xdg-state-home)
```

--------------------------------

### Check operating system and path separators

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Provides utilities to determine the operating system and retrieve the appropriate file and path separators. Useful for cross-platform compatibility.

```clojure
(fs/windows?)
;; Running on Windows?
(fs/file-separator)
;; "/" or "\"
(fs/path-separator)
;; ":" or ";"
(fs/temp-dir)
;; System temp directory
```

--------------------------------

### Get XDG Data Home

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieves the XDG Base Directory for user data files. Defaults to ~/.local/share.

```clojure
(fs/xdg-data-home)
```

--------------------------------

### Create a temporary file in a specific directory with prefix and suffix

Source: https://github.com/babashka/fs/blob/master/API.md

Create a temporary file in a custom directory with a specified prefix and suffix. The file is not automatically deleted.

```clojure
(create-temp-file {:dir (path (cwd) "_workdir") :prefix "process-1-" :suffix "-queue"})
```

--------------------------------

### Get XDG Cache Home

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieves the XDG Base Directory for user cache files. Defaults to ~/.cache.

```clojure
(fs/xdg-cache-home)
```

--------------------------------

### Read File Attributes

Source: https://github.com/babashka/fs/blob/master/_autodocs/types.md

Use `fs/read-attributes` to get file metadata. The function returns a map with keywordized keys.

```clojure
(fs/read-attributes "file.txt" "basic:*")
;; => {:size 1024
;;     :is-regular-file true
;;     :is-directory false
;;     :creation-time #object[java.nio.file.attribute.FileTime ...]
;;     ...}
```

--------------------------------

### Read Configuration with Fallback using Try-Catch

Source: https://github.com/babashka/fs/blob/master/_autodocs/errors.md

Read a configuration file, providing a default configuration if the file is not found or if any other exception occurs during reading. Catches NoSuchFileException and general Exceptions.

```clojure
(defn read-config [path default-config]
  (try
    (edn/read-string (slurp path))
    (catch java.nio.file.NoSuchFileException _
      (println "Config not found, using defaults")
      default-config)
    (catch Exception e
      (println "Error reading config:" e)
      default-config)))
```

--------------------------------

### Time and Permission Type Conversions

Source: https://github.com/babashka/fs/blob/master/_autodocs/types.md

Shows how to convert between file time representations and instant objects, and between string and POSIX permission formats.

```clojure
;; Between time types
(fs/file-time->instant (fs/last-modified-time p))
(fs/instant->file-time (java.time.Instant/now))
```

```clojure
;; Between permission types
(fs/str->posix "rwx------")
(fs/posix->str (fs/posix-file-permissions p))
```

--------------------------------

### Get File Owner Username

Source: https://github.com/babashka/fs/blob/master/_autodocs/types.md

Retrieves the owner of a file and converts the `UserPrincipal` object to its string representation (username).

```clojure
(str (fs/owner "file.txt"))
;; => "username"
```

--------------------------------

### Create a temporary directory with babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `create-temp-dir` to create a temporary directory. You can specify a parent directory, a prefix for the directory name, and POSIX file permissions. Note that this function does not automatically delete the directory.

```clojure
(fs/create-temp-dir)
```

```clojure
(fs/create-temp-dir {:prefix "my-app-" :posix-file-permissions "rwx------"})
```

--------------------------------

### Get Size of a Path

Source: https://github.com/babashka/fs/blob/master/API.md

Returns the size of the specified path in bytes. This is useful for determining the disk space occupied by a file.

```clojure
(size path)
```

--------------------------------

### Get the root of a path

Source: https://github.com/babashka/fs/blob/master/API.md

Use `root` to retrieve the root component of a path. The format of the root depends on the operating system.

```clojure
(root path)
```

--------------------------------

### Copy Directory Tree with Options

Source: https://github.com/babashka/fs/blob/master/API.md

Copies an entire directory tree from a source to a target. The target directory is created if it doesn't exist. Options can control replacing existing files, copying attributes, and following symbolic links.

```clojure
(copy-tree source-dir target-dir)
```

```clojure
(copy-tree source-dir target-dir {:keys [:replace-existing :copy-attributes :nofollow-links], :as opts})
```

--------------------------------

### Get Executable Paths

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieves directories from the PATH environment variable as a vector of Path objects. Useful for finding executables.

```clojure
(fs/exec-paths)
```

--------------------------------

### Temporary Directory Management in Babashka FS

Source: https://github.com/babashka/fs/blob/master/_autodocs/README.md

Demonstrates the use of `fs/with-temp-dir` for creating and automatically cleaning up temporary directories, useful for temporary file operations.

```clojure
;; Use with-temp-dir for cleanup
(fs/with-temp-dir [tmpdir]
  (fs/write-lines (fs/path tmpdir "temp.txt") ["data"]))
;; Automatically deleted
```

--------------------------------

### File Creation Exception Cases

Source: https://github.com/babashka/fs/blob/master/_autodocs/errors.md

Understand potential exceptions like FileAlreadyExistsException, NoSuchFileException, and FileSystemException when creating files, directories, or temporary files.

```clojure
;; May throw:
(fs/create-file path)
;;  - FileAlreadyExistsException if exists
;;  - NoSuchFileException if parent doesn't exist
;;  - FileSystemException for permission/disk errors

(fs/create-dir path)
;;  - FileAlreadyExistsException if exists
;;  - NoSuchFileException if parent doesn't exist
;;  - FileSystemException for permission/disk errors

(fs/create-dirs path)
;;  - FileSystemException for permission/disk errors
;;  - Never throws FileAlreadyExistsException (creates if missing)

(fs/create-temp-dir)
;;  - FileSystemException for disk/permission errors
;;  - Very unlikely FileAlreadyExistsException (UUID-based names)

(fs/create-temp-file)
;;  - FileSystemException for disk/permission errors
;;  - Very unlikely FileAlreadyExistsException (UUID-based names)
```

--------------------------------

### Get Last Modified Time

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieves the last modified time of a file. Supports an option to not follow symbolic links.

```clojure
(last-modified-time path)
(last-modified-time path {:keys [nofollow-links]})
```

--------------------------------

### create-dirs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Creates a directory and all necessary parent directories. It does not throw an error if the directory already exists.

```APIDOC
## create-dirs

### Description
Creates a directory and all parent directories. Does not throw if already exists (like `mkdir -p`).

### Signature
```clojure
(create-dirs dir)
(create-dirs dir {:keys [:posix-file-permissions]})
```

### Parameters
#### Path Parameter
- **dir** (string | File | Path) - Required - Directory path

#### Options
- **:posix-file-permissions** (string) - Optional - POSIX permissions

### Returns
`java.nio.file.Path`

### Example
```clojure
(fs/create-dirs "a/b/c/d")
;; Creates all intermediate directories
```
```

--------------------------------

### Get Path Components: babashka.fs/components

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `fs/components` to decompose a path into its individual components, returning a sequence of `java.nio.file.Path` objects.

```clojure
(fs/components "foo/bar/baz")
;; => (#object[sun.nio.fs.UnixPath 0x... "foo"]
;;     #object[sun.nio.fs.UnixPath 0x... "bar"]
;;     #object[sun.nio.fs.UnixPath 0x... "baz"])
```

--------------------------------

### babashka.fs/create-dir

Source: https://github.com/babashka/fs/blob/master/API.md

Creates a directory. This function uses Java's Files#createDirectory() method.

```APIDOC
## create-dir

### Description
Creates `dir` via [Files/createDirectory](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Files.html#createDirectory(java.nio.file.Path,java.nio.file.attribute.FileAttribute...)).

### Parameters
#### Path Parameters
- **dir** (string | Path) - The directory to create.
- **attrs** (optional Repeatable) - File attributes to set during creation.

### Response
#### Success Response (Path)
- Returns the created directory path.
```

--------------------------------

### Find .clj files recursively

Source: https://github.com/babashka/fs/blob/master/API.md

Use this snippet to find all .clj files and directories recursively starting from the current directory.

```clojure
(fs/glob "." "**.clj")
```

--------------------------------

### Walking Trees

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Illustrates how to traverse a directory tree recursively using `fs/walk-file-tree`, with options to control visiting behavior and depth.

```APIDOC
## Walking Trees

### Description
Recursively traverse a directory tree.

### Function
- `fs/walk-file-tree`

### Examples
```clojure
(fs/walk-file-tree "."
  {:visit-file (fn [f attrs] (println f) :continue)})
(fs/walk-file-tree "."
  {:max-depth 2
   :visit-file (fn [f _] :continue)
   :visit-file-failed (fn [f e] :continue)})
```
```

--------------------------------

### Creating Files

Source: https://github.com/babashka/fs/blob/master/_autodocs/README.md

Functions for creating files, directories, links, and temporary file system objects.

```APIDOC
## Creating Files

### Create file
- `create-file`

### Create directory
- `create-dir`
- `create-dirs`

### Temporary file
- `create-temp-file`

### Temporary directory
- `create-temp-dir`
- `with-temp-dir`

### Symbolic link
- `create-sym-link`

### Hard link
- `create-link`
```

--------------------------------

### Get Posix File Permissions

Source: https://github.com/babashka/fs/blob/master/API.md

Retrieves the PosixFilePermission set for a given path. Use `:nofollow-links` option to ignore symbolic links.

```clojure
(posix-file-permissions path)
(posix-file-permissions path {:keys [:nofollow-links]})
```

--------------------------------

### Create File with POSIX Permissions

Source: https://github.com/babashka/fs/blob/master/_autodocs/configuration.md

Creates a new file with specified POSIX file permissions. Useful for setting restrictive access controls on configuration files.

```clojure
(require '[babashka.fs :as fs])

;; Create with restrictive permissions
(fs/create-file "config.edn" {:posix-file-permissions "rw-------"})
```

--------------------------------

### Get File Name

Source: https://github.com/babashka/fs/blob/master/API.md

Extracts the file or directory name from a given path using Java's File#getName method.

```clojure
(file-name path)
```

--------------------------------

### Get File Creation Time

Source: https://github.com/babashka/fs/blob/master/API.md

Retrieves the creation time of a given path. Supports optional options for controlling link following.

```clojure
(creation-time path)
(creation-time path {:keys [nofollow-links], :as opts})
```

--------------------------------

### Flexible Path Type Handling in Babashka FS

Source: https://github.com/babashka/fs/blob/master/_autodocs/README.md

Shows how babashka.fs functions accept various path types (String, java.io.File, java.nio.file.Path) and how to convert results to a preferred type.

```clojure
(fs/exists? "path.txt")                    ;; String
(fs/exists? (java.io.File. "path.txt"))    ;; File
(fs/exists? (java.nio.file.Paths/get "path.txt" (into-array String [])))  ;; Path
```

```clojure
(str (fs/cwd))      ;; To string
(fs/file (fs/cwd))  ;; To File
(fs/path (fs/cwd))  ;; To Path
```

--------------------------------

### Get Current Working Directory (cwd)

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `cwd` to retrieve the current working directory path. It returns a `java.nio.file.Path` object.

```clojure
(fs/cwd)
```

--------------------------------

### home

Source: https://github.com/babashka/fs/blob/master/API.md

Returns home dir path.

```APIDOC
## home

### Description
Returns the path to the user's home directory.

### Returns
* The path to the home directory.
```

--------------------------------

### Get Creation Time

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieves the creation time of a file. Note that behavior is OS/JDK dependent and may vary across platforms.

```clojure
(creation-time path)
(creation-time path {:keys [nofollow-links]})
```

--------------------------------

### Get File Extension with fs/extension

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieve only the extension of a path using `fs/extension`. This function is useful when you need to isolate the file extension.

```clojure
(extension path)
```

```clojure
(fs/extension "file.txt")
;; => "txt"

(fs/extension "archive.tar.gz")
;; => "gz"
```

--------------------------------

### babashka.fs/create-temp-dir

Source: https://github.com/babashka/fs/blob/master/API.md

Creates a temporary directory. Uses Java's Files#createTempDirectory() method.

```APIDOC
## create-temp-dir

### Description
Returns path to directory created via [Files/createTempDirectory](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Files.html#createTempDirectory(java.nio.file.Path,java.lang.String,java.nio.file.attribute.FileAttribute...)).

### Parameters
#### Path Parameters
- **dir** (optional string | Path) - The directory in which to create the temporary directory. Defaults to the system's temporary directory.
- **prefix** (optional string) - A prefix string to be used in generating the directory name.
- **attrs** (optional Repeatable) - File attributes to set during creation.

### Response
#### Success Response (Path)
- Returns the path to the newly created temporary directory.
```

--------------------------------

### Get Parent Directory: babashka.fs/parent

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `fs/parent` to retrieve the parent directory of a given path. Returns `nil` if the path is the root.

```clojure
(fs/parent "foo/bar/baz.txt")
;; => #object[sun.nio.fs.UnixPath 0x... "foo/bar"]

(fs/parent ".")
;; => #object[sun.nio.fs.UnixPath 0x... ".."]
```

--------------------------------

### List Directories from Multiple Roots - babashka.fs

Source: https://github.com/babashka/fs/blob/master/API.md

Similar to `list-dir`, but accepts multiple root directories and concatenates the results. Accepts a glob string or an accept function.

```clojure
(list-dirs dirs glob-or-accept)
```

--------------------------------

### Compress File with GZIP using babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Compress a single file using `fs/gzip`. You can specify an output directory or a custom output filename. If not specified, the output file will be in the same directory with a `.gz` extension.

```clojure
(fs/gzip "data.csv")
```

```clojure
(fs/gzip "data.csv" {:dir "backups" :out-file "data.csv.gz"})
```

--------------------------------

### Create a temporary file with specific POSIX permissions

Source: https://github.com/babashka/fs/blob/master/API.md

Use this to create a temporary file with custom POSIX file permissions. The file is not automatically deleted.

```clojure
(create-temp-file {:posix-file-permissions "rw-------"})
```

--------------------------------

### babashka.fs/create-file

Source: https://github.com/babashka/fs/blob/master/API.md

Creates an empty file. This function uses Java's Files#createFile() method.

```APIDOC
## create-file

### Description
Creates empty `file` via [Files/createFile](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/file/Files.html#createFile(java.nio.file.Path,java.nio.file.attribute.FileAttribute...)).

### Parameters
#### Path Parameters
- **file** (string | Path) - The file to create.
- **attrs** (optional Repeatable) - File attributes to set during creation.

### Response
#### Success Response (Path)
- Returns the created file path.
```

--------------------------------

### Get File Size with babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `fs/size` to retrieve the size of a file in bytes. This function throws an exception if the path is a directory or does not exist.

```clojure
(fs/size "README.md")
;; => 1024
```

--------------------------------

### Import babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Import the babashka.fs namespace for use in your scripts.

```clojure
(require '[babashka.fs :as fs])
```

--------------------------------

### Get Path Root: babashka.fs/root

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `fs/root` to extract the root component of a path. Returns `nil` for relative paths. The output is platform-dependent.

```clojure
(fs/root "/foo/bar")
;; => #object[sun.nio.fs.UnixPath 0x... "/"]

(fs/root "foo/bar")
;; => nil
```

--------------------------------

### Get and Convert FileTime Attributes

Source: https://github.com/babashka/fs/blob/master/_autodocs/types.md

Retrieves the last modified time of a file and converts it to both an Instant and epoch milliseconds. Requires `babashka.fs` namespace.

```clojure
(require '[babashka.fs :as fs])

(let [ft (fs/last-modified-time "file.txt")
      inst (fs/file-time->instant ft)
      millis (fs/file-time->millis ft)]
  ;; ft is FileTime
  ;; inst is java.time.Instant
  ;; millis is long)
  )
```

--------------------------------

### Expand Home Directory in Path

Source: https://github.com/babashka/fs/blob/master/API.md

Replaces '~' with the user's home directory in a given path. Handles '~' with and without a username.

```clojure
(expand-home path)
```

--------------------------------

### Create Symbolic Link

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Creates a symbolic link. On Windows, requires appropriate permissions. Use "." not "" for current directory.

```clojure
(create-sym-link link target-path)
```

--------------------------------

### File Creation Exceptions

Source: https://github.com/babashka/fs/blob/master/_autodocs/errors.md

Details the exceptions that may be thrown during file and directory creation operations.

```APIDOC
## File Creation

### `fs/create-file path`

- **Description**: Creates a new file at the specified path.
- **Exceptions**: 
  - `FileAlreadyExistsException` if the file already exists.
  - `NoSuchFileException` if the parent directory does not exist.
  - `FileSystemException` for general permission or disk errors.

### `fs/create-dir path`

- **Description**: Creates a new directory at the specified path.
- **Exceptions**: 
  - `FileAlreadyExistsException` if the directory already exists.
  - `NoSuchFileException` if the parent directory does not exist.
  - `FileSystemException` for general permission or disk errors.

### `fs/create-dirs path`

- **Description**: Creates a new directory and any necessary parent directories.
- **Exceptions**: 
  - `FileSystemException` for general permission or disk errors.
  - Does not throw `FileAlreadyExistsException`.

### `fs/create-temp-dir`

- **Description**: Creates a temporary directory.
- **Exceptions**: 
  - `FileSystemException` for disk or permission errors.
  - `FileAlreadyExistsException` is very unlikely.

### `fs/create-temp-file`

- **Description**: Creates a temporary file.
- **Exceptions**: 
  - `FileSystemException` for disk or permission errors.
  - `FileAlreadyExistsException` is very unlikely.
```

--------------------------------

### Extract Path Components in Babashka

Source: https://github.com/babashka/fs/blob/master/API.md

Use `components` to get a sequence of path components, split by the file separator. Useful for analyzing directory structures.

```clojure
(components path)
```

--------------------------------

### Get Path Separator Constant (path-separator)

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use the `path-separator` constant to obtain the OS-specific path separator character as a string (e.g., ':' on Unix, ';' on Windows).

```clojure
fs/path-separator
```

--------------------------------

### Get XDG Config Home

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieves the XDG Base Directory for user configuration files. Appends an optional application name. Defaults to ~/.config.

```clojure
(fs/xdg-config-home)
```

```clojure
(fs/xdg-config-home "myapp")
```

--------------------------------

### Find Executable Paths

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Locate executables in the system's PATH using fs/which (first match) or fs/which-all (all matches). You can specify custom paths for searching. fs/exec-paths returns all directories in the PATH, and fs/split-paths parses a PATH string.

```clojure
(fs/which "java")                 ;; First java in PATH
```

```clojure
(fs/which-all "java")             ;; All java in PATH
```

```clojure
(fs/which "python" {:paths ["/usr/bin" "/usr/local/bin"]})
```

```clojure
(fs/exec-paths)                   ;; All PATH directories
```

```clojure
(fs/split-paths (System/getenv "PATH")) ;; Parse PATH string
```

--------------------------------

### Get Home Directory

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Returns the current user's home directory as a Path object. Optionally accepts a username to retrieve their home directory.

```clojure
(fs/home)
```

```clojure
(fs/home "root")
```

--------------------------------

### Get File Attribute with babashka.fs

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Retrieve the value of a specific file attribute using `fs/get-attribute`. The attribute name is a string, and the `:nofollow-links` option can be used.

```clojure
(get-attribute path attribute)
```

--------------------------------

### Create an empty file

Source: https://github.com/babashka/fs/blob/master/API.md

Creates an empty file. Optionally, POSIX file permissions can be specified.

```clojure
(create-file file)
(create-file file {:keys [:posix-file-permissions]})
```

--------------------------------

### Listing Directories

Source: https://github.com/babashka/fs/blob/master/_autodocs/quick-reference.md

Shows how to list files within a directory using various methods, including glob patterns and regular expressions for filtering.

```APIDOC
## Listing Directories

### Description
Functions for listing and filtering directory contents.

### Functions
- `fs/list-dir`
- `fs/glob`
- `fs/match`

### Examples
```clojure
(fs/list-dir ".")                 ;;
(fs/list-dir "." "*.clj")         ;;
(fs/glob "." "*.clj")             ;;
(fs/glob "." "**/*.clj")          ;;
(fs/match "." "glob:*.clj")       ;;
(fs/match "." "regex:.*\\.clj$")  ;;
```
```

--------------------------------

### Get command search paths

Source: https://github.com/babashka/fs/blob/master/API.md

Retrieve the executable search paths defined in the `PATH` environment variable using `exec-paths`. This is equivalent to splitting the `PATH` variable.

```clojure
(exec-paths)
```

--------------------------------

### expand-home

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Expands the tilde (~) character in a path string to the user's home directory.

```APIDOC
## `expand-home`

### Description
Expands `~` (tilde) to the home directory in a path.

### Parameters
#### Path Parameters
- **path** (string \| File \| Path) - Description: Path with potential tilde

### Returns
`java.nio.file.Path`

### Example
```clojure
(fs/expand-home "~/projects/my-app")
;; => #object[sun.nio.fs.UnixPath 0x... "/home/username/projects/my-app"]

(fs/expand-home "~root/config")
;; => #object[sun.nio.fs.UnixPath 0x... "/root/config"]
```
```

--------------------------------

### List Directory Contents

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Use `list-dir` to get a vector of paths within a specified directory. It supports optional glob patterns or predicate functions for filtering.

```clojure
(list-dir dir)
(list-dir dir glob-or-accept)
```

```clojure
(fs/list-dir ".")
;; => [#object[sun.nio.fs.UnixPath 0x... "file1.clj"]
;;     #object[sun.nio.fs.UnixPath 0x... "file2.clj"] ...]

(fs/list-dir "." "*.clj")
;; => [#object[sun.nio.fs.UnixPath 0x... "file1.clj"] ...]

(fs/list-dir "." #(fs/regular-file? %))
;; => [#object[sun.nio.fs.UnixPath 0x... "file1.clj"] ...]
```

--------------------------------

### Regenerate API documentation

Source: https://github.com/babashka/fs/blob/master/README.md

Command to regenerate the API documentation file (API.md) using the quickdoc tool.

```shell
shell quickdoc
```

--------------------------------

### Get and Convert POSIX File Permissions

Source: https://github.com/babashka/fs/blob/master/_autodocs/types.md

Retrieves POSIX file permissions for a file and converts them to a string representation. The permissions are returned as a set of `PosixFilePermission` enums.

```clojure
(let [perms (fs/posix-file-permissions "file.txt")
      str-perms (fs/posix->str perms)]
  ;; perms is java.util.Set<java.nio.file.attribute.PosixFilePermission>
  ;; str-perms is string like "rw-r--r--"
  )
```

--------------------------------

### starts-with?

Source: https://github.com/babashka/fs/blob/master/_autodocs/api-reference/babashka-fs-api.md

Checks if a given path starts with another path. Returns true if `this-path` begins with `other-path`. It takes two path strings or File/Path objects.

```APIDOC
## starts-with?

### Description
Returns `true` if `this-path` starts with `other-path`.

### Signature
```clojure
(starts-with? this-path other-path)
```

### Parameters
#### Path Parameters
- **this-path** (string | File | Path) - Required - Path to check
- **other-path** (string | File | Path) - Required - Potential prefix

### Returns
- `boolean`
```