docs: overhaul documentation for v5.0.0 Rust rewrite
swadhinbiswas committed 8 months ago
dac0ffe
1 parent a330027
commit dac0ffe
4 files changed
+201 -570
Showing 4 changed files+201-559
▼CHANGELOG.md
+20-0
| @@ -2,6 +2,24 @@ | ||
2 | 2 | |
3 | 3 | All notable changes to this project will be documented in this file. |
4 | 4 | |
5 | +## [5.0.0] - 2026-02-15 | |
6 | +### Added | |
7 | +- **Complete Rewrite in Rust**: Transitioned from a Bash/Python hybrid to a native Rust implementation for massive performance gains. | |
8 | +- **Tree View**: Added native tree visualization via the `--tree` flag. | |
9 | +- **Git Integration**: Built-in support for displaying git status indicators using the `--git` flag. | |
10 | +- **Zero Dependencies**: The tool is now a single static binary with no runtime dependencies on Bash or Python. | |
11 | +- **Improved Benchmarks**: Competitive with and often faster than GNU `ls` for colorized output. | |
12 | +- **Native Recursive Sorting**: Improved handling of recursive listings and depth control. | |
13 | + | |
14 | +### Changed | |
15 | +- **Performance**: Significant reduction in startup time and listing speed for large directories. | |
16 | +- **Documentation**: Overhauled README, Installation, and Troubleshooting guides to reflect the Rust transition. | |
17 | +- **Installation**: New `make install` and `cargo install` methods added to the preferred workflow. | |
18 | + | |
19 | +### Fixed | |
20 | +- Fixed icon misalignment issues in long listing formats. | |
21 | +- Resolved various shell-specific escaping bugs from the legacy version. | |
22 | + | |
5 | 23 | ## [4.5.1] - 2025-10-17 |
6 | 24 | ### Added |
7 | 25 | - Standalone installer (install-standalone.sh) for convenient pipe-to-bash installation |
| @@ -40,4 +58,6 @@ All notable changes to this project will be documented in this file. | ||
40 | 58 | ### Removed |
41 | 59 | - Deprecated ls-material.sh script |
42 | 60 | |
61 | +[5.0.0]: https://github.com/swadhinbiswas/ls-f/compare/v4.5.1...v5.0.0 | |
62 | +[4.5.1]: https://github.com/swadhinbiswas/ls-f/compare/v4.5.0...v4.5.1 | |
43 | 63 | [4.5.0]: https://github.com/swadhinbiswas/ls-f/releases/tag/v4.5.0 |
44 | 64 | |
▼QUICK_REFERENCE.md
+37-174
| @@ -1,20 +1,17 @@ | ||
1 | -# Quick Reference Guide — ls-f | |
1 | +# Quick Reference Guide — lsf v5.0.0 | |
2 | 2 | |
3 | -A one-page cheat sheet for **ls-f** users and developers. | |
3 | +A one-page cheat sheet for **lsf** (Rust) users and developers. | |
4 | 4 | |
5 | 5 | --- |
6 | 6 | |
7 | -## 🚀 Installation (One Minute) | |
7 | +## 🚀 Installation | |
8 | 8 | |
9 | 9 | ```bash |
10 | -# Pipe-to-bash (downloads both files automatically) | |
11 | -curl -fsSL https://raw.githubusercontent.com/swadhinbiswas/ls-f/main/install-standalone.sh | bash | |
10 | +# Build from source (Rust) | |
11 | +make install | |
12 | 12 | |
13 | -# Or for system-wide install | |
14 | -curl -fsSL https://raw.githubusercontent.com/swadhinbiswas/ls-f/main/install-standalone.sh | bash -s system | |
15 | - | |
16 | -# Or clone and install locally | |
17 | -git clone https://github.com/swadhinbiswas/ls-f.git && cd ls-f && ./install.sh --user | |
13 | +# Or via cargo | |
14 | +cargo install --path . | |
18 | 15 | ``` |
19 | 16 | |
20 | 17 | --- |
| @@ -23,19 +20,15 @@ git clone https://github.com/swadhinbiswas/ls-f.git && cd ls-f && ./install.sh - | ||
23 | 20 | |
24 | 21 | ```bash |
25 | 22 | lsf # List files with icons (grid view) |
26 | -lsf -a # List all files (including hidden) | |
27 | -lsf -A # Hidden files without . and .. | |
28 | -lsf -b # Show names with C-style escapes | |
29 | -lsf -x # List entries by lines (horizontal) | |
30 | -lsf -T 4 # Align columns with tab width of 4 | |
31 | -lsf -Z # Display SELinux/AppArmor security context | |
32 | -lsf --zero # Output entries delimited by NUL (for scripting) | |
33 | -lsf -l # Long format | |
34 | -lsf -la # Long + all files | |
35 | -lsf -R # Recursive listing | |
23 | +lsf -la # Long format (all files) | |
24 | +lsf --tree # Recursive tree view | |
25 | +lsf --git # Show git status | |
26 | +lsf -R # Recursive listing (classic) | |
36 | 27 | lsf -t # Sort by time |
37 | 28 | lsf -S # Sort by size |
38 | 29 | lsf -X # Sort by extension |
30 | +lsf -v # Natural version sort | |
31 | +lsf --depth 2 # Limit tree depth | |
39 | 32 | lsf --help # Show help |
40 | 33 | lsf --version # Show version |
41 | 34 | lsf --no-icons # Disable icons |
| @@ -43,58 +36,29 @@ lsf --no-icons # Disable icons | ||
43 | 36 | |
44 | 37 | --- |
45 | 38 | |
46 | -## 🎨 Customize Icons | |
47 | - | |
48 | -Edit `~/.config/lsf/lsf.conf`: | |
39 | +## ⚙️ Sorting Options | |
49 | 40 | |
50 | -```bash | |
51 | -# Python icon | |
52 | -ICONS[".py"]="" | |
53 | -COLORS[".py"]="92" # Bright green | |
54 | - | |
55 | -# Directory icon | |
56 | -ICONS["dir"]="" | |
57 | -COLORS["dir"]="94" # Bright blue | |
58 | - | |
59 | -# JSON icon | |
60 | -ICONS[".json"]="" | |
61 | -COLORS[".json"]="36" # Cyan | |
62 | -``` | |
63 | - | |
64 | -**Color Codes:** 30-37 (normal), 90-97 (bright), 38;5;N (256-color), 38;2;R;G;B (RGB) | |
65 | - | |
66 | - | |
67 | -## ⚙️ Installation Options | |
68 | - | |
69 | -| Option | Purpose | | |
70 | -|--------|---------| | |
71 | -| `--user` | Install to `~/.local/bin` | | |
72 | -| `--system` | Install to `/usr/local/bin` (requires sudo) | | |
73 | -| `--replace-ls` | Replace system `ls` (creates backup) | | |
74 | -| `--force` | Overwrite without prompting | | |
75 | -| `--no-font-check` | Skip Nerd Font detection | | |
76 | -| `--help` | Show all options | | |
41 | +| Flag | Sort By | | |
42 | +|------|---------| | |
43 | +| `-t` | Time (newest first) | | |
44 | +| `-S` | Size (largest first) | | |
45 | +| `-X` | Extension (alphabetical) | | |
46 | +| `-v` | Version (natural sort) | | |
47 | +| `-r` | Reverse sort order | | |
48 | +| `-U` | Unsorted (directory order) | | |
77 | 49 | |
78 | 50 | --- |
79 | 51 | |
80 | 52 | ## 🔗 Set Up Alias |
81 | 53 | |
82 | -### Bash (~/.bashrc) | |
83 | -```bash | |
84 | -alias ls='lsf' | |
85 | -source ~/.bashrc | |
86 | -``` | |
87 | - | |
88 | -### Zsh (~/.zshrc) | |
54 | +### Bash / Zsh | |
89 | 55 | ```bash |
90 | 56 | alias ls='lsf' |
91 | -source ~/.zshrc | |
92 | 57 | ``` |
93 | 58 | |
94 | -### Fish (~/.config/fish/config.fish) | |
59 | +### Fish | |
95 | 60 | ```fish |
96 | -alias ls='lsf' | |
61 | +alias ls lsf | |
97 | 62 | ``` |
98 | 63 | |
99 | 64 | --- |
| @@ -103,140 +67,31 @@ alias ls='lsf' | ||
103 | 67 | |
104 | 68 | | Problem | Solution | |
105 | 69 | |---------|----------| |
106 | -| Icons show as boxes | Install Nerd Fonts from nerdfonts.com | | |
107 | -| `lsf: command not found` | Add `~/.local/bin` to PATH | | |
108 | -| Alias not working | Reload shell: `source ~/.bashrc` | | |
109 | -| Permission denied | Use `sudo ./install.sh --system` | | |
110 | -| Python not found | Install Python 3: `apt install python3` | | |
70 | +| Icons show as boxes | Install a [Nerd Font](https://www.nerdfonts.com/) | | |
71 | +| `lsf: command not found` | Add `/usr/local/bin` to PATH | | |
72 | +| Alias not working | Reload shell config: `source ~/.bashrc` | | |
73 | +| No colors | Use `lsf --color=always` | | |
111 | 74 | |
112 | 75 | --- |
113 | 76 | |
114 | 77 | ## 📚 Documentation |
115 | 78 | |
116 | -- **Website:** Open `index.html` | |
117 | 79 | - **Installation:** See `docs/INSTALLATION.md` |
118 | -- **Configuration:** See `docs/CONFIGURATION.md` | |
119 | 80 | - **Troubleshooting:** See `docs/TROUBLESHOOTING.md` |
81 | +- **Benchmarks:** See `BENCHMARKS.md` | |
120 | 82 | - **Overview:** See `README.md` |
121 | 83 | |
122 | 84 | --- |
123 | 85 | |
124 | -## 🎯 Common Use Cases | |
125 | - | |
126 | -### Replace system ls | |
127 | -```bash | |
128 | -sudo ./install.sh --system --replace-ls | |
129 | -alias ls='lsf' # Add to ~/.bashrc or ~/.zshrc | |
130 | -``` | |
131 | - | |
132 | -### Install for current user only | |
133 | -```bash | |
134 | -./install.sh --user | |
135 | -export PATH="$HOME/.local/bin:$PATH" # Add to ~/.bashrc | |
136 | -``` | |
137 | - | |
138 | -### Customize all Python files purple | |
139 | -```bash | |
140 | -# Edit ~/.config/lsf/lsf.conf | |
141 | -ICONS[".py"]="" | |
142 | -COLORS[".py"]="35" # Magenta/Purple | |
143 | -``` | |
144 | - | |
145 | -### Use without icons | |
146 | -```bash | |
147 | -lsf --no-icons | |
148 | -# OR disable Nerd Fonts permanently: | |
149 | -./install.sh --no-font-check | |
150 | -``` | |
151 | - | |
152 | - | |
153 | -## 🛠️ Uninstall | |
154 | - | |
155 | -```bash | |
156 | -# Remove files | |
157 | -rm ~/.local/bin/lsf ~/.local/bin/column.py # User | |
158 | -sudo rm /usr/local/bin/lsf /usr/local/bin/column.py # System | |
159 | - | |
160 | -# Remove config | |
161 | -rm -rf ~/.config/lsf/ | |
162 | - | |
163 | -# Remove alias | |
164 | -# Edit ~/.bashrc or ~/.zshrc and remove: alias ls='lsf' | |
165 | -``` | |
166 | - | |
167 | - | |
168 | -## 📊 File Type Categories Supported | |
169 | - | |
170 | -- **Programming:** `.py`, `.js`, `.ts`, `.rs`, `.go`, `.c`, `.java`, etc. | |
171 | -- **Config:** `.json`, `.yaml`, `.toml`, `.xml`, `.env`, `.conf` | |
172 | -- **Docs:** `.md`, `.txt`, `.pdf`, `.doc` | |
173 | -- **Media:** `.png`, `.jpg`, `.mp4`, `.mp3`, `.zip` | |
174 | -- **Special:** `package.json`, `Dockerfile`, `LICENSE`, `.gitignore` | |
175 | -- **And 100+ more!** | |
176 | - | |
177 | - | |
178 | -## 🚨 Diagnostics | |
179 | - | |
180 | -```bash | |
181 | -# Check installation | |
182 | -which lsf | |
183 | -lsf --version | |
184 | - | |
185 | -# Check fonts | |
186 | -fc-list | grep -i "Nerd Font" | |
187 | - | |
188 | -# Check bash version | |
189 | -echo $BASH_VERSION | |
190 | - | |
191 | -# Check Python | |
192 | -python3 --version | |
193 | - | |
194 | -# Check PATH | |
195 | -echo $PATH | tr ':' '\n' | |
196 | - | |
197 | -# Check alias | |
198 | -alias | grep ls | |
199 | -``` | |
200 | - | |
201 | - | |
202 | 86 | ## 🌐 Platform Support |
203 | 87 | |
204 | -| OS | Support | Install | | |
205 | -|----|---------|---------| | |
206 | -| Linux (Ubuntu, Fedora, Arch, etc.) | ✅ Full | `./install.sh` | | |
207 | -| macOS | ✅ Full | `./install.sh` (needs Bash 4+) | | |
208 | -| WSL (Windows) | ✅ Full | `./install.sh` | | |
209 | -| BSD/Unix | ✅ Full | `./install.sh` | | |
210 | - | |
211 | - | |
212 | -## 💡 Tips | |
213 | - | |
214 | -1. **Keep it simple:** Start with default icons, customize later | |
215 | -2. **Use colors consistently:** Pick a color scheme and stick with it | |
216 | -3. **Test changes:** Run `lsf` after editing config | |
217 | -4. **Back up config:** Save working configurations | |
218 | -5. **Check permissions:** Use `ls -la ~/.local/bin/` to verify | |
219 | - | |
220 | - | |
221 | -## 🆘 Getting Help | |
222 | - | |
223 | -- **GitHub Issues:** https://github.com/swadhinbiswas/ls-f/issues | |
224 | -- **Documentation:** See `docs/` folder | |
225 | -- **FAQ:** Open `index.html` in browser | |
226 | - | |
227 | - | |
228 | -## 📄 License | |
229 | - | |
230 | -MIT License — Use freely, modify, and redistribute. | |
88 | +| OS | Support | | |
89 | +|----|---------| | |
90 | +| Linux | ✅ Full | | |
91 | +| macOS | ✅ Full | | |
92 | +| WSL (Windows) | ✅ Full | | |
93 | +| BSD | ✅ Full | | |
231 | 94 | |
232 | 95 | --- |
233 | 96 | |
234 | -**Last updated: October 16, 2025** | |
235 | -For latest docs, visit: https://github.com/swadhinbiswas/ls-f | |
97 | +**Created by [swadhinbiswas](https://github.com/swadhinbiswas)** | |
236 | 98 | |
▼README.md
+87-39
| @@ -1,63 +1,111 @@ | ||
1 | -# ls-f | |
1 | +# 📂 ls-f | |
2 | 2 | |
3 | -A simple wrapper for `ls` that adds icons. It works just like the `ls` you already know, but looks better. | |
3 | +[](https://github.com/swadhinbiswas/ls-f/releases) | |
4 | +[](LICENSE) | |
5 | + | |
6 | +**ls-f** is a modern, blazing-fast `ls` replacement. Originally a bash wrapper, it has been completely rewritten in **Rust (v5.0.0)** to provide superior performance, a native tree view, and zero runtime dependencies. | |
4 | 7 | |
5 | 8 |  |
6 | 9 | |
7 | -## Why use this? | |
8 | -- **Familiar:** It uses your system's `ls` under the hood. All your favorite flags (`-la`, `-R`, `-h`) just work. | |
9 | -- **Icons:** Automatically adds Nerd Font icons based on file extensions. | |
10 | -- **Simple:** No complex configuration needed. It's just a bash script and a tiny python helper. | |
10 | +--- | |
11 | + | |
12 | +## ✨ Key Features | |
13 | + | |
14 | +- 🚀 **Performance:** Native Rust implementation, matching GNU `ls` speed even with icons and colors. | |
15 | +- 🎨 **Nerd Font Icons:** Rich set of icons for hundreds of file types and extensions. | |
16 | +- 🌳 **Tree View:** Recursive tree visualization built-in via `--tree`. | |
17 | +- 🌿 **Git Integration:** View file git status (staged, modified, etc.) with `--git`. | |
18 | +- 🌈 **ANSI Colors:** Intelligent colorization for file types, permissions, and metadata. | |
19 | +- ⚙️ **GNU Compatibility:** Supports standard flags: `-l`, `-a`, `-R`, `-h`, `-t`, `-S`, `-v`, and more. | |
20 | +- 📦 **Zero Dependencies:** Single static binary—no Bash or Python required for the Rust version. | |
21 | + | |
22 | +--- | |
23 | + | |
24 | +## 📊 Benchmarks (v5.0.0) | |
25 | + | |
26 | +`lsf` is optimized for speed. Benchmarked against GNU `ls` (coreutils 9.1) with `--color=always`. | |
11 | 27 | |
12 | -## Prerequisites | |
13 | -- **A Nerd Font:** You need a font that supports icons (like FiraCode Nerd Font, JetBrainsMono, etc.) set in your terminal. | |
14 | -- **Python 3:** Used for the pretty grid layout. | |
28 | +| Scenario | GNU ls | lsf | Winner | | |
29 | +|---|---|---|---| | |
30 | +| Small dir (grid) | 0.75 ms | **0.65 ms** | 🏆 lsf | | |
31 | +| Large dir (7.3k files) | **10.2 ms** | 12.9 ms | 🏆 GNU ls | | |
32 | +| Long format (large dir) | 18.4 ms | **18.3 ms** | 🏆 lsf | | |
33 | +| Tree View (recursive) | N/A | **17.2 ms** | 🏆 lsf | | |
15 | 34 | |
16 | -## Installation | |
35 | +> *Icons add ~0% measurable overhead to lsf. See [BENCHMARKS.md](BENCHMARKS.md) for details.* | |
17 | 36 | |
18 | -The easiest way is to use the one-liner: | |
37 | +--- | |
38 | + | |
39 | +## 🚀 Installation | |
40 | + | |
41 | +### Prerequisites | |
42 | +- A **[Nerd Font](https://www.nerdfonts.com/)** must be set in your terminal for icons to render. | |
43 | + | |
44 | +### 1. Build from Source (Rust - Recommended) | |
45 | +The Rust version (v5.0.0) provides the best performance and features. | |
46 | +```bash | |
47 | +git clone https://github.com/swadhinbiswas/ls-f.git | |
48 | +cd ls-f | |
49 | +make install # Installs to /usr/local/bin | |
50 | +``` | |
51 | +*Or via cargo:* `cargo install --path .` | |
19 | 52 | |
53 | +### 2. Quick Install (Legacy Bash) | |
54 | +If you don't have Rust installed, you can use the legacy bash wrapper (v1.x). | |
20 | 55 | ```bash |
21 | 56 | curl -fsSL https://raw.githubusercontent.com/swadhinbiswas/ls-f/main/install-standalone.sh | bash |
22 | 57 | ``` |
23 | 58 | |
24 | -This will download `lsf` and its helper to your machine and make them ready to use. | |
59 | +--- | |
25 | 60 | |
26 | -### Manual Install | |
27 | -If you prefer doing it yourself: | |
28 | -1. Clone the repo: `git clone https://github.com/swadhinbiswas/ls-f.git` | |
29 | -2. Enter the folder: `cd ls-f` | |
30 | -3. Run the install script: `./install.sh --user` | |
61 | +## 📖 Usage | |
31 | 62 | |
32 | -## Setting up the Alias | |
33 | -To make `ls` show icons automatically, add an alias to your shell config file. | |
63 | +Simply use `lsf` where you would use `ls`. | |
34 | 64 | |
35 | -**For Bash (`~/.bashrc`):** | |
36 | 65 | ```bash |
37 | -echo "alias ls='lsf'" >> ~/.bashrc | |
38 | -source ~/.bashrc | |
66 | +lsf # Grid view with icons | |
67 | +lsf -la # Long format, hidden files | |
68 | +lsf --tree # Recursive tree view | |
69 | +lsf --git # Show git status indicators | |
70 | +lsf --depth 2 # Limit tree/recursive depth | |
39 | 71 | ``` |
40 | 72 | |
41 | -**For Zsh (`~/.zshrc`):** | |
73 | +### Setting up the Alias | |
74 | +Add this to your shell profile (`.bashrc`, `.zshrc`, or `.config/fish/config.fish`): | |
42 | 75 | ```bash |
43 | -echo "alias ls='lsf'" >> ~/.zshrc | |
44 | -source ~/.zshrc | |
76 | +alias ls='lsf' | |
45 | 77 | ``` |
46 | 78 | |
47 | -**For Fish (`~/.config/fish/config.fish`):** | |
48 | -```bash | |
49 | -echo "alias ls='lsf'" >> ~/.config/fish/config.fish | |
50 | -``` | |
79 | +--- | |
80 | + | |
81 | +## 🔧 Troubleshooting | |
82 | + | |
83 | +- **Icons look like boxes?** You need a [Nerd Font](https://www.nerdfonts.com/). Check terminal font settings. | |
84 | +- **Command not found?** Ensure `/usr/local/bin` or `~/.local/bin` is in your `$PATH`. | |
85 | +- **Colors missing?** Ensure your terminal supports ANSI colors. Try `lsf --color=always`. | |
86 | + | |
87 | +*Detailed guides:* | |
88 | +- [Installation Guide](docs/INSTALLATION.md) | |
89 | +- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) | |
90 | +- [Configuration (Legacy)](docs/CONFIGURATION.md) | |
91 | + | |
92 | +--- | |
93 | + | |
94 | +## 🤝 Contributing | |
95 | + | |
96 | +Contributions are welcome! | |
97 | +1. Fork the repo. | |
98 | +2. Create your branch (`git checkout -b feature/AmazingFeature`). | |
99 | +3. Commit your changes (`git commit -m 'Add AmazingFeature'`). | |
100 | +4. Push to the branch (`git push origin feature/AmazingFeature`). | |
101 | +5. Open a Pull Request. | |
102 | + | |
103 | +--- | |
104 | + | |
105 | +## 📄 License | |
51 | 106 | |
52 | -## Usage | |
53 | -Just use it like `ls`: | |
54 | -- `ls` (shows icons in a grid) | |
55 | -- `ls -la` (long format with icons) | |
56 | -- `ls -R` (recursive with icons) | |
57 | -- `ls --no-icons` (if you want the plain old boring output) | |
107 | +Distributed under the MIT License. See `LICENSE` for details. | |
58 | 108 | |
59 | -## Customizing Icons | |
60 | -If you want to change an icon, you can edit the `ICONS` mapping inside the `lsf` script or create a config at `~/.config/lsf`. | |
109 | +--- | |
61 | 110 | |
62 | -## License | |
63 | -MIT | |
111 | +**Created by [swadhinbiswas](https://github.com/swadhinbiswas)** | |
64 | 112 | |
▼docs/TROUBLESHOOTING.md
+57-346
| @@ -1,6 +1,6 @@ | ||
1 | -# Troubleshooting Guide for ls-f | |
1 | +# Troubleshooting Guide for lsf | |
2 | 2 | |
3 | -Solutions to common issues and problems with **ls-f**. | |
3 | +Solutions to common issues with **lsf v5.0.0** (Rust rewrite). | |
4 | 4 | |
5 | 5 | --- |
6 | 6 | |
| @@ -12,14 +12,14 @@ Before troubleshooting, run these diagnostic commands: | ||
12 | 12 | # Check if lsf is installed |
13 | 13 | which lsf |
14 | 14 | |
15 | -# Check version | |
15 | +# Check version (should be 5.0.0+) | |
16 | 16 | lsf --version |
17 | 17 | |
18 | 18 | # Test basic functionality |
19 | 19 | lsf |
20 | 20 | |
21 | 21 | # Check for errors |
22 | -lsf -a 2>&1 | head -20 | |
22 | +lsf . 2>&1 | head -n 20 | |
23 | 23 | ``` |
24 | 24 | |
25 | 25 | --- |
| @@ -35,117 +35,58 @@ Icons appear as boxes `□`, question marks `?`, or don't show at all. | ||
35 | 35 | |
36 | 36 | **Check installed fonts:** |
37 | 37 | ```bash |
38 | +# Linux | |
38 | 39 | fc-list | grep -i "Nerd Font" |
39 | -``` | |
40 | 40 | |
41 | -**Expected output:** | |
42 | -``` | |
43 | -/usr/share/fonts/...: Nerd Font Mono:... | |
41 | +# macOS | |
42 | +system_profiler SPFontsDataType | grep -i "Nerd" | |
44 | 43 | ``` |
45 | 44 | |
46 | 45 | **Solution:** |
47 | 46 | - Download from [nerdfonts.com](https://www.nerdfonts.com/) |
48 | -- Extract to `~/.local/share/fonts/` | |
49 | -- Refresh cache: `fc-cache -fv` | |
50 | -- Restart terminal and set font to Nerd Font | |
51 | - | |
52 | -#### 2. Terminal Font Not Set to Nerd Font | |
47 | +- Extract to `~/.local/share/fonts/` (Linux) or install via Font Book (macOS) | |
48 | +- Refresh cache (Linux): `fc-cache -fv` | |
49 | +- **Crucial:** Restart your terminal and set the font to a Nerd Font (e.g., "JetBrainsMono Nerd Font"). | |
53 | 50 | |
54 | -**Solution:** | |
55 | -1. Open terminal settings | |
56 | -2. Find "Font" or "Text" settings | |
57 | -3. Select a Nerd Font (e.g., "FiraCode Nerd Font", "JetBrains Mono Nerd Font") | |
58 | -4. Apply and restart terminal | |
59 | - | |
60 | -#### 3. Icons Disabled (Bash < 4) | |
61 | - | |
62 | -**Check Bash version:** | |
63 | -```bash | |
64 | -echo $BASH_VERSION | |
65 | -``` | |
66 | - | |
67 | -**Expected:** Version 4 or higher. | |
68 | - | |
69 | -**If lower:** | |
70 | -- Install Bash 4+ | |
71 | -- Use `lsf --no-icons` for now | |
72 | -- Or use `--user` installer flag | |
73 | - | |
74 | -**Solution:** | |
75 | -```bash | |
76 | -# Install newer Bash (Ubuntu/Debian) | |
77 | -sudo apt-get install bash | |
78 | - | |
79 | -# Or use Zsh instead | |
80 | -sudo apt-get install zsh | |
81 | -``` | |
82 | - | |
83 | -#### 4. Icons Explicitly Disabled | |
51 | +#### 2. Icons Explicitly Disabled | |
84 | 52 | |
85 | 53 | **Check if `--no-icons` is active:** |
86 | -```bash | |
87 | -# Test without flags | |
88 | -lsf | |
89 | - | |
90 | -# Test with icons forced | |
91 | -lsf --help # check for --no-icons option | |
92 | -``` | |
93 | - | |
94 | -**Solution:** | |
95 | -- Remove `--no-icons` from alias if set | |
96 | -- Verify `.bashrc` or `.zshrc` doesn't have disabling flag | |
54 | +- Check your shell aliases: `alias | grep ls` | |
55 | +- Try running `lsf` without any flags or aliases: `command lsf` | |
97 | 56 | |
98 | 57 | --- |
99 | 58 | |
100 | -## 🔧 "Command Not Found" or "lsf: command not found" | |
59 | +## 🔧 "lsf: command not found" | |
101 | 60 | |
102 | 61 | ### Symptom |
103 | 62 | `lsf` doesn't execute, even though it was installed. |
104 | 63 | |
105 | 64 | ### Causes & Solutions |
106 | 65 | |
107 | -#### 1. Not in PATH (User Install) | |
66 | +#### 1. Not in PATH (Local Install) | |
67 | + | |
68 | +If you installed to `~/.local/bin/` or `~/.cargo/bin/`, ensure it's in your `$PATH`. | |
108 | 69 | |
109 | 70 | **Check:** |
110 | 71 | ```bash |
111 | 72 | echo $PATH |
112 | -which lsf | |
113 | 73 | ``` |
114 | 74 | |
115 | 75 | **Solution:** |
116 | 76 | Add to `~/.bashrc` or `~/.zshrc`: |
117 | 77 | ```bash |
118 | 78 | export PATH="$HOME/.local/bin:$PATH" |
79 | +# or for cargo | |
80 | +export PATH="$HOME/.cargo/bin:$PATH" | |
119 | 81 | ``` |
120 | 82 | |
121 | -Then reload: | |
122 | -```bash | |
123 | -source ~/.bashrc | |
124 | -exec $SHELL | |
125 | -``` | |
126 | - | |
127 | -#### 2. Installation Directory Not in PATH (System Install) | |
128 | - | |
129 | -**Check:** | |
130 | -```bash | |
131 | -ls -la /usr/local/bin/lsf | |
132 | -``` | |
133 | - | |
134 | -**If not found:** | |
135 | -```bash | |
136 | -# Reinstall | |
137 | -sudo ./install.sh --system --force | |
138 | -``` | |
139 | - | |
140 | -#### 3. Shell Cache Not Updated | |
83 | +#### 2. Shell Cache Not Updated | |
141 | 84 | |
142 | 85 | **Solution:** |
143 | 86 | ```bash |
144 | 87 | # Clear shell hash table |
145 | -hash -r | |
146 | - | |
147 | -# Reload shell | |
148 | -exec $SHELL | |
88 | +hash -r # Bash/Zsh | |
89 | +rehash # Zsh/Fish | |
149 | 90 | ``` |
150 | 91 | |
151 | 92 | --- |
| @@ -158,240 +99,56 @@ exec $SHELL | ||
158 | 99 | ### Causes & Solutions |
159 | 100 | |
160 | 101 | #### 1. Shell Config Not Sourced |
102 | +Reload your config: `source ~/.bashrc` or `source ~/.zshrc`. | |
161 | 103 | |
162 | -**Check if alias is set:** | |
163 | -```bash | |
164 | -alias | grep ls | |
165 | -``` | |
166 | - | |
167 | -**If empty:** | |
168 | -```bash | |
169 | -# Reload shell config | |
170 | -source ~/.bashrc | |
171 | -# OR | |
172 | -source ~/.zshrc | |
173 | -``` | |
174 | - | |
175 | -#### 2. Typo in Alias | |
104 | +#### 2. Overridden by Oh My Zsh | |
105 | +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`. | |
176 | 106 | |
177 | -**Check:** | |
178 | -```bash | |
179 | -alias | grep lsf | |
180 | -``` | |
181 | - | |
182 | -**Common typos:** | |
183 | -- `alias ls=lsf` (missing quotes) | |
184 | -- `alias ls 'lsf'` (wrong quote type for Bash) | |
185 | -- Extra spaces: `alias ls = 'lsf'` | |
186 | - | |
187 | -**Fix:** | |
188 | -```bash | |
189 | -# Correct syntax | |
190 | -alias ls='lsf' | |
191 | -``` | |
192 | - | |
193 | -#### 3. Alias Overridden Later | |
194 | - | |
195 | -**Check if something is overriding the alias:** | |
196 | -```bash | |
197 | -# Search for later alias definitions | |
198 | -grep -n "alias ls" ~/.bashrc ~/.zshrc 2>/dev/null | |
199 | -``` | |
200 | - | |
201 | -**Solution:** Remove duplicate or conflicting alias. | |
202 | - | |
203 | -#### 4. Interactive vs Non-Interactive Shell | |
204 | - | |
205 | -**For non-interactive shells (scripts):** | |
206 | - | |
207 | -Add to `~/.bashrc` (not `~/.bash_profile`): | |
208 | -```bash | |
209 | -alias ls='lsf' | |
210 | -``` | |
211 | - | |
212 | -Or use `~/.bash_aliases`: | |
213 | -```bash | |
214 | -# ~/.bash_aliases | |
215 | -alias ls='lsf' | |
216 | - | |
217 | -# In ~/.bashrc: | |
218 | -if [ -f ~/.bash_aliases ]; then | |
219 | - source ~/.bash_aliases | |
220 | -fi | |
221 | -``` | |
107 | +#### 3. Typo in Alias | |
108 | +Ensure the syntax is correct for your shell: | |
109 | +- Bash/Zsh: `alias ls='lsf'` | |
110 | +- Fish: `alias ls lsf` or `abbr --add ls lsf` | |
222 | 111 | |
223 | 112 | --- |
224 | 113 | |
225 | 114 | ## ⚠️ Permission Errors |
226 | 115 | |
227 | 116 | ### Symptom |
228 | -"Permission denied" or "Cannot write to directory" during installation. | |
117 | +"Permission denied" during installation. | |
229 | 118 | |
230 | 119 | ### Causes & Solutions |
231 | 120 | |
232 | -#### 1. Insufficient Permissions (System Install) | |
233 | - | |
234 | -**Error:** | |
235 | -``` | |
236 | -Error: You don't have write permissions for /usr/local/bin | |
237 | -``` | |
238 | - | |
239 | -**Solution:** | |
121 | +#### 1. System-wide Installation | |
122 | +If installing to `/usr/local/bin`, you must use `sudo`: | |
240 | 123 | ```bash |
241 | -# Use sudo for system install | |
242 | -sudo ./install.sh --system | |
124 | +sudo cp target/release/lsf /usr/local/bin/ | |
243 | 125 | ``` |
244 | 126 | |
245 | -#### 2. File Already Exists (Permission Issue) | |
246 | - | |
247 | -**Error:** | |
248 | -``` | |
249 | -cp: cannot create regular file: Permission denied | |
250 | -``` | |
251 | - | |
252 | -**Solution:** | |
127 | +#### 2. Binary Not Executable | |
128 | +Ensure the binary has execution permissions: | |
253 | 129 | ```bash |
254 | -# Force overwrite with sudo | |
255 | -sudo ./install.sh --system --force | |
256 | - | |
257 | -# OR remove existing file | |
258 | -sudo rm /usr/local/bin/lsf | |
259 | -./install.sh --system | |
260 | -``` | |
261 | - | |
262 | -#### 3. Cannot Create Config Directory | |
263 | - | |
264 | -**Error:** | |
265 | -``` | |
266 | -mkdir: cannot create directory: Permission denied | |
267 | -``` | |
268 | - | |
269 | -**Solution:** | |
270 | -```bash | |
271 | -# Create manually | |
272 | -mkdir -p ~/.config/lsf | |
273 | -chmod 755 ~/.config/lsf | |
274 | - | |
275 | -# Then reinstall | |
276 | -./install.sh --user | |
130 | +chmod +x /path/to/lsf | |
277 | 131 | ``` |
278 | 132 | |
279 | 133 | --- |
280 | 134 | |
281 | -## 🐍 Python or column.py Issues | |
135 | +## 🌈 Colors Look Wrong | |
282 | 136 | |
283 | 137 | ### Symptom |
284 | -Errors about `column.py` or Python not found. | |
138 | +Colors are missing, dull, or unreadable. | |
285 | 139 | |
286 | 140 | ### Causes & Solutions |
287 | 141 | |
288 | -#### 1. Python Not Installed | |
289 | - | |
290 | -**Check:** | |
291 | -```bash | |
292 | -which python3 | |
293 | -python3 --version | |
294 | -``` | |
295 | - | |
296 | -**Solution (Ubuntu/Debian):** | |
297 | -```bash | |
298 | -sudo apt-get install python3 | |
299 | -``` | |
300 | - | |
301 | -**Solution (Fedora/RHEL):** | |
302 | -```bash | |
303 | -sudo dnf install python3 | |
304 | -``` | |
305 | - | |
306 | -**Solution (macOS):** | |
307 | -```bash | |
308 | -brew install python3 | |
309 | -``` | |
310 | - | |
311 | -#### 2. column.py Not Installed | |
312 | - | |
313 | -**Check:** | |
314 | -```bash | |
315 | -ls -la ~/.local/bin/column.py | |
316 | -# OR | |
317 | -ls -la /usr/local/bin/column.py | |
318 | -``` | |
319 | - | |
320 | -**If missing:** | |
321 | -```bash | |
322 | -# Reinstall with column.py | |
323 | -cd ~/path/to/ls-f | |
324 | -./install.sh --force | |
325 | -``` | |
326 | - | |
327 | -#### 3. Python 2 vs Python 3 | |
328 | - | |
329 | -**Check default Python:** | |
142 | +#### 1. Terminal Color Support | |
143 | +Check if your terminal supports true color: | |
330 | 144 | ```bash |
331 | -python --version # Might be Python 2 | |
332 | -python3 --version # Should be Python 3.x | |
145 | +curl -s https://raw.githubusercontent.com/gnachman/iTerm2/master/tests/24-bit-color.sh | bash | |
333 | 146 | ``` |
334 | 147 | |
335 | -**Solution:** | |
336 | -Ensure `column.py` has correct shebang: | |
148 | +#### 2. Color Mode Forced | |
149 | +Try forcing color output to see if it's an auto-detection issue: | |
337 | 150 | ```bash |
338 | -head -1 ~/.local/bin/column.py | |
339 | -# Should output: #!/usr/bin/env python3 | |
340 | -``` | |
341 | - | |
342 | - | |
343 | -## 🎯 File Listing Issues | |
344 | - | |
345 | -### Symptom | |
346 | -`lsf` shows no files, wrong files, or unusual output. | |
347 | - | |
348 | -### Causes & Solutions | |
349 | - | |
350 | -#### 1. Wrong Directory | |
351 | - | |
352 | -**Check:** | |
353 | -```bash | |
354 | -pwd | |
355 | -lsf | |
356 | -``` | |
357 | - | |
358 | -**Solution:** | |
359 | -```bash | |
360 | -# List current directory explicitly | |
361 | -lsf . | |
362 | - | |
363 | -# Or specify path | |
364 | -lsf /path/to/directory | |
365 | -``` | |
366 | - | |
367 | -#### 2. Permission Denied on Files | |
368 | - | |
369 | -**Error:** | |
370 | -``` | |
371 | -lsf: command not found | |
372 | -``` | |
373 | - | |
374 | -**Solution:** | |
375 | -```bash | |
376 | -# Use absolute path | |
377 | -/usr/local/bin/lsf | |
378 | - | |
379 | -# OR check PATH | |
380 | -echo $PATH | tr ':' '\n' | |
381 | -``` | |
382 | - | |
383 | -#### 3. Hidden Files Not Showing | |
384 | - | |
385 | -**Note:** By default, hidden files are not shown (standard `ls` behavior). | |
386 | - | |
387 | -**Solution:** | |
388 | -```bash | |
389 | -# Show hidden files | |
390 | -lsf -a | |
391 | - | |
392 | -# OR use with alias | |
393 | -ls -a | |
151 | +lsf --color=always | |
394 | 152 | ``` |
395 | 153 | |
396 | 154 | --- |
| @@ -400,57 +157,20 @@ ls -a | ||
400 | 157 | |
401 | 158 | ### macOS Specific |
402 | 159 | |
403 | -#### 1. Bash Version Too Old | |
404 | - | |
405 | -**Check:** | |
406 | -```bash | |
407 | -bash --version | |
408 | -``` | |
160 | +#### Homebrew PATH | |
161 | +If installed via Homebrew or Cargo, ensure `/opt/homebrew/bin` or `~/.cargo/bin` is in your PATH. | |
409 | 162 | |
410 | -**Solution:** | |
163 | +#### Nerd Fonts on macOS | |
164 | +Recommended way to install: | |
411 | 165 | ```bash |
412 | -# Install newer Bash | |
413 | -brew install bash | |
414 | - | |
415 | -# Set as default shell | |
416 | -chsh -s /usr/local/bin/bash | |
417 | -``` | |
418 | - | |
419 | -#### 2. Nerd Fonts on macOS | |
420 | - | |
421 | -**Solution:** | |
422 | -```bash | |
423 | -# Install via Homebrew | |
424 | 166 | brew tap homebrew/cask-fonts |
425 | -brew install font-fira-code-nerd-font | |
167 | +brew install --cask font-jetbrains-mono-nerd-font | |
426 | 168 | ``` |
427 | 169 | |
428 | 170 | ### WSL (Windows Subsystem for Linux) |
429 | 171 | |
430 | -#### 1. Fonts in WSL | |
431 | - | |
432 | -**Solution:** | |
433 | -- Install Nerd Fonts on Windows (host) | |
434 | -- Configure Windows Terminal to use the font | |
435 | -- WSL will inherit terminal settings | |
436 | - | |
437 | - | |
438 | -## 🐛 Debug Mode | |
439 | - | |
440 | -Enable detailed output to diagnose issues: | |
441 | - | |
442 | -```bash | |
443 | -# Run with bash debug flag | |
444 | -bash -x /usr/local/bin/lsf -a 2>&1 | head -50 | |
445 | - | |
446 | -# Check for errors | |
447 | -lsf -a 2>&1 | |
448 | - | |
449 | -# Verify config is loaded | |
450 | -echo $CONFIG_DIR | |
451 | -cat ~/.config/lsf/lsf.conf | |
452 | -``` | |
172 | +#### Fonts in WSL | |
173 | +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. | |
453 | 174 | |
454 | 175 | --- |
455 | 176 | |
| @@ -458,20 +178,12 @@ cat ~/.config/lsf/lsf.conf | ||
458 | 178 | |
459 | 179 | If you still have issues: |
460 | 180 | |
461 | -1. **Check existing issues:** https://github.com/swadhin-biswas/ls-f/issues | |
462 | -2. **Create new issue with:** | |
463 | - - Your OS and version (`uname -a`) | |
464 | - - Shell and version (`echo $SHELL $BASH_VERSION`) | |
465 | - - Python version (`python3 --version`) | |
466 | - - Error message (full output) | |
467 | - - Steps to reproduce | |
468 | -3. **Include diagnostic output:** | |
469 | - ```bash | |
470 | - which lsf | |
471 | - lsf --version | |
472 | - echo $PATH | |
473 | - alias | grep ls | |
474 | - ``` | |
181 | +1. **Check existing issues:** [https://github.com/swadhinbiswas/ls-f/issues](https://github.com/swadhinbiswas/ls-f/issues) | |
182 | +2. **Open a new issue** with: | |
183 | + - OS & Version (`uname -a`) | |
184 | + - Terminal emulator name | |
185 | + - `lsf --version` output | |
186 | + - A screenshot of the problem (especially for icon/color issues) | |
475 | 187 | |
476 | 188 | --- |
477 | 189 | |
| @@ -480,7 +192,3 @@ If you still have issues: | ||
480 | 192 | - [Installation Guide](INSTALLATION.md) |
481 | 193 | - [Configuration Guide](CONFIGURATION.md) |
482 | 194 | - [README.md](../README.md) |
483 | - | |
484 | - | |
485 | -**Happy listing! If you encounter issues, we're here to help.** 🚀 | |
486 | 195 | |