zd - Diff-Based Configuration Editor¶

zd [target]
```bash

### Targets

Same as `ze`:

- **No argument**: Edit main framework file (`zshrc.zsh`)
- **Partial name**: Fuzzy match in `core/` directory
- **Special targets**: `main`, `zshrc`, OS templates

## Examples

### Basic Editing Examples

```bash
# Edit main config with full diff review
# Shows exactly what changed before applying
zd

# Edit aliases with confirmation prompt
# Safe for adding/removing aliases without accidents
zd alias

# Edit functions safely with change preview
# Prevents breaking function syntax
zd func
```bash

### Review Workflow Example

```bash
# Start editing core configuration
zd core
# [opens editor in your preferred $EDITOR]
# [make changes, save file, close editor]
# [zd shows colored diff of all changes]
# Apply changes and rebuild? [y/N]: y
# [if confirmed, applies changes and runs zr automatically]
```bash

### Comparison with ze Example

```bash
# Fast editing without review (use for quick changes)
ze config

# Safe editing with mandatory diff review (use for important changes)
zd config
```bash

### Advanced Usage Examples

```bash
# Edit specific function with safety
zd functions/my-important-function

# Edit private functions (not in dotfiles)
zd private

# Edit OS-specific configuration
zd ubuntu    # or osx, wsl, etc.

# Edit keybindings with confirmation
zd keys
```bash

### Error Recovery Example

```bash
# If you make a mistake during editing
zd config
# [make changes]
# [see diff, realize mistake]
# Apply changes and rebuild? [y/N]: n
# [changes discarded, original file unchanged]

# Start over with clean state
zd config
```bash

### Batch Editing Example

```bash
# Edit multiple related files
zd core
# [edit core settings]

zd functions
# [edit function definitions]

# Review all changes together
# Each file edited separately with its own diff
```bash

## Workflow

1. **Target resolution**: Fuzzy matches to find the target file
2. **Temporary copy**: Creates `.tmp` version for editing
3. **Editor launch**: Opens temporary file in `$EDITOR`
4. **Diff generation**: Compares original vs edited version
5. **Review prompt**: Shows colored diff and asks for confirmation
6. **Application**: If confirmed, replaces original and suggests rebuild
7. **Cleanup**: Removes temporary file

## Configuration

### Editor Selection

Uses `$EDITOR` environment variable (same as `ze`):

```bash
export EDITOR="cursor --block"
export EDITOR="code --wait"
```bash

### Diff Display

Uses standard `diff` command with colors. Customize with:

```bash
# Color output (usually default)
export DIFF_COLOR=always

# Custom diff options
export DIFF_OPTIONS="--ignore-space-change"
```bash

## Dependencies

- **Required:** `zsh`, `$EDITOR`, `diff`
- **Optional:** `zr` (for rebuild suggestions), `colordiff` (better colors)

## Troubleshooting

### No Diff Shown

**Symptom:** Editor opens but no diff is displayed

**Cause:** No changes were made to the file

**Fix:**

```bash
# Make some changes and save
# Or check if file was actually modified
ls -la core/file.zsh.tmp  # Should exist during editing
```bash

### Diff Command Not Found

**Symptom:** "diff: command not found"

**Cause:** `diff` utility not installed

**Fix:**

```bash
# Install diffutils
sudo apt install diffutils  # Ubuntu/Debian
sudo dnf install diffutils  # Fedora
brew install diffutils      # macOS
```bash

### Temporary File Issues

**Symptom:** "Cannot create .tmp file"

**Cause:** Permission issues or read-only filesystem

**Fix:**

```bash
# Check permissions
ls -la core/
ls -ld core/

# Fix permissions if needed
chmod u+w core/file.zsh
```bash

## Performance

- **Launch time**: Fast (creates temp file instantly)
- **Diff generation**: Quick even for large files
- **Safety**: Prevents accidental overwrites
- **Review**: Allows careful consideration of changes

## Integration

### With ze (Quick Editor)

```bash
# Quick iteration
ze config

