rclink - Recursive Link Tool¶

rclink [options] <source> <target>
```bash

### Options

- `-r`: Recursive mode (default)
- `-f`: Force overwrite existing files/links
- `-i`: Interactive conflict resolution
- `-n`: Dry run (show what would be done)
- `-b`: Create backups before overwriting
- `-v`: Verbose output
- `-q`: Quiet mode
- `-l`: Follow symbolic links in source
- `-d DEPTH`: Maximum recursion depth
- `-h`: Show help

## Examples

### Basic Linking

```bash
# Link directory recursively
rclink ~/project/config ~/.config/

# Link single file
rclink ~/.zshrc ~/.config/zsh/rc

# Dry run to preview
rclink -n ~/dotfiles/ ~/
```bash

### Conflict Resolution

```bash
# Force overwrite
rclink -f ~/new-config/ ~/.config/

# Interactive resolution
rclink -i ~/project-files/ ~/workspace/

# Backup before overwrite
rclink -b ~/updated-config/ ~/.config/
```bash

### Advanced Usage

```bash
# Limited depth
rclink -d 2 ~/shallow-copy/ ~/target/

# Follow symlinks in source
rclink -l ~/linked-source/ ~/target/

# Verbose output
rclink -v ~/source/ ~/target/
```bash

## How It Works

### Linking Algorithm

1. **Discovery**: Traverse source directory structure
2. **Analysis**: Check target existence and type
3. **Conflict Resolution**: Handle existing files/links
4. **Link Creation**: Create symbolic links
5. **Verification**: Confirm successful linking
6. **Cleanup**: Remove backups if successful

### Conflict Types

- **File Exists**: Target file exists
- **Link Exists**: Target is already a symlink
- **Directory Exists**: Target is a directory
- **Permission Denied**: Cannot create link
- **Cross-Filesystem**: Source and target on different filesystems

### Resolution Strategies

- **Skip**: Leave existing file unchanged
- **Backup**: Move existing to backup location
- **Overwrite**: Remove existing and create link
- **Merge**: Handle directory conflicts
- **Interactive**: Prompt user for each conflict

## Configuration

### Configuration File

```toml
# ~/.config/rclink/config.toml
[linking]
default_mode = "recursive"
follow_symlinks = false
max_depth = 10

[conflicts]
default_action = "backup"
backup_suffix = ".backup"
interactive = false

[output]
verbose = false
quiet = false
log_file = "~/.local/log/rclink.log"

[excludes]
patterns = [".git", "__pycache__", "*.tmp"]
skip_hidden = true

[performance]
parallel_linking = true
batch_size = 100
```bash

### Environment Variables

```bash
# Default behavior
export RCLINK_FORCE="false"
export RCLINK_INTERACTIVE="true"

# Backup settings
export RCLINK_BACKUP_SUFFIX=".bak"
export RCLINK_BACKUP_DIR="~/rclink-backups"

# Performance
export RCLINK_MAX_DEPTH="5"
export RCLINK_PARALLEL="true"
```bash

## Dependencies

### Required

- **ln**: Symbolic link creation
- **find**: Directory traversal
- **readlink**: Link verification
- **mkdir**: Directory creation

### Optional

- **rsync**: Backup creation
- **dialog/whiptail**: Interactive prompts
- **parallel**: Parallel processing

## Troubleshooting

### Permission Denied

**Symptom:** "Permission denied" when creating links

**Cause:** Insufficient permissions on target directory

**Fix:**

```bash
# Check permissions
ls -ld /target/directory/

# Fix permissions
chmod +w /target/directory/

# Use sudo if necessary
sudo rclink /source/ /target/

# Check SELinux/AppArmor
ls -Z /target/directory/
```bash

### Cross-Filesystem Links

**Symptom:** Links fail across different filesystems

**Cause:** Symlinks cannot cross filesystem boundaries

**Fix:**

```bash
# Check filesystems
df -h /source/ /target/

# Use bind mounts
sudo mount --bind /source/subdir /target/subdir

# Use relative paths
rclink -r ../relative/source ./target/

# Copy instead of link
cp -r /source/ /target/
```bash

### Broken Links

**Symptom:** Created links are broken

**Cause:** Incorrect relative paths or moved sources

**Fix:**

```bash
# Check link targets
ls -la /target/link

# Verify source exists
ls -la /source/file

# Recreate with absolute paths
rclink -f /absolute/source/path /absolute/target/path

# Use relative paths carefully
cd /target && rclink ../source .
```bash

### Infinite Loops

**Symptom:** Linking hangs or creates circular references

**Cause:** Recursive linking of self-referential structures

**Fix:**

```bash
# Limit depth
rclink -d 3 /source/ /target/

# Exclude problematic directories
export RCLINK_EXCLUDE_PATTERNS=".git,node_modules"

# Check for circular references
find /source -type l | head -10
```bash

## Performance

### Linking Times

| Scenario        | Files | Time | Memory |
| --------------- | ----- | ---- | ------ |
| Small config    | 50    | 2s   | 20MB   |
| Medium project  | 500   | 15s  | 50MB   |
| Large directory | 5000  | 2min | 200MB  |

### Optimization Tips

- **Parallel Processing**: Enable for multi-core systems
- **Batch Operations**: Process files in batches
- **Exclude Patterns**: Skip unnecessary files
- **Depth Limiting**: Prevent excessive recursion

## Integration

### With Development Setup

```bash
# Link dotfiles
rclink ~/dotfiles/ ~/

# Link project config
rclink ~/project/config/ ~/.config/project/

# Link development tools
rclink ~/tools/ ~/bin/
```bash

### With Backup Systems

```bash
# Create backup before linking
rclink -b ~/new-config/ ~/.config/

# Restore from backup
cp ~/.config/.backup/* ~/.config/

# Versioned backups
rclink -b --backup-dir ~/config-backups/$(date +%Y%m%d) ~/config/ ~/.config/
```bash

### With Package Management

```bash
# Link package files
rclink /opt/package/share/ ~/.local/share/

# Link binaries
rclink /opt/package/bin/ ~/.local/bin/

# Link libraries
rclink /opt/package/lib/ ~/.local/lib/
```bash

### With Container Management

```bash
# Link volumes
rclink /host/data/ /container/data/

# Link configs
rclink /host/config/ /container/config/

# Link logs
rclink /container/logs/ /host/logs/
```bash

## Technical Details

### Link Creation

```bash
# Absolute path linking
ln -s /absolute/source/path /target/link

# Relative path linking
cd /target && ln -s ../relative/source/path link

# Directory linking
ln -s /source/directory /target/directory
```bash

### Conflict Resolution

- **File Conflicts**: Backup or overwrite existing files
- **Link Conflicts**: Update link target or skip
- **Directory Conflicts**: Merge or replace directories
- **Permission Conflicts**: Skip or attempt with elevated privileges

### Backup System

- **Automatic Backups**: Timestamped backup files
- **Backup Directories**: Organized backup storage
- **Restore Capability**: Easy backup restoration
- **Cleanup**: Automatic old backup removal

### Verification

- **Link Validity**: Check all created links work
- **Permission Preservation**: Maintain correct permissions
- **Ownership**: Preserve file ownership
- **Integrity**: Verify link targets exist

## See Also

- **[pcopy](pcopy.md)** - Local file copying
- **[persync](persync.md)** - Remote resilient sync
- **[File Management](../../README.md#file-management)** - File management guide