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/