📝 overhaul documentation and add sample config files (#1175)

bvdbasch · web-flow · commit 3f9443639295 · 2025-12-09T10:32:45.000+08:00
diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE
@@ -6,5 +6,8 @@
 
 - [ ] Use `cargo fmt`
 - [ ] Add necessary tests
-- [ ] Update default config/theme in README (if applicable)
+- [ ] Update README (if applicable)
+- [ ] Update config sample file in `doc/samples` (if applicable)
+- [ ] Update icon sample file in `doc/samples` (if applicable)
+- [ ] Update color sample file in `doc/samples` (if applicable)
 - [ ] Update man page at lsd/doc/lsd.md (if applicable)
diff --git a/README.md b/README.md
diff --git a/doc/colors.md b/doc/colors.md
@@ -0,0 +1,50 @@
+# Color reference
+> [!TIP]
+> Checkout [trapd00r/LS_COLORS](https://github.com/trapd00r/LS_COLORS) and [sharkdp/vivid](https://github.com/sharkdp/vivid) for help in theming using `LS_COLORS`.
+
+You can customize filetype colors using `LS_COLORS` and other colors using the theme.
+
+## Default colors
+### Users and groups
+| Color                                                                | Hex code  | RGB array         | Used for |
+| :------------------------------------------------------------------- | :-------- | :---------------- | :------- |
+| <img valign='middle' alt='very pale yellow' src='./img/ffffd7.svg'/> | `#ffffd7` | `[255, 255, 215]` | User     |
+| <img valign='middle' alt='grayish yellow' src='./img/d7d7af.svg'/>   | `#d7d7af` | `[215, 215, 175]` | Group    |
+
+### Permissions
+| Color                                                                             | Hex code  | RGB array         | Used for                          |
+| :-------------------------------------------------------------------------------- | :-------- | :---------------- | :-------------------------------- |
+| <img valign='middle' alt='strong lime green' src='./img/00d700.svg'/>             | `#00d700` | `[0, 215, 0]`     | Read permission                   |
+| <img valign='middle' alt='very light green' src='./img/d7ff87.svg'/>              | `#d7ff87` | `[215, 255, 135]` | Write permission                  |
+| <img valign='middle' alt='dark red' src='./img/af0000.svg'/>                      | `#af0000` | `[175, 0, 1]`     | Execute permission                |
+| <img valign='middle' alt='pure (or mostly pure) magenta' src='./img/ff00ff.svg'/> | `#ff00ff` | `[255, 0, 255]`   | Execute permission with stickybit |
+| <img valign='middle' alt='moderate pink' src='./img/d75f87.svg'/>                 | `#d75f87` | `[215, 95, 135]`  | No Access                         |
+
+### File Types
+> [!Note]
+> These change based on your configured terminal color scheme
+
+| Color                                                                           | Hex code  | RGB array         | Used for                                |
+| :------------------------------------------------------------------------------ | :-------- | :---------------- | :-------------------------------------- |
+| <img valign='middle' alt='pure (or mostly pure) blue.' src='./img/0087ff.svg'/> | `#0087ff` | `[0, 135, 255]`   | Directory                               |
+| <img valign='middle' alt='strong lime green' src='./img/00d700.svg'/>           | `#00d700` | `[0, 215, 0]`     | Executable file                         |
+| <img valign='middle' alt='white' src='./img/ffffff.svg'/>                       | `#ffffff` | `[255, 255, 255]` | Non-executable file                     |
+| <img valign='middle' alt='dark red' src='./img/af0000.svg'/>                    | `#af0000` | `[175, 0, 1]`     | Broken symlink                          |
+| <img valign='middle' alt='strong cyan' src='./img/00d7d7.svg'/>                 | `#00d7d7` | `[0, 215, 215]`   | Pipe/Symlink/Blockdevice/Socket/Special |
+| <img valign='middle' alt='strong orange' src='./img/d78700.svg'/>               | `#d78700` | `[215, 135, 0]`   | CharDevice                              |
+
+
+### Dates
+| Color                                                                        | Hex code  | RGB array       | Used for             |
+| :--------------------------------------------------------------------------- | :-------- | :-------------- | :------------------- |
+| <img valign='middle' alt='strong lime green' src='./img/00d700.svg'/>        | `#00d700` | `[0, 215, 0]`.  | Within the last hour |
+| <img valign='middle' alt='strong cyan - lime green' src='./img/00d787.svg'/> | `#00d787` | `[215, 135, 1]` | Within the last day  |
+| <img valign='middle' alt='dark cyan' src='./img/00af87.svg'/>                | `#00af87` | `[175, 135, 1]` | Older                |
+
+### File Sizes
+| Color                                                                 | Hex code  | RGB array         | Used for    |
+| :-------------------------------------------------------------------- | :-------- | :---------------- | :---------- |
+| <img valign='middle' alt='pale yellow' src='./img/ffffaf.svg'/>       | `#ffffaf` | `[255, 255, 175]` | Small file  |
+| <img valign='middle' alt='very light orange' src='./img/ffaf87.svg'/> | `#ffaf87` | `[215, 135, 1]`   | Medium file |
+| <img valign='middle' alt='strong orange' src='./img/d78700.svg'/>     | `#d78700` | `[215, 135, 0]`   | Large file  |
+| <img valign='middle' alt='white' src='./img/ffffff.svg'/>             | `#ffffff` | `[255, 255, 255]` | Non file    |
diff --git a/doc/img/0087ff.svg b/doc/img/0087ff.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#0087ff' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/00af87.svg b/doc/img/00af87.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#00af87' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/00d700.svg b/doc/img/00d700.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#00d700' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/00d787.svg b/doc/img/00d787.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#00d787' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/00d7d7.svg b/doc/img/00d7d7.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#00d7d7' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/af0000.svg b/doc/img/af0000.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#af0000' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/d75f87.svg b/doc/img/d75f87.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#d75f87' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/d78700.svg b/doc/img/d78700.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#d78700' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/d7d7af.svg b/doc/img/d7d7af.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#d7d7af' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/d7ff87.svg b/doc/img/d7ff87.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#d7ff87' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/ff00ff.svg b/doc/img/ff00ff.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#ff00ff' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/ffaf87.svg b/doc/img/ffaf87.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#ffaf87' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/ffffaf.svg b/doc/img/ffffaf.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#ffffaf' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/ffffd7.svg b/doc/img/ffffd7.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#ffffd7' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/img/ffffff.svg b/doc/img/ffffff.svg
@@ -0,0 +1 @@
+<svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='20' height='22' viewBox='0 0 20 22'><rect fill='#ffffff' x='0' y='0' width='20' height='20' rx='4'/></svg>
diff --git a/doc/samples/colors-sample.yaml b/doc/samples/colors-sample.yaml
@@ -0,0 +1,39 @@
+---
+user: 230                       # Default = 230
+group: 187                      # Default = 187
+permission:
+  read: dark_green              # Default = dark_green
+  write: dark_yellow            # Default = dark_yellow
+  exec: dark_red                # Default = dark_red
+  exec-sticky: 5                # Default = 5
+  no-access: 245                # Default = 245
+  octal: 6                      # Default = 6
+  acl: dark_cyan                # Default = dark_cyan
+  context: cyan                 # Default = cyan
+date:
+  hour-old: 40                  # Default = 40
+  day-old: 42                   # Default = 42
+  older: 36                     # Default = 36
+size:
+  none: 245                     # Default = 245
+  small: 229                    # Default = 229
+  medium: 216                   # Default = 216
+  large: 172                    # Default = 172
+inode:
+  valid: 13                     # Default = 13
+  invalid: 245                  # Default = 245
+links:
+  valid: 13                     # Default = 13
+  invalid: 245                  # Default = 245
+tree-edge: 245                  # Default = 245
+git-status:
+  default: 245                  # Default = 245
+  unmodified: 245               # Default = 245
+  ignored: 245                  # Default = 245
+  new-in-index: dark_green      # Default = dark_green
+  new-in-workdir: dark_green    # Default = dark_green
+  typechange: dark_yellow       # Default = dark_yellow
+  deleted: dark_red             # Default = dark_red
+  renamed: dark_green           # Default = dark_green
+  modified: dark_yellow         # Default = dark_yellow
+  conflicted: dark_red          # Default = dark_red
diff --git a/doc/samples/config-sample.yaml b/doc/samples/config-sample.yaml
@@ -0,0 +1,149 @@
+---
+# == Classic ==
+# This is a shorthand to override some of the options to be backwards compatible
+# with `ls`. It affects the "color"->"when", "sorting"->"dir-grouping", "date"
+# and "icons"->"when" options.
+# Possible values: false, true
+classic: false
+
+# == Blocks ==
+# This specifies the columns and their order when using the long and the tree
+# layout.
+# Possible values: permission, user, group, context, size, date, name, inode, links, git
+blocks:
+  - permission
+  - user
+  - group
+  - size
+  - date
+  - name
+
+# == Color ==
+# This has various color options. (Will be expanded in the future.)
+color:
+  # When to colorize the output.
+  # When "classic" is set, this is set to "never".
+  # Possible values: never, auto, always
+  when: auto
+  # How to colorize the output.
+  # When "classic" is set, this is set to "no-color".
+  # Possible values: default, custom
+  # When "custom" is set, lsd will look in the config directory for `colors.yaml`.
+  theme: default
+
+# == Date ==
+# This specifies the date format for the date column. The freeform format
+# accepts a strftime like string.
+# When "classic" is set, this is set to "date".
+# Possible values: date, locale, relative, '+<date_format>'
+# `date_format` will be a `strftime` formatted value. e.g. `date: '+%d %b %y %X'` will give you a date like this: 17 Jun 21 20:14:55
+date: date
+
+# == Dereference ==
+# Whether to dereference symbolic links.
+# Possible values: false, true
+dereference: false
+
+# == Display ==
+# What items to display. Do not specify this for the default behavior.
+# Possible values: all, almost-all, directory-only
+# display: all
+
+# == Icons ==
+icons:
+  # When to use icons.
+  # When "classic" is set, this is set to "never".
+  # Possible values: always, auto, never
+  when: auto
+  # Which icon theme to use.
+  # Possible values: fancy, unicode
+  theme: fancy
+  # Separator between icon and the name
+  # Default to 1 space
+  separator: " "
+
+# == Ignore Globs ==
+# A list of globs to ignore when listing.
+# ignore-globs:
+#   - .git
+
+# == Indicators ==
+# Whether to add indicator characters to certain listed files.
+# Possible values: false, true
+indicators: false
+
+# == Layout ==
+# Which layout to use. "oneline" might be a bit confusing here and should be
+# called "one-per-line". It might be changed in the future.
+# Possible values: grid, tree, oneline
+layout: grid
+
+# == Recursion ==
+recursion:
+  # Whether to enable recursion.
+  # Possible values: false, true
+  enabled: false
+  # How deep the recursion should go. This has to be a positive integer. Leave
+  # it unspecified for (virtually) infinite.
+  # depth: 3
+
+# == Size ==
+# Specifies the format of the size column.
+# Possible values: default, short, bytes
+size: default
+
+# == Permission ==
+# Specify the format of the permission column
+# Possible value: rwx, octal, attributes (windows only), disable
+# permission: rwx
+
+# == Sorting ==
+sorting:
+  # Specify what to sort by.
+  # Possible values: extension, name, time, size, version
+  column: name
+  # Whether to reverse the sorting.
+  # Possible values: false, true
+  reverse: false
+  # Whether to group directories together and where.
+  # When "classic" is set, this is set to "none".
+  # Possible values: first, last, none
+  dir-grouping: none
+
+# == No Symlink ==
+# Whether to omit showing symlink targets
+# Possible values: false, true
+no-symlink: false
+
+# == Total size ==
+# Whether to display the total size of directories.
+# Possible values: false, true
+total-size: false
+
+# == Hyperlink ==
+# Attach hyperlink to filenames
+# Possible values: always, auto, never
+hyperlink: never
+
+# == Symlink arrow ==
+# Specifies how the symlink arrow display, chars in both ascii and utf8
+symlink-arrow: ⇒
+
+# == Header ==
+# Whether to display block headers.
+# Possible values: false, true
+header: false
+
+# == Literal ==
+# Whether to show quotes on filenames.
+# Possible values: false, true
+literal: false
+
+# == Truncate owner ==
+# How to truncate the username and group names for a file if they exceed a certain
+# number of characters.
+truncate-owner:
+  # Number of characters to keep. By default, no truncation is done (empty value).
+  after:
+  # String to be appended to a name if truncated.
+  marker: ""
diff --git a/doc/samples/icons-sample.yaml b/doc/samples/icons-sample.yaml
