### Example Color Configuration

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/configuration.md

Provides a practical example of how to configure colors for file types, permissions, and sizes in your color.yaml file.

```yaml
color:
  file-type:
    file:
      exec-uid: "bright-yellow"
      no-exec-no-uid: "white"
    directory:
      no-uid: "bright-blue"
    symlink:
      default: "bright-cyan"
      broken: "bright-red"
  
  permission:
    read: "green"
    write: "yellow"
    exec: "red"
    no-access: "bright-black"
  
  size:
    large: "red"
    medium: "yellow"
    small: "green"
```

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

### Complete icons.yaml Example

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating name-based, extension-based, and filetype-based icon overrides in a single configuration file.

```yaml
icons:
  name:
    ".git": 
    ".github": 
    ".gitignore": 
    ".travis.yml": 
    ".gitlab-ci.yml": 
    ".cargo": 🦀
    "Cargo.toml": 🦀
    "Gemfile": 
    "Makefile": 
    "package.json": 
    "docker-compose.yml": 
    "Dockerfile": 
    ".env": 
    ".DS_Store": 
    ".Spotlight-V100": 
    ".Trashes": 
    ".vimrc": 
    "config": 
    "README.md": 📘
    "LICENSE": 

  extension:
    "as": 
    "asm": 
    "bas": 
    "bash": 
    "bat": 
    "c": 
    "cc": 
    "clj": 
    "cljs": 
    "cmake": 
    "coffee": 
    "cpp": 
    "cs": 
    "css": 
    "cxx": 
    "d": 
    "dart": 
    "db": 
    "diff": 
    "docx": "󰬴"
    "dwg": 
    "dxf": 
    "edn": 
    "eex": 
    "erl": 
    "ex": 
    "exs": 
    "fish": 
    "fs": 
    "fsi": 
    "fsscript": 
    "fsx": 
    "go": 
    "groovy": 
    "gvy": 
    "gz": 
    "h": 
    "handlebars": 
    "hbs": 
    "hs": 
    "html": 
    "htm": 
    "hxx": 
    "java": 
    "js": 
    "json": 
    "jsx": 
    "jinja": 
    "jinja2": 
    "kt": 
    "kts": 
    "latex": 
    "lc": 
    "less": 
    "ls": 
    "lua": 
    "m": 
    "markdown": 
    "md": 
    "mdx": 
    "mjs": 
    "ml": 
    "mli": 
    "mo": 
    "mocha": 
    "mustache": 
    "nix": 
    "node": 
    "objc": 
    "o": 
    "pas": 
    "passwd": 
    "pdf": 
    "php": 
    "pl": 
    "pm": 
    "png": 
    "pp": 
    "ppt": "󰬴"
    "pptx": "󰬴"
    "ps": 
    "ps1": 
    "psd": 
    "py": 
    "pyc": 
    "pyo": 
    "pyi": 
    "r": 
    "rb": 
    "rd": 
    "rdata": 
    "rdf": 
    "rdoc": 
    "re": 
    "readme": 
    "res": 
    "rlib": 
    "rmd": 
    "rs": 🦀
    "rsx": 
    "rtf": 
    "ru": 
    "rake": 
    "s": 
    "sass": 
    "scala": 
    "scm": 
    "scss": 
    "sh": 
    "sig": 
    "sml": 
    "so": 
    "sql": 
    "sqlite": 
    "sql3": 
    "styl": 
    "swift": 
    "swiftpm": 
    "t": 
    "tex": 
    "textile": 
    "tf": 
    "tfvars": 
    "ts": 
    "tsx": 
    "twig": 
    "txt": 
    "v": 
    "vb": 
    "vbproj": 
    "vbs": 
    "vhdl": 
    "vim": 
    "vue": 
    "wasm": 
    "webmanifest": 
    "webp": 
    "xml": 
    "xul": 
    "yaml": 
    "yml": 
    "zsh": 
    "zip": 

  filetype:
    "dir": 
    "file": 📄
    "pipe": 📩
    "socket": 
    "executable": 
    "symlink-dir": 
    "symlink-file": 
    "device-char": 
    "device-block": 
    "special": 
```

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

### Complete config.yaml Example

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/configuration.md

A comprehensive example of a `config.yaml` file, demonstrating various display, color, icon, file listing, sorting, and recursion options.

