file-management

---

name: file-management description: Safe filesystem operations using built-in Unix tools and macOS utilities. Use when listing, searching, reading, organizing, or managing files and directories. Always confirm destructive operations before executing. Triggers on: "list files", "search for files", "find files", "organize files", "batch rename", "move files", "copy files", "delete files", "disk usage", "file search".

File Management

Safe filesystem operations using only pre-installed system tools. No external dependencies, no network access, no install.

Core Principle

Safety first — always confirm destructive operations before executing.

• mv, cp, rm are irreversible without a backup
• Prefer ls -la before touching anything
• For deletions, prefer trash (macOS) or rm as last resort

Built-in Tools Only

Guaranteed on all Unix/macOS

Tool	Purpose	Notes
ls	List files	All Unix ✅
find	Search files	All Unix ✅
grep	Search file contents	All Unix ✅
cat / head / tail	Read files	All Unix ✅
mv	Move / rename	Write ⚠️
cp	Copy files	Write ⚠️
mkdir	Create directories	Write ⚠️
rm	Delete files	Write ⚠️ last resort
stat	File metadata	All Unix ✅
du	Disk usage	All Unix ✅
tar	Archive files	All Unix ✅
xattr	Extended attributes	macOS ✅

macOS-specific (pre-installed)

Tool	Purpose	Notes
trash	Move to Trash (recoverable)	macOS ✅ preferred
pbcopy / pbpaste	Clipboard	macOS ✅
mdls	Spotlight metadata	macOS ✅
mdutil	Spotlight index	macOS ✅

Optional tools (may not be installed)

These are helpful but NOT guaranteed. Check with which <tool> before using:

• tree — directory tree view (install: brew install tree)
• rg (ripgrep) — faster grep (install: brew install ripgrep)
• fd — faster find (install: brew install fd)
• dust — better du (install: brew install dust)
• bat — better cat (install: brew install bat)

Common Patterns

List Directory Contents

# Basic listing
ls -la /path/to/dir

# Human-readable sizes, newest first
ls -lahF /path/to/dir | sort -k5 -rh

# Recursive depth
find /path -maxdepth 2 -type f

# Show hidden files
ls -la /path/to/dir

Search for Files by Name

# Find by name pattern
find /path -name "*.txt" -type f

# Case-insensitive
find /path -iname "readme*"

# Modified in last N days
find /path -name "*.md" -mtime -7

# By size
find /path -size +100M

Search File Contents

# Grep with context
grep -rn "search_term" /path

# Case-insensitive
grep -ri "search_term" /path

# Only filenames with matches
grep -rl "search_term" /path

Disk Usage Analysis

# Total size of directory
du -sh /path/to/dir

# Per-subdirectory breakdown
du -h --max-depth=1 /path | sort -rh

# Find largest files (recursive)
find /path -type f -exec du -h {} + | sort -rh | head -20

Move / Copy / Delete

# Move (rename)
mv source.txt /new/path/

# Copy (recursive for directories)
cp -r /source/dir /dest/dir

# Delete — ALWAYS confirm first
# Preferred on macOS (goes to Trash):
trash /path/to/file.txt
# Or rm as last resort:
rm /path/to/file.txt

Batch Rename (pure bash)

# Rename all .txt to .md in current directory
for f in *.txt; do mv "$f" "${f%.txt}.md"; done

# Replace spaces with underscores
for f in *\ *; do mv "$f" "${f// /_}"; done

Archive & Compress

# Create tar.gz
tar -czvf archive.tar.gz /path

# Extract
tar -xzvf archive.tar.gz

# Create zip
zip -r archive.zip /path

# Extract zip
unzip archive.zip

Permission Model

Read-only operations — safe to execute without asking: ls, find, grep, cat, head, tail, du, stat, file, mdls

Write operations — always confirm before executing: mv, cp, mkdir, trash, rm, zip, tar

For destructive operations:

1. Show what will be affected first
2. Ask for confirmation with exact command
3. Prefer trash over rm on macOS

Anti-Patterns (Never Do)

• ❌ rm -rf / or any recursive delete without confirming
• ❌ chmod -R 777 or permission changes that break security
• ❌ Executing downloaded scripts directly without review
• ❌ Accessing paths outside user's home without asking
• ❌ sudo operations unless explicitly requested

Quick Reference

# Where am I?
pwd

# What's in current directory?
ls -la

# Find all PDFs larger than 10MB
find ~ -name "*.pdf" -size +10M

# How much space is used?
du -sh ~/Library

# Search for TODO in code files
grep -rn --include="*.py" "TODO" ~/code/