zr-dir - Directory Listing Tool¶

zr-dir [options] [directory]
```bash

### Options

- `-l`: Long listing format
- `-a`: Show hidden files
- `-h`: Human-readable sizes
- `-t`: Sort by modification time
- `-S`: Sort by size
- `-r`: Reverse sort order
- `-f FORMAT`: Output format (table, json, csv)
- `-p PATTERN`: Filter by pattern
- `-T TYPE`: Filter by file type
- `-d DEPTH`: Recursion depth
- `-s`: Summary only
- `-v`: Verbose output
- `-q`: Quiet mode
- `-h`: Show help

## Examples

### Basic Listing

```bash
# List current directory
zr-dir

# List specific directory
zr-dir ~/Documents

# Long format
zr-dir -l

# Include hidden files
zr-dir -a
```bash

### Filtering and Sorting

```bash
# Filter by pattern
zr-dir -p "*.txt"

# Filter by type
zr-dir -T directory

# Sort by size
zr-dir -S

# Sort by time, reverse
zr-dir -t -r
```bash

### Advanced Usage

```bash
# Recursive listing
zr-dir -d 2

# JSON output
zr-dir -f json

# Summary only
zr-dir -s

# Human-readable with long format
zr-dir -l -h
```bash

## How It Works

### Listing Algorithm

1. **Directory Reading**: Read directory contents
2. **File Analysis**: Gather file metadata
3. **Filtering**: Apply pattern and type filters
4. **Sorting**: Sort by specified criteria
5. **Formatting**: Format output according to options
6. **Display**: Output results

### File Analysis

- **Basic Info**: Name, size, modification time
- **Type Detection**: File type classification
- **Permissions**: Access permissions
- **Ownership**: User and group ownership
- **Extended Attributes**: Additional metadata

### Output Formats

- **Table**: Human-readable tabular format
- **JSON**: Machine-readable structured data
- **CSV**: Spreadsheet-compatible format
- **Tree**: Hierarchical tree view

## Configuration

### Configuration File

```toml
# ~/.config/zr-dir/config.toml
[display]
default_format = "table"
show_hidden = false
human_readable = true
color = true

[sorting]
default_sort = "name"
reverse = false

[filtering]
default_pattern = "*"
default_type = "all"

[output]
max_width = 120
truncate_names = true
show_icons = true

[performance]
cache_metadata = true
parallel_processing = false
```bash

### Environment Variables

```bash
# Display settings
export ZR_DIR_FORMAT="table"
export ZR_DIR_COLOR="true"

# Default behavior
export ZR_DIR_SHOW_HIDDEN="false"
export ZR_DIR_HUMAN_READABLE="true"

# Performance
export ZR_DIR_CACHE="true"
export ZR_DIR_MAX_WIDTH="120"
```bash

## Dependencies

### Required

- **ls/stat**: File information
- **find**: Directory traversal
- **grep**: Pattern matching
- **sort**: Data sorting

### Optional

- **file**: MIME type detection
- **du**: Disk usage information
- **tree**: Tree view display
- **exa/lsd**: Enhanced ls alternatives

## Troubleshooting

### No Files Shown

**Symptom:** Empty or incomplete listing

**Cause:** Permission issues or filtering

**Fix:**

```bash
# Check permissions
ls -la /directory/

# Try with sudo
sudo zr-dir /directory/

# Check filtering
zr-dir -p "*" /directory/

# Disable filters
zr-dir --no-filter /directory/
```bash

### Slow Performance

**Symptom:** Listing takes too long

**Cause:** Large directory or deep recursion

**Fix:**

```bash
# Limit depth
zr-dir -d 1 /large/directory/

# Use summary mode
zr-dir -s /large/directory/

# Disable metadata
export ZR_DIR_CACHE="false"
```bash

### Incorrect File Types

**Symptom:** Wrong file type detection

**Cause:** Missing file command or unusual files

**Fix:**

```bash
# Install file command
sudo apt install file

# Check file manually
file /path/to/file

# Force type detection
zr-dir --force-type /directory/
```bash

### Display Issues

**Symptom:** Formatting problems or garbled output

**Cause:** Terminal width or encoding issues

**Fix:**

```bash
# Check terminal
echo $TERM
tput cols