```yaml
# Display options
classic: false
display: visible-only
layout: grid
indicators: false
blocks:
  - permission
  - user
  - group
  - size
  - date
  - name

# Color and icons
color:
  when: auto
  theme: default

icons:
  when: auto
  theme: fancy
  separator: " "

# File listing options
date: date
permission: rwx
size: default
no-symlink: false
total-size: false
header: false
literal: false

# Sorting
sorting:
  column: name
  reverse: false
  dir-grouping: none

# Recursion
recursion:
  enabled: false
  depth: null

# Other
ignore-globs:
  - .git
  - __pycache__
hyperlink: never
dereference: false
truncate-owner:
  after: null
  marker: "."
symlink-arrow: " -> "
```

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

### Permissions::from() Example Usage

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Example demonstrating how to create a Permissions struct from file metadata.

```rust
let metadata = path.metadata()?;
let perms = Permissions::from(&metadata);
```

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

### Rust Code Example Structure

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/README.md

Illustrates the standard format for code examples within the documentation, including headings, parameters, and source references.

```rust
code example
```

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

### Grid Format Output Example

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Presents files and directories in a compact grid layout, suitable for maximizing screen space.

```text
colors.rs  config_file.rs  display.rs    flags        git_theme.rs
core.rs    display.rs      flags.rs      git.rs       icon.rs
main.rs    meta            sort.rs       theme.rs     theme
```

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

### Loading Theme Configurations

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Example of how to load ColorTheme and IconTheme configurations from YAML files using `Theme::from_path`. Ensure the YAML files exist and are correctly formatted.

```rust
let color_theme: ColorTheme = Theme::from_path("colors.yaml")?;
let icon_theme: IconTheme = Theme::from_path("icons.yaml")?;
```

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

### Tree Format Output Example

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Shows the directory structure in a tree format, clearly indicating nested directories and files.

```text
.
├── src
│   ├── main.rs
│   └── lib.rs
├── tests
│   └── integration_test.rs
├── Cargo.toml
└── README.md
```

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

### Example Output with Git Status Column

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

This example shows the typical output when lsd is run with both the --long and --git flags, including the added Git status column.

```bash
$ lsd -l --git
Permissions User   Group  Size Date Modified Name    Git
drwxr-xr-x  user   staff  4.0K Dec 25 14:30 .git
drwxr-xr-x  user   staff  4.0K Dec 25 14:30 src          M
-rw-r--r--  user   staff  1.2K Dec 25 14:30 Cargo.toml   M
-rw-r--r--  user   staff   500 Dec 25 14:30 README.md
-rw-r--r--  user   staff   800 Dec 25 13:00 new_file.rs  N
```

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

### Long Format Output Example

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Illustrates the detailed long format output, displaying file permissions, user, group, size, modification date, and name.

```text
Permissions User    Group   Size  Date Modified  Name
drwxr-xr-x  user    staff   4.0K  Dec 25 14:30  src
-rw-r--r--  user    staff   1.2K  Dec 25 14:30  Cargo.toml
lrwxr-xr-x  user    staff    12   Dec 25 14:30  link -> target
```

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

### Example Usage of assemble_sorters

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Demonstrates how the `assemble_sorters` function might be used to obtain a list of sorting functions and their orders based on flags.

```rust
let sorters = assemble_sorters(&flags);
// Might return:
// [(SortOrder::Reverse, time_sort), (SortOrder::Default, name_sort)]
```

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

### Install Latest LSD from Main Branch

Source: https://github.com/lsd-rs/lsd/blob/main/README.md

Install the latest development version of LSD directly from the main branch of its Git repository. This is useful for testing the newest features.

```sh
cargo install --git https://github.com/lsd-rs/lsd.git --branch main
```

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

### SymLink::new() Example

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Shows example states for a SymLink struct. The target field is an Option<PathBuf> and is_broken indicates if the symlink's target does not exist.

```rust
// Points to existing target:
// target: Some(PathBuf::from("/path/to/target"))
// is_broken: false

// Broken symlink:
// target: Some(PathBuf::from("/path/to/missing"))
// is_broken: true
```

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

### Install LSD with Cargo

Source: https://github.com/lsd-rs/lsd/blob/main/README.md

Install LSD using Rust's package manager, Cargo. This is a common method for installing Rust-based tools.

```sh
cargo install lsd
```

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

### Custom Date Format Examples

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/flags-api.md

Illustrates how to use custom format strings with the DateFlag enum for displaying file modification dates in various human-readable formats.

```text
- +%Y-%m-%d → 2024-12-25
- +%d/%m/%Y → 25/12/2024
- +%c → Locale-specific complete date/time
```

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

### Owner::from_metadata() Example

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Illustrates potential values for owner.user and owner.group after calling Owner::from_metadata(). User can be a username or a UID string if the user is not found. Group can be a group name or a GID string if the group is not found.

