_ _
| |___ _ __ ___ | |_ ___
| / __| '_ \ / _ \| __/ _ \
| \__ \ | | | (_) | || __/
|_|___/_| |_|\___/ \__\___|
lswith notes — because sometimes files need context
A modern ls replacement with file notes, emoji icons, git integration, and colored column headers. No nerd fonts required.
# Regular ls
$ ls
Cargo.lock Cargo.toml README.md src target
# lsnote - detailed view with colored headers by default
$ lsnote
Perms L User Group Size Modified Name
-rw-r--r-- 1 user user 26.8K Dec 16 20:10 🦀 Cargo.lock
-rw-r--r-- 1 user user 637B Dec 16 20:10 🦀 Cargo.toml # Rust manifest
-rw-r--r-- 1 user user 5.5K Dec 16 20:10 📖 README.md
drwxr-xr-x 1 user user 96B Dec 16 20:12 ● 📁 src
drwxr-xr-x 1 user user 80B Dec 16 20:12 📁 targetWhat you get:
- Detailed view by default — Permissions, size, dates, and colored headers
- Human-readable sizes —
26.8Kinstead of27464 - Notes — Add context to any file (
# Rust manifestabove) - Icons — Instant visual recognition by file type
- Git status — See what's modified (●), staged (◐), or untracked (?) at a glance
- Tree view — Explore nested directories beautifully
- Copy to clipboard — Share project structure with
-cflag (works on Wayland & X11)
cargo install lsnotebrew tap jofftiquez/tap
brew install lsnotegit clone https://github.com/jofftiquez/lsnote.git
cd lsnote
cargo build --release
cp target/release/lsnote ~/.local/bin/Download from GitHub Releases for:
- macOS (Intel & Apple Silicon)
- Linux (x64 & ARM64)
# Basic listing
lsnote
# Add a note to remember what a file is for
lsnote -s config.yaml "Production database settings - DO NOT COMMIT"
# View your project as a tree
lsnote -tAttach persistent notes to any file or directory:
lsnote -s secrets.env "API keys for staging"
lsnote -s src/legacy/ "Deprecated - migrate to v2 by Q2"Notes appear inline when listing:
📄 secrets.env # API keys for staging
● 📁 src/legacy/ # Deprecated - migrate to v2 by Q2
Manage notes:
lsnote -s FILE "note" # Set note
lsnote -g FILE # Get note
lsnote -r FILE # Remove noteGit status is shown automatically — no extra commands needed:
◐ 🦀 lib.rs # Staged
● 🦀 main.rs # Modified
? 📄 temp.txt # Untracked
📁 vendor/ # Clean
| Symbol | Meaning | Color |
|---|---|---|
| ● | Modified | Red |
| ◐ | Staged | Green |
| ? | Untracked | Yellow |
Directories show the highest-priority status of their contents.
Recognize file types instantly — works in any terminal:
| Type | Icon | Examples |
|---|---|---|
| Rust | 🦀 | .rs, Cargo.toml |
| Python | 🐍 | .py |
| JavaScript | 🟨 | .js, .jsx |
| TypeScript | 🔷 | .ts, .tsx |
| Go | 🐹 | .go |
| Docker | 🐳 | Dockerfile |
| Config | ⚙️ | .toml, .yaml, .json |
| Docs | 📝 | .md |
| Images | 🖼️ | .png, .jpg, .svg |
| And many more... |
Visualize your project structure:
$ lsnote -t src
📁 src
├── 🦀 config.rs
├── 🦀 display.rs
├── 🦀 git.rs
├── 🦀 icons.rs
├── 🦀 main.rs
└── 🦀 notes.rsThe detailed view with permissions, size, dates, and colored headers is shown by default:
$ lsnote
Perms L User Group Size Modified Name
drwxr-xr-x 1 user user 256B Dec 16 09:34 📁 src
-rw-r--r-- 1 user user 3.5K Dec 16 09:34 🦀 main.rs # Entry pointUse -S for a compact short listing:
$ lsnote -S
🦀 Cargo.lock
🦀 Cargo.toml
● 📁 srcUse -B to show raw byte sizes instead of human-readable:
$ lsnote -B
Perms L User Group Size Modified Name
-rw-r--r-- 1 user user 27464 Dec 16 09:34 🦀 Cargo.lockCopy any view to clipboard — perfect for documentation, chat, or AI prompts:
# Copy current listing
$ lsnote -c
Perms L User Group Size Modified Name
-rw-r--r-- 1 user user 3.5K Dec 16 09:34 🦀 main.rs
Copied to clipboard!
# Copy tree view
$ lsnote -ct src
📁 src
├── 🦀 config.rs
└── 🦀 main.rs
Copied to clipboard!
# Copy short format
$ lsnote -cS
🦀 Cargo.lock
🦀 Cargo.toml
Copied to clipboard!Works on Linux (Wayland & X11), macOS, and Windows. No external clipboard tools required.
Combine -c with any other flags (-t, -S, -a, -B, etc.).
lsnote [OPTIONS] [PATH]
Options:
-a, --all Show hidden files
-S, --short Short listing (disable detailed view)
-B, --bytes Show raw byte sizes (disable human-readable)
-t, --tree Tree view
-c, --copy Copy output to clipboard
-s, --set FILE NOTE Set a note
-g, --get FILE Get a note
-r, --remove FILE Remove a note
--no-git Disable git status indicators
--no-icons Disable icons
--no-header Hide column headers
--init-config Generate config file
-h, --help Print help
-V, --version Print versionDefaults: Long format with human-readable sizes and colored headers are enabled by default.
Generate a config file:
lsnote --init-configEdit ~/.lsnote/config:
# Custom icons
icon.directory = 📁
icon.ext.rs = 🦀
icon.ext.py = 🐍
icon.name.Dockerfile = 🐳
# Colors
color.directory = blue
color.git_modified = red
color.git_staged = green
color.git_untracked = yellow
# Git symbols
git.modified = ●
git.staged = ◐
git.untracked = ?Add an alias to your shell config:
Bash (~/.bashrc):
alias ls='lsnote'
alias ll='lsnote' # Already long format by default
alias la='lsnote -a' # Show hidden files
alias lt='lsnote -t' # Tree view
alias lss='lsnote -S' # Short formatZsh (~/.zshrc):
alias ls='lsnote'
alias ll='lsnote'
alias la='lsnote -a'
alias lt='lsnote -t'
alias lss='lsnote -S'Fish (~/.config/fish/config.fish):
alias ls 'lsnote'
alias ll 'lsnote'
alias la 'lsnote -a'
alias lt 'lsnote -t'
alias lss 'lsnote -S'Then reload your shell:
source ~/.bashrc # or ~/.zshrc- Notes:
~/.lsnote/notes - Config:
~/.lsnote/config
MIT
Made with ❤️ by @jofftiquez