Lib.rs

 _                 _
| |___ _ __   ___ | |_ ___
| / __| '_ \ / _ \| __/ _ \
| \__ \ | | | (_) | ||  __/
|_|___/_| |_|\___/ \__\___|

ls with 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.

Why lsnote?

# 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   📁 target

What you get:

• Detailed view by default — Permissions, size, dates, and colored headers
• Human-readable sizes — 26.8K instead of 27464
• Notes — Add context to any file (# Rust manifest above)
• 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 -c flag (works on Wayland & X11)

Installation

Cargo (recommended)

cargo install lsnote

Homebrew

brew tap jofftiquez/tap
brew install lsnote

From source

git clone https://github.com/jofftiquez/lsnote.git
cd lsnote
cargo build --release
cp target/release/lsnote ~/.local/bin/

Pre-built binaries

Download from GitHub Releases for:

• macOS (Intel & Apple Silicon)
• Linux (x64 & ARM64)

Quick Start

# 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 -t

Features

File Notes

Attach 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 note

Git Integration

Git status is shown automatically — no extra commands needed:

◐ 🦀 lib.rs          # Staged
● 🦀 main.rs         # Modified
? 📄 temp.txt        # Untracked
  📁 vendor/         # Clean

Directories show the highest-priority status of their contents.

Emoji Icons

Recognize file types instantly — works in any terminal:

Tree View

Visualize your project structure:

$ lsnote -t src
📁 src
├── 🦀 config.rs
├── 🦀 display.rs
├── 🦀 git.rs
├── 🦀 icons.rs
├── 🦀 main.rs
└── 🦀 notes.rs

Long Format (Default)

The 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 point

Use -S for a compact short listing:

$ lsnote -S
  🦀 Cargo.lock
  🦀 Cargo.toml
● 📁 src

Use -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.lock

Copy to Clipboard

Copy 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.).

Usage

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 version

Defaults: Long format with human-readable sizes and colored headers are enabled by default.

Configuration

Generate a config file:

lsnote --init-config

Edit ~/.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 = ?

Tips

Replace ls with lsnote

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 format

Zsh (~/.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

Data Storage

• Notes: ~/.lsnote/notes
• Config: ~/.lsnote/config

License

MIT

Made with ❤️ by @jofftiquez