Troubleshooting Guide for lsf

Solutions to common issues with lsf v5.0.0 (Rust rewrite).

🔍 General Diagnostics

Before troubleshooting, run these diagnostic commands:

# Check if lsf is installed
which lsf

# Check version (should be 5.0.0+)
lsf --version

# Test basic functionality
lsf

# Check for errors
lsf . 2>&1 | head -n 20

🎨 Icons Not Displaying

Symptom

Icons appear as boxes □, question marks ?, or don't show at all.

Causes & Solutions

1. Missing or Incorrect Nerd Font

Check installed fonts:

# Linux
fc-list | grep -i "Nerd Font"

# macOS
system_profiler SPFontsDataType | grep -i "Nerd"

Solution:

• Download from nerdfonts.com
• Extract to ~/.local/share/fonts/ (Linux) or install via Font Book (macOS)
• Refresh cache (Linux): fc-cache -fv
• Crucial: Restart your terminal and set the font to a Nerd Font (e.g., "JetBrainsMono Nerd Font").

2. Icons Explicitly Disabled

Check if --no-icons is active:

• Check your shell aliases: alias | grep ls
• Try running lsf without any flags or aliases: command lsf

🔧 "lsf: command not found"

Symptom

lsf doesn't execute, even though it was installed.

Causes & Solutions

1. Not in PATH (Local Install)

If you installed to ~/.local/bin/ or ~/.cargo/bin/, ensure it's in your $PATH.

Check:

echo $PATH

Solution:
Add to ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"
# or for cargo
export PATH="$HOME/.cargo/bin:$PATH"

2. Shell Cache Not Updated

Solution:

# Clear shell hash table
hash -r   # Bash/Zsh
rehash    # Zsh/Fish

📝 Alias Not Working

Symptom

alias ls='lsf' is set but ls doesn't use lsf.

Causes & Solutions

1. Shell Config Not Sourced

Reload your config: source ~/.bashrc or source ~/.zshrc.

2. Overridden by Oh My Zsh

Oh My Zsh often sets its own ls aliases. Ensure your alias ls='lsf' is at the very bottom of ~/.zshrc, or after the line source $ZSH/oh-my-zsh.sh.

3. Typo in Alias

Ensure the syntax is correct for your shell:

• Bash/Zsh: alias ls='lsf'
• Fish: alias ls lsf or abbr --add ls lsf

⚠️ Permission Errors

Symptom

"Permission denied" during installation.

Causes & Solutions

1. System-wide Installation

If installing to /usr/local/bin, you must use sudo:

sudo cp target/release/lsf /usr/local/bin/

2. Binary Not Executable

Ensure the binary has execution permissions:

chmod +x /path/to/lsf

🌈 Colors Look Wrong

Symptom

Colors are missing, dull, or unreadable.

Causes & Solutions

1. Terminal Color Support

Check if your terminal supports true color:

curl -s https://raw.githubusercontent.com/gnachman/iTerm2/master/tests/24-bit-color.sh | bash

2. Color Mode Forced

Try forcing color output to see if it's an auto-detection issue:

lsf --color=always

💻 Cross-Platform Issues

macOS Specific

Homebrew PATH

If installed via Homebrew or Cargo, ensure /opt/homebrew/bin or ~/.cargo/bin is in your PATH.

Nerd Fonts on macOS

Recommended way to install:

brew tap homebrew/cask-fonts
brew install --cask font-jetbrains-mono-nerd-font

WSL (Windows Subsystem for Linux)

Fonts in WSL

You must install the Nerd Font on the Windows host system, then configure the Windows Terminal (or whatever terminal you use) to use that font.

🆘 Getting Help

If you still have issues:

1. Check existing issues: https://github.com/swadhinbiswas/ls-f/issues
2. Open a new issue with:
   • OS & Version (uname -a)
   • Terminal emulator name
   • lsf --version output
   • A screenshot of the problem (especially for icon/color issues)

📚 Related Documentation

• Installation Guide
• Configuration Guide
• README.md