```rust
// owner.user might be:
// "root"         (username found)
// "1000"         (UID, no user found)

// owner.group might be:
// "wheel"        (group name found)
// "1000"         (GID, no group found)
```

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

### Check LSD Git Support Compilation

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Verify that your LSD installation was compiled with Git support by checking the version information.

```bash
lsd --version    # Should show git support compiled in
```

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

### Include all files, including hidden ones

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Use the `-a` or `--all` flags to show all files, including those starting with a dot (hidden files). On Windows, this also includes system-protected files.

```bash
lsd -a              # Show all files including .hidden
```

```bash
lsd --all           # Same as above
```

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

### Display Help Information

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Shows usage instructions and a list of available command-line flags.

```bash
lsd --help          # Show usage and available flags
```

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

### Use Custom Configuration File

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Specify a custom path for the configuration file instead of using the default.

```bash
lsd --config-file ~/.lsd/custom.yaml
lsd --config-file /etc/lsd/default.yaml
```

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

### Programmatic Entry Point

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/INDEX.md

Shows how to use LSD as a library by programmatically setting up flags, initializing the core, and running it with a specified input path.

```rust
// If lsd were used as a library
let flags = Flags::configure_from(&cli, &config)?;
let core = Core::new(flags);
let exit_code = core.run(vec![PathBuf::from(".")]);
```

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

### Command-Line Entry Point

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/INDEX.md

Illustrates the main function's execution flow for the command-line interface. It parses CLI arguments, loads configuration, sets up flags, initializes the core, and runs the application.

```rust
// main.rs: main()
let cli = Cli::parse_from(wild::args_os());
let config = Config::default() or Config::from_file(path)?;
let flags = Flags::configure_from(&cli, &config)?;
let core = Core::new(flags);
let exit_code = core.run(cli.inputs);
```

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

### Create Meta Instance from Path

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Creates a Meta instance by reading filesystem metadata from a given path. Use `dereference` to control symlink following and `permission_flag` to specify permission representation.

```rust
let meta = Meta::from_path(
    Path::new("file.txt"),
    false,  // Don't follow symlinks
    PermissionFlag::Rwx
)?;
```

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

### Generate Default Configuration File

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/configuration.md

Generates a sample configuration file with all default settings in YAML format. This file can be customized and placed in the appropriate configuration directory.

```bash
lsd --generate-config > config.yaml
```

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

### Core::new()

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/core-api.md

Creates and initializes a new Core instance from the provided Flags. This method sets up TTY detection, color configuration, icon output, hyperlink resolution, sort function assembly, and theme initialization.

```APIDOC
## Core::new()

### Description
Creates and initializes a new Core instance from the provided Flags.

### Signature
```rust
pub fn new(mut flags: Flags) -> Self
```

### Parameters
#### Path Parameters
- **flags** (Flags) - Description: Configuration flags that control behavior of the listing

### Returns
A `Core` instance ready to execute file listing.

### Purpose
Initializes the Core with:
- TTY detection (whether output is connected to a terminal)
- Color output configuration (Windows ANSI support check)
- Icon output configuration
- Hyperlink option resolution
- Sort function assembly
- Theme and color initialization

### Example
```rust
let flags = Flags::configure_from(&cli, &config)?;
let core = Core::new(flags);
let exit_code = core.run(paths);
```
```

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

### Print Error Safely

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/core-api.md

Safely prints error messages to stderr without panicking if the pipe is closed. Prevents panics when stderr closes, for example, when output is piped and the consumer closes.

```rust
#[macro_export]
macro_rules! print_error {
    ($($arg:tt)*) => { /* implementation */ }
}
```

```rust
print_error!("Cannot read file: {}", path);
```

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

### Initialize Core Instance

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/core-api.md

Creates a new Core instance using provided configuration flags. This method handles TTY detection, color and icon configuration, and theme initialization.

```rust
pub fn new(mut flags: Flags) -> Self
```

```rust
let flags = Flags::configure_from(&cli, &config)?;
let core = Core::new(flags);
let exit_code = core.run(paths);
```

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

### Core::run()

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/core-api.md

Executes the file listing operation for the provided paths. This method fetches metadata, applies sorting and filtering, and then formats and displays the output.

