[Bug]: Documentation or Config error.

[ben2talk]

Version

• latest

version

1.0.0

What OS are you seeing the problem on?

Linux

installation

pacman -S lsd

term

xterm-kitty
xterm-konsole

ls-colors

No response

What happened?

I copied and pasted the config from the documentation...

# == 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, 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
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: ""

When I start up a terminal and type lsd I get many errors.

### What expected?

```markdown
I expect the default config to have no effect unless I edit and change it.

What else?

Error:

lsd: Configuration file /home/ben/.config/lsd/config.yaml format error, unknown field `literal`, expected one of `classic`, `blocks`, `color`, `date`, `dereference`, `display`, `icons`, `ignore-globs`, `indicators`, `layout`, `recursion`, `size`, `permission`, `sorting`, `no-symlink`, `total-size`, `symlink-arrow`, `hyperlink`, `header` at line 139 column 1.

[zwpaper]

the master branch is for dev

[Flightkick]

@zwpaper although it is clearly stated in the readme, it might be easy to miss. Especially if you're using Ctrl + F to quickly find what you're looking for, skimming through the readme, or when you arrive on the default branch because you landed here through a search result, or navigated to the main page by clicking on the project name at the top (which drops the tag).

Looking at TS, the negative reaction emoji's, similar issues, and the fact that I stumbled upon this myself as well. It seems quite a common pitfall.

Would it be worth it to look for a solution that's clearer for newcomers and doesn't require your attention for these repetitive confusions?

Some suggestions:

• Change the workflow to make use of a develop branch and have master mirror the latest release
• Move docs out the project readme so that you can avoid mixing your development workflow with user experience

In any case, thanks!

[zwpaper]

@Flightkick thanks so much for the suggestions, I also do not want to fix issues like this and we do have ideas for creating a site for lsd, for both themes and docs.

i have created a issue to track #988