# Set width manually
export ZR_DIR_MAX_WIDTH="80"

# Disable colors
export ZR_DIR_COLOR="false"
```bash

## Performance

### Listing Times

| Directory Size     | Files | Time | Memory |
| ------------------ | ----- | ---- | ------ |
| Small (<100)       | 50    | 0.1s | 5MB    |
| Medium (100-1000)  | 500   | 0.5s | 15MB   |
| Large (1000-10000) | 5000  | 3s   | 50MB   |

### Optimization Tips

- **Caching**: Enable metadata caching
- **Filtering**: Apply filters early
- **Parallel**: Use parallel processing for large directories
- **Summary**: Use summary mode for overviews

## Integration

### With Shell Navigation

```bash
# Enhanced ls replacement
alias ls='zr-dir'

# Quick directory overview
alias l='zr-dir -l'
alias la='zr-dir -a'
alias ll='zr-dir -l -a'
```bash

### With File Managers

```bash
# Generate file list for processing
zr-dir -f csv > files.csv

# Directory analysis
zr-dir -s -f json > dir-analysis.json

# Find large files
zr-dir -S -T file | head -10
```bash

### With Development Tools

```bash
# Project structure analysis
zr-dir -d 3 -f json > project-structure.json

# Code file inventory
zr-dir -p "*.py" -f csv > python-files.csv

# Asset management
zr-dir -T image -f table > image-assets.txt
```bash

### With Scripts

```bash
# Backup verification
zr-dir /backup | wc -l

# Disk usage analysis
zr-dir -s -f json | jq '.summary.total_size'

# File type distribution
zr-dir -T all -f json | jq '.files[].type' | sort | uniq -c
```bash

## Output Formats

### Table Format (default)

```bash
Permissions  Size  Modified    Name
drwxr-xr-x   4.2K  Jan 01 12:00  documents/
-rw-r--r--   1.5K  Jan 01 11:30  README.md
-rwxr-xr-x   2.1K  Jan 01 11:00  script.sh
lrwxrwxrwx     12  Jan 01 10:45  link -> target
```bash

### JSON Format

```json
{
  "directory": "/home/user",
  "files": [
    {
      "name": "README.md",
      "type": "file",
      "size": 1536,
      "permissions": "rw-r--r--",
      "modified": "2024-01-01T11:30:00Z",
      "owner": "user",
      "group": "user"
    }
  ],
  "summary": {
    "total_files": 4,
    "total_directories": 1,
    "total_size": "8.5K",
    "file_types": {
      "file": 3,
      "directory": 1
    }
  }
}
```bash

### CSV Format

```csv
name,type,size,permissions,modified,owner,group
README.md,file,1536,rw-r--r--,2024-01-01T11:30:00Z,user,user
documents,directory,4096,drwxr-xr-x,2024-01-01T12:00:00Z,user,user
script.sh,file,2150,rwxr-xr-x,2024-01-01T11:00:00Z,user,user
```bash

## Technical Details

### File Type Detection

- **Extension Analysis**: File extension mapping
- **MIME Type Detection**: Content-based typing
- **Executable Detection**: Permission-based classification
- **Symlink Resolution**: Link target analysis

### Metadata Collection

```bash
# Basic file info
stat -c "%a %s %Y %n" "$file"

# Extended attributes
getfattr -d "$file"

# MIME type
file -b --mime-type "$file"
```bash

### Sorting Algorithms

- **Name**: Alphabetical sorting
- **Size**: Numerical size sorting
- **Time**: Modification time sorting
- **Type**: File type grouping
- **Custom**: User-defined sorting

### Filtering System

- **Pattern Matching**: Glob and regex patterns
- **Type Filtering**: File type categories
- **Size Filtering**: Size range filtering
- **Time Filtering**: Modification time filtering

### Performance Optimizations

- **Lazy Loading**: Load metadata on demand
- **Caching**: Cache expensive operations
- **Parallel Processing**: Multi-threaded for large directories
- **Memory Management**: Efficient data structures

## See Also

- **[zr](zr.md)** - Framework rebuild tool
- **[File Management](../../README.md#file-management)** - File management guide