```APIDOC
## Core::run()

### Description
Executes the file listing operation for the provided paths.

### Signature
```rust
pub fn run(self, paths: Vec<PathBuf>) -> ExitCode
```

### Parameters
#### Path Parameters
- **paths** (Vec<PathBuf>) - Description: Paths to list (files or directories)

### Returns
`ExitCode` indicating success or failure.

### Purpose
The main execution method that:
1. Fetches file metadata for all requested paths
2. Applies sorting rules
3. Applies filtering rules
4. Formats and displays the output

### Example
```rust
let mut meta_list = /* fetch metadata */;
let exit_code = core.run(vec![PathBuf::from(".")]);
std::process::exit(exit_code as i32);
```
```

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

### Create Colors Instance

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Initializes a Colors instance with a specified theme. Use this to set up colorization for terminal output elements.

```rust
let colors = Colors::new(ThemeOption::Default);
let colored_file = colors.colorize('f', &Elem::File { exec: false, uid: false });
```

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

### Choose Icon Theme

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Select an icon theme using the --icon-theme flag. 'fancy' uses Nerd Font glyphs, while 'unicode' uses more compatible Unicode symbols.

```bash
lsd --icon-theme=fancy    # Nerd Font glyphs (default, visually rich)
lsd --icon-theme=unicode  # Unicode symbols (more compatible)
```

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

### Sorting Pattern Function Signature

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/INDEX.md

Defines the SortFn type alias for sorting functions and provides examples of specific sort functions like name_sort and size_sort. It also shows how to assemble sorters based on flags.

```rust
pub type SortFn = fn(&Meta, &Meta) -> Ordering;

pub fn name_sort(a: &Meta, b: &Meta) -> Ordering { ... }
pub fn size_sort(a: &Meta, b: &Meta) -> Ordering { ... }
// ... more sort functions

pub fn assemble_sorters(flags: &Flags) -> Vec<(SortOrder, SortFn)> { ... }
```

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

### Test Folder Icon Display

Source: https://github.com/lsd-rs/lsd/blob/main/README.md

Run this command in your terminal to verify if your font is correctly set up to display folder icons. If a box or question mark appears, your font setup or terminal rendering may need adjustment.

```sh
echo $'\uf115'
```

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

### Meta::from_path()

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Creates a Meta instance by reading filesystem metadata from a specified path. It allows control over symlink dereferencing and permission representation.

```APIDOC
## Meta::from_path()

### Description
Creates a Meta instance by reading filesystem metadata from a path. It allows control over symlink dereferencing and permission representation.

### Method
`pub fn from_path(
    path: &Path,
    dereference: bool,
    permission_flag: PermissionFlag,
) -> io::Result<Self>`

### Parameters
#### Path Parameters
- **path** (`&Path`) - Required - Filesystem path to read metadata from
- **dereference** (`bool`) - Required - Follow symlinks when reading
- **permission_flag** (`PermissionFlag`) - Required - How to represent permissions

### Returns
`io::Result<Meta>` containing metadata or I/O error

### Behavior
1. Read file metadata via `std::fs::metadata()` or `symlink_metadata()`
2. Create Name from filename
3. Determine FileType
4. Extract Permissions
5. Read Date, Owner, Size, etc.
6. Resolve symlink target if applicable
7. Query git status if in repository

### Example
```rust
let meta = Meta::from_path(
    Path::new("file.txt"),
    false,  // Don't follow symlinks
    PermissionFlag::Rwx
)?;
```
```

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

### Execute File Listing Operation

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/core-api.md

Runs the main file listing process for specified paths. It fetches metadata, applies sorting and filtering, and formats the output.

```rust
pub fn run(self, paths: Vec<PathBuf>) -> ExitCode
```

```rust
let mut meta_list = /* fetch metadata */;
let exit_code = core.run(vec![PathBuf::from(".")]);
std::process::exit(exit_code as i32);
```

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

### Create and Render File Metadata

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Creates file metadata from a given path and renders various components like file type indicator, size, and date for display. Does not follow symlinks.

```rust
// Get file metadata
let meta = Meta::from_path(
    Path::new("example.txt"),
    false,  // Don't follow symlinks
    PermissionFlag::Rwx
)?;

// Metadata now contains:
// - name: "example.txt"
// - path: /full/path/to/example.txt
// - file_type: File { uid: false, exec: false }
// - size: Some(Size { size: 1024 })
// - date: Some(Date { date: ... })
// - owner: Some(Owner { user: "alice", group: "staff" })
// - permissions: Some(PermissionsOrAttributes::Permissions(...))
// - git_status: Some(GitFileStatus::Unmodified)

// Render for display
let indicator = meta.file_type.render(&colors);  // Colored '.'
let size = format!( "{:>5}", meta.size.unwrap());  // "  1.0K"
let date = meta.date.unwrap().render();            // "Dec 25 14:30"
```

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