# Final review
zd config
```bash

### With zr (Rebuild)

```bash
# zd suggests zr automatically
zd functions
# "Apply changes and rebuild? [y/N]"

# Manual workflow
zd core && zr
```bash

### With Version Control

```bash
# Review changes before commit
zd config
git diff core/config.zsh
git add core/config.zsh
```bash

## Technical Details

### Temporary File Handling

- Creates `file.zsh.tmp` in same directory as original
- Atomic replacement: `mv file.zsh.tmp file.zsh`
- Safe cleanup: removes temp file even if process interrupted

### Diff Generation

```bash
# Basic diff command
diff -u original.zsh edited.zsh

# With colors (if available)
colordiff -u original.zsh edited.zsh
```bash

### Error Recovery

- If editor crashes, temp file remains for recovery
- If diff fails, offers to open files manually
- If replacement fails, original file is untouched

### Security

- Never modifies original file until you confirm
- Temporary files have restrictive permissions
- No network operations or external data access

## Advanced Usage

### Custom Diff Tools

```bash
# Use git diff for better formatting
zd() {
    # Custom zd with git diff
    local file=$(find_target "$1")
    cp "$file" "${file}.tmp"
    $EDITOR "${file}.tmp"
    if git diff --no-index --color "$file" "${file}.tmp"; then
        read -q "Apply? [y/N]: "
        if [[ $REPLY == 'y' ]]; then
            mv "${file}.tmp" "$file"
            zr
        fi
    fi
    rm -f "${file}.tmp"
}
```bash

### Batch Editing

```bash
# Edit multiple files
zd core && zd functions && zr
```bash

### Integration with Git

```bash
# Pre-commit review
zd config
git add -p core/config.zsh  # Interactive staging
```bash

## Gotchas

### Temporary Files Not Cleaned

**Problem:** Temporary files remain after canceling edit.

**Cause:** `zd` creates temp files that may not be cleaned on interruption.

**Solution:** Temp files are in `/tmp/zd-*`. Safe to delete manually.

### Diff Too Large

**Problem:** Diff output is overwhelming for large changes.

**Cause:** Editing very large files or making many changes.

**Solution:** Use `ze` for large files or break changes into smaller edits.
For large files, consider using your editor's diff features directly.

### Color Issues

**Problem:** Diff colors don't display properly.

**Cause:** Terminal doesn't support colors or color settings incorrect.

**Solution:** Check terminal capabilities:

```bash
echo $TERM
tput colors
```bash

Use `--no-color` flag if colors cause issues.

### Editor Changes Not Saved

**Problem:** Made changes in editor but diff shows no changes.

**Cause:** Editor didn't save file or saved to wrong location.

**Solution:** Ensure your editor saves to the temp file location.
Some editors need special configuration for temp file editing.

### Permission Denied

**Problem:** Cannot create temporary files.

**Cause:** `/tmp` not writable or disk full.

**Solution:** Check disk space and permissions:

```bash
df -h /tmp
ls -ld /tmp
```bash

### Syntax Errors Hidden

**Problem:** Diff looks good but syntax validation fails.

**Cause:** Zsh syntax errors not visible in diff.

**Solution:** `zd` shows syntax errors after diff review. Fix errors before
applying changes. Common issues: unmatched quotes, brackets, or syntax.

### Backup Files Accumulate

**Problem:** Many `.backup` files in config directories.

**Cause:** Frequent use of `zd` with backup creation.

**Solution:** Clean old backups periodically:

```bash
find ~/.config -name "*.backup" -mtime +30 -delete
```bash

## See Also

- **[ze](ze.md)** - Quick editor (no diff review)
- **[zr](zr.md)** - Framework rebuild tool
- **[rclink](rclink.md)** - Zshrc management
- **[Git Integration](../../README.md#git-integration)** - Version control
  with ZSHAND