### Colors::new()

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Creates a new Colors instance with the specified theme, initializing color configurations.

```APIDOC
## Colors::new()

### Description
Creates a new Colors instance with the specified theme.

### Method
`pub fn new(theme: ThemeOption) -> Self`

### Parameters
#### Path Parameters
- **theme** (`ThemeOption`) - Required - Which color theme to use

### Returns
- `Self` - A Colors instance ready to colorize elements

### Purpose
Initializes the theme and loads color configuration files if needed.

### Example
```rust
let colors = Colors::new(ThemeOption::Default);
let colored_file = colors.colorize('f', &Elem::File { exec: false, uid: false });
```
```

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

### Flags::configure_from

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/core-api.md

Constructs a Flags struct from CLI arguments and config file in priority order.

```APIDOC
## Flags::configure_from

### Description
Constructs a Flags struct from CLI arguments and config file in priority order.

### Method
Rust function

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
let flags = Flags::configure_from(&cli, &config).unwrap_or_else(|err| err.exit());
```

### Response
#### Success Response
- **Flags**: The constructed Flags struct.
- **Error**: A clap error if configuration fails.

#### Response Example
```rust
// Success case would return a Flags struct
// Error case would exit with an error message
```

### Behavior
Uses the `Configurable` trait to resolve each flag field. For each field:
1. CLI arguments take precedence
2. Environment variables are checked next
3. Config file values are used if available
4. Defaults are applied as fallback
```

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

### Icons::new()

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Creates a new Icons instance, initializing icon rendering based on terminal capabilities and user preferences.

```APIDOC
## Icons::new()

### Description
Creates a new Icons instance.

### Signature
```rust
pub fn new(
    tty_available: bool,
    when: IconOption,
    theme: IconTheme,
    separator: String,
) -> Self
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **tty_available** (bool) - Required - Whether output is a TTY
- **when** (`IconOption`) - Required - When to display icons
- **theme** (`IconTheme`) - Required - Icon theme to use
- **separator** (String) - Required - String between icon and name

### Request Example
None

### Response
#### Success Response (200)
- **Self** (`Icons`) - An Icons instance configured for the environment

### Response Example
None
```

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

### Generate Default Configuration

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Prints the default configuration file content to standard output, useful for creating a custom configuration file.

```bash
lsd --generate-config > config.yaml
lsd --generate-config | less
```

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

### Theme::from_path

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Loads a theme configuration from a specified YAML file path. It handles path expansion, configuration searching, and file format validation.

```APIDOC
## Theme::from_path()

### Description
Loads a theme from a YAML file path. This function supports loading various theme types by deserializing the YAML content.

### Method Signature
```rust
pub fn from_path<D>(file: &str) -> Result<D, Error>
where
    D: DeserializeOwned + Default,
```

### Parameters
#### Path Parameters
- **file** (`&str`) - Required - File path (absolute or relative to config dir)

### Returns
- `Result<D, Error>` - Returns the deserialized theme type `D` on success, or an `Error` on failure.

### Behavior
1. Expands `~` to the home directory.
2. Searches standard configuration paths if a relative path is provided.
3. Attempts to load files with both `.yaml` and `.yml` extensions.
4. Deserializes the YAML content into the specified theme type `D`.

### Errors
- `Error::InvalidPath`: If the provided file path cannot be resolved.
- `Error::ReadFailed`: If the file at the specified path cannot be read.
- `Error::InvalidFormat`: If the YAML content in the file is malformed.

### Example
```rust
// Assuming ColorTheme is a type that implements DeserializeOwned + Default
let color_theme: ColorTheme = Theme::from_path("colors.yaml")?;
let icon_theme: IconTheme = Theme::from_path("icons.yaml")?;
```
```

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

### Release Profile for Optimized Binary

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/project-overview.md

Configure the release profile for a small, fast binary optimized for distribution. This includes enabling link-time optimization, setting a single codegen unit, and stripping debug symbols.

```toml
[profile.release]
lto = true             # Link-time optimization
codegen-units = 1      # Single codegen unit for optimization
strip = true           # Strip debug symbols
debug = false          # No debug info
```

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

### Sort by File Extension

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Use the -X or --extensionsort flags to sort entries alphabetically by their file extension.

```bash
lsd -X              # Sort by extension
lsd --extensionsort # Same as above
```

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

### Display one entry per line

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Use the `--oneline` flag to list each file or directory on a separate line.

```bash
lsd --oneline       # List one file per line
```

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

### Layout Enum for File Listing

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/flags-api.md

Defines the possible layout formats for displaying file listings. Use Grid for compact multi-column output, Tree for hierarchical views, or OneLine for a simple list.

```Rust
pub enum Layout {
    #[default]
    Grid,      // Multi-column grid format
    Tree,      // Hierarchical tree format
    OneLine,   // Single file per line with metadata
}
```

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

### Ignore Configuration Files

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/configuration.md

Completely bypass all configuration files using the `--ignore-config` flag.

```bash
lsd --ignore-config
```

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

### Format File Permissions

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Control permission display with the --permission flag. Choose between 'rwx' format, 'octal', 'attributes' for Windows, or 'disable' to hide permissions.

```bash
lsd --permission=rwx         # rwxrwxrwx format (Unix default)
lsd --permission=octal       # 0755 format
lsd --permission=attributes  # Windows attributes (Windows default)
lsd --permission=disable     # Don't show permissions
```

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

### Enable Git Support in Build Configuration

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/project-overview.md

This TOML snippet shows how to enable the 'git2' feature for git support in the build configuration. Alternatively, use 'no-git' to disable it and avoid the 'git2' dependency.

```toml
[features]
default = ["git2"]     # Enable git support
no-git = []            # Disable git to avoid git2 dependency
```

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

### Display SELinux Context with lsd

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Use the `-Z` or `--context` flag to display the SELinux security context for files.

```bash
lsd -Z              # Show SELinux context
```

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

### Specify Custom Config File Location

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/configuration.md

Use the `--config-file` flag to point to a custom YAML configuration file.

```bash
lsd --config-file /path/to/custom-config.yaml
```

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

### Combine Tree View with Git Info

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Display a tree view of the project that includes Git information, specifically filtering to show only modified files.

```bash
lsd --tree -l --git | grep M   # Show only modified files in tree
```

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

### Detailed LSD View Options

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Display detailed file information. Use '-l' for long format, '-la' to include hidden files, and '-lh' for human-readable file sizes.

```bash
lsd -l              # Long format with details
lsd -la             # Long format including hidden files
lsd -lh             # Long format with human-readable sizes
```

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

### Build LSD with Git Support

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Builds the LSD project with Git support enabled by default. This includes the git2 dependency.

```bash
cargo build --release
```

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

### LSD Configuration Management

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Manage LSD configuration. Use '--ignore-config' to bypass configuration files, '--config-file' to specify a custom configuration file, or '--generate-config' to create a default configuration file.

```bash
lsd --ignore-config                 # Ignore config files
lsd --config-file custom.yaml       # Use custom config
lsd --generate-config > config.yaml # Create default config file
```

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

### Generate Default Configuration

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/COMPLETION_REPORT.txt

Use the --generate-config flag to create a default YAML configuration file. This is useful for understanding available options and customizing behavior.

```bash
lsd --generate-config > lsd.yaml
```

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

### FileType::new() Constructor

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Constructs a FileType instance from filesystem metadata. Requires different parameters for Unix and Windows systems. Use when determining the type of a filesystem entry.

```rust
pub fn new(
    meta: &Metadata,
    symlink_meta: Option<&Metadata>,
    permissions: &Permissions,  // Unix
    path: &Path,                 // Windows
) -> Self
```

```rust
let metadata = path.metadata()?;
let file_type = FileType::new(&metadata, None, &permissions);
```

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

### Icons Configuration

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/types.md

Defines the configuration for displaying icons. It allows specifying when to show icons, the icon theme, and a separator.

```rust
pub struct Icons {
    pub when: Option<IconOption>,
    pub theme: Option<IconTheme>,
    pub separator: Option<String>,
}
```

```yaml
icons:
  when: auto
  theme: fancy
  separator: " "
```

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

### Basic LSD Directory Listing

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Perform basic file listings. Use 'lsd' for the current directory in a grid layout, 'lsd path/to/dir' for a specific directory, or 'lsd file1 dir1' to list a mix of files and directories.

```bash
lsd                 # Current directory, grid layout
lsd path/to/dir     # List specific directory
lsd file1 dir1      # Mix files and directories
```

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

### Include almost all files (excluding '.' and '..')

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

The `-A` or `--almost-all` flags are similar to `-a` but exclude the current directory (`.`) and parent directory (`..`) entries.

```bash
lsd -A              # Show hidden files except . and ..
```

```bash
lsd --almost-all    # Same as above
```

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

### Configure Default Git Status in Long Format

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Create a configuration file to ensure Git status is always included in the long listing format by default.

```yaml
# config.yaml
blocks:
  - permission
  - user
  - size
  - date
  - git
  - name
```

```bash
lsd -l      # Now shows git status by default
```

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

### Display Version Information

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Prints the current version number of the LSD tool.

```bash
lsd --version       # Show version number
```

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

### Rust Type Annotation Convention

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/README.md

Demonstrates the convention for displaying type annotations in Rust function signatures, including parameter and return types.

```rust
pub fn function(param: Type) -> ReturnType
```

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

### Advanced LSD Formatting

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Customize output appearance with color, icons, columns, and headers. Force colors with '--color=always', disable icons with '--icon=never', specify columns like '--blocks=size,name', and add headers with '--header --total-size'.

```bash
lsd -l --color=always                          # Force colors
lsd -l --icon=never                            # Disable icons
lsd -l --blocks=size,name --permission=octal   # Custom columns
lsd -l --header --total-size                   # Headers and directory totals
```

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

### TTY Detection on Unix

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Demonstrates the use of `libc::isatty()` on stdout's file descriptor for TTY detection on Unix-like systems. This helps in disabling colors when output is piped.

```text
Unix: libc::isatty() check on stdout file descriptor
```

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

### Icons::new() Constructor

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Creates a new Icons instance, configuring icon rendering based on terminal capabilities and user-defined settings for display timing, theme, and separator.

```rust
pub fn new(
    tty_available: bool,
    when: IconOption,
    theme: IconTheme,
    separator: String,
) -> Self
```

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

### Group Directories First

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

The --group-directories-first flag ensures that all directories are listed before any files in the output. This is a shorthand for --group-dirs=first.

```bash
lsd --group-directories-first  # Directories first
```

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

### GitCache::new() Function

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Creates a new `GitCache` by discovering the Git repository at or above the specified path and querying all file statuses. Returns an empty cache if not in a Git repository.

```rust
pub fn new(path: &Path) -> GitCache
```

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

### Ignore All Configuration Files

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Disables the use of any configuration files, relying solely on command-line arguments and defaults.

```bash
lsd --ignore-config     # Skip config files, use defaults
```

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

### LSD Filtering Options

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Exclude specific files or patterns from the listing. Use '-I' followed by a glob pattern to ignore files, such as build artifacts or cache directories. Combine with '-a' to show all files except specific ignored ones.

```bash
lsd -I '*.o' -I '*.a'               # Ignore build artifacts
lsd -I '__pycache__'                # Ignore Python cache
lsd -a -I '.git'                    # All files except .git
```

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

### Enable Git Status Display (CLI)

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Use the --git flag with the long format (-l) to display git status information in the file listing. The short flag -G can also be used.

```bash
lsd -l --git              # Long format with git status
lsd --long -G             # Same using short flag -G
```

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

### Format File Sizes

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Customize file size display using the --size flag. Options include 'default' for human-readable, 'short' for abbreviated, and 'bytes' for exact byte counts.

```bash
lsd --size=default  # Human-readable: 1.5K, 2.3M (default)
lsd --size=short    # Abbreviated: 1K, 2M
lsd --size=bytes    # Exact bytes: 1536, 2411724
```

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

### Icons::get() Method

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Retrieves the appropriate icon for a given file path and type. It checks display conditions, attempts matching by filename, extension, and file type category before returning an icon or None.

```rust
pub fn get(&self, path: &Path, file_type: &FileType) -> Option<String>
```

```rust
if let Some(icon) = icons.get(&path, &file_type) {
    println!("{}{}{}", icon, separator, name);
} else {
    println!("{}", name);
}
```

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

### Enable Git Status Display (Config)

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Git status can be enabled in the configuration file. This setting only applies when the --long format is used.

```yaml
# In config.yaml - this flag only works with --long format
# When --git is not specified, git status is only shown with explicit flag
```

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

### Recursive Listing with LSD

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Recursively list files and directories. Conflicts with the --tree option.

```bash
lsd -R              # List all subdirectories
lsd --recursive     # Same as above
```

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

### Verify Git Repository

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Before troubleshooting Git status issues, verify that you are currently within a Git repository by running `git status`.

```bash
git status
```

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

### Build LSD Without Git Support

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/git-support.md

Builds the LSD project without Git support by using the 'no-git' feature. This reduces binary size and build time.

```bash
cargo build --release --features no-git
```

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

### Display Enum for File Visibility

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/flags-api.md

Controls which files and directories are shown in the listing. Use All or AlmostAll to include hidden files, DirectoryOnly to list directories themselves, or SystemProtected on Windows for specific files.

```Rust
pub enum Display {
    SystemProtected,  // Windows: show system-protected files
    All,              // Show all files including hidden (.)
    AlmostAll,        // Show all except . and ..
    DirectoryOnly,    // Show directories only, not their contents
    #[default]
    VisibleOnly,      // Hide files starting with . (default)
}
```

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

### Color Configuration

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/types.md

Defines the configuration for the color theme. It includes options for when to apply colors and the specific theme to use.

```rust
pub struct Color {
    pub when: Option<ColorOption>,
    pub theme: Option<ThemeOption>,
}
```

```yaml
color:
  when: auto
  theme: default
```

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

### Configuration Pattern Implementation

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/INDEX.md

Implement the Configurable trait for custom options. This pattern defines how options are configured from CLI arguments, configuration files, or environment variables, with a clear priority order.

```rust
pub enum MyOption { ... }

impl Configurable<MyOption> for MyOption {
    fn from_cli(cli: &Cli) -> Option<MyOption> { ... }
    fn from_config(config: &Config) -> Option<MyOption> {
        None
    }
    fn from_environment() -> Option<MyOption> {
        None
    }
}
```

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

### Recursion Configuration

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/types.md

Defines the configuration for recursive directory listing. It includes options to enable recursion and set the depth.

```rust
pub struct Recursion {
    pub enabled: Option<bool>,
    pub depth: Option<usize>,
}
```

```yaml
recursion:
  enabled: false
  depth: 3
```

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

### Directory Structure Visualization

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/README.md

Visual representation of the LSD project's directory structure, showing the relationship between different documentation files and modules.

```text
README.md (you are here)
├── INDEX.md (navigation hub)
├── project-overview.md (big picture)
├── Core API
│   ├── core-api.md
│   ├── flags-api.md
│   └── types.md
├── Implementation APIs
│   ├── metadata-api.md
│   ├── display-api.md
│   └── git-support.md
└── User Guides
    ├── cli-reference.md
    └── configuration.md
```

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

### Tree View Listing with LSD

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Display directory contents in a tree format, which implies recursive listing. Conflicts with the --recursive option.

```bash
lsd --tree          # Show as tree (better than -R for visualization)
```

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

### Theme Struct Definition

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/display-api.md

Defines the top-level theme configuration structure, aggregating color, icon, and git themes.

```rust
pub struct Theme {
    pub color: ColorTheme,
    pub icon: IconTheme,
    pub git_theme: GitThemeSymbols,
}
```

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

### Display Column Headers with lsd

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

Use the `--header` flag to display column headers above the file listings in long format. This improves readability.

```bash
lsd -l --header      # Show column headers above data
```

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

### Show Windows system-protected files

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/cli-reference.md

On Windows, the `--system-protected` flag includes files with the system protection flag set. On other systems, it behaves like `--all`.

```bash
lsd --system-protected  # Show Windows system-protected files
```

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

### Construct Flags from CLI and Config

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/core-api.md

Constructs a Flags struct from CLI arguments and config file in priority order. CLI arguments take precedence, followed by environment variables, config file values, and finally defaults.

```rust
pub fn configure_from(cli: &Cli, config: &Config) -> Result<Self, Error>
```

```rust
let flags = Flags::configure_from(&cli, &config).unwrap_or_else(|err| err.exit());
```

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

### Sorting Configuration

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/types.md

Defines the configuration for sorting files and directories. It allows specifying the sort column, direction, and directory grouping.

```rust
pub struct Sorting {
    pub column: Option<SortColumn>,
    pub reverse: Option<bool>,
    pub dir-grouping: Option<DirGrouping>,
}
```

```yaml
sorting:
  column: name
  reverse: false
  dir-grouping: first
```

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

### ThemeOption Enum

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/flags-api.md

Specifies which color theme to use for file type and metadata coloring. Supports default, custom, and no-color options.

```APIDOC
## ThemeOption Enum

### Description
Specifies which color theme to use for file type and metadata coloring.

### Enum Variants
- **NoColor**: No coloring.
- **Default**: Default theme (uses LS_COLORS if available).
- **NoLscolors**: Don't use LS_COLORS env var.
- **CustomLegacy(String)**: Path to custom YAML theme.
- **Custom**: Use custom theme from config.

### Configuration
`color.theme` in YAML, or specify custom theme file path.
```

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

### Permissions::from() Implementation Signature

Source: https://github.com/lsd-rs/lsd/blob/main/_autodocs/metadata-api.md

Signature for the Permissions::from() method, which extracts file permissions from std::fs::Metadata.

```rust
impl From<&Metadata> for Permissions
```