WSL Sync

A modern desktop application for seamless two-way file synchronization between Windows and WSL (Windows Subsystem for Linux) environments.

Features

Core Functionality

• Two-way synchronization between Windows and WSL file systems
• Real-time progress tracking with detailed file-by-file updates
• Path validation for both Windows and WSL formats
• Automatic path conversion between Windows and WSL formats
• Conflict resolution with multiple resolution strategies
• Dry run mode to preview changes before syncing

Performance & Reliability

• Multi-threaded processing using worker threads for optimal performance
• Streaming for large files with progress reporting
• Intelligent file batching for efficient small file handling
• Retry mechanism with exponential backoff for transient failures
• Operation queue to prevent UI freezing during large syncs
• File verification using SHA-256 hashing (optional)

User Interface

• Modern Web 3.0 design with glassmorphism effects
• Dark mode support with smooth theme transitions
• Interactive folder tree with file type icons
• Real-time validation with inline error messages
• Progress visualization with detailed statistics
• Responsive layout that works on various screen sizes

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Windows 10/11 with WSL2 installed
• Git (for cloning the repository)

Setup

1. Clone the repository:

git clone https://github.com/yourusername/wsl-sync.git
cd wsl-sync

2. Install dependencies:

npm install

3. Run in development mode:

npm run dev

4. Build for production:

npm run build

Usage

Basic Sync Operation

1. Launch the application
2. Enter or browse to your Windows folder path
3. Enter your WSL folder path (e.g., /home/user/project)
4. Click "Sync Both Ways" to start synchronization

Sync Options

• Dry Run: Preview changes without applying them
• Verify Files: Enable SHA-256 verification for file integrity
• Max Workers: Adjust the number of worker threads (default: 4)

Path Formats

• Windows: C:\Users\YourName\Documents\project or D:\projects\myapp
• WSL: /home/username/project or /mnt/c/Users/YourName/Documents

Sync Patterns

The application supports .syncignore files for excluding files/folders from sync:

# .syncignore example
node_modules/
*.tmp
.git/
build/
dist/
*.log

Architecture

Technology Stack

• Frontend: React 19.1.0 with Vite
• Desktop Framework: Electron 36.4.0
• Styling: Tailwind CSS with custom theme system
• File Operations: Node.js fs-extra with worker threads
• State Management: React hooks and event emitters

Key Components

• sync/sync.js - Core synchronization logic with path validation
• sync/sync-performance.js - Performance-optimized sync with worker threads
• sync/file-worker.cjs - Worker thread for parallel file operations
• electron/main.cjs - Main Electron process with IPC handlers
• src/App.jsx - React UI with modern design
• src/components/FolderTree.jsx - Interactive folder browser

Development

Available Scripts

# Development
npm run dev              # Start dev server with hot reload

# Testing
npm test                 # Run all tests
npm run test:ui         # Run UI tests with Vitest
npm run test:watch      # Run tests in watch mode

# Building
npm run build           # Build for production
npm run clean          # Clean build artifacts

Project Structure

wsl-sync/
├── electron/           # Electron main process
├── src/               # React application
│   ├── components/    # React components
│   └── styles/        # CSS and theme files
├── sync/              # Core sync logic
├── tests/             # Test suites
├── dist/              # Build output
└── assets/            # Application assets

Testing

The project includes comprehensive test coverage:

• Unit tests for sync logic
• Integration tests for IPC communication
• Performance tests for worker threads
• UI tests for React components

Run tests with:

npm test

Performance

Optimization Features

• Worker threads for parallel processing
• Streaming for files over 10MB
• Batch processing for small files
• Operation queuing to prevent overload
• Efficient memory usage with streaming

Benchmarks

• Small files (< 1MB): Up to 100 files/second
• Large files (> 10MB): 15-20 MB/s throughput
• Worker threads: 2-4x performance improvement for many files

Troubleshooting

Common Issues

1. "WSL path does not exist" error

   • Ensure WSL is running: wsl --list --running
   • Check path accessibility: wsl ls /your/path

2. "Permission denied" errors

   • Run the app as administrator if needed
   • Check file permissions in both Windows and WSL

3. Sync seems slow

   • Increase worker threads in settings
   • Check for antivirus interference
   • Ensure no other heavy I/O operations

Debug Mode

Set the DEBUG environment variable for verbose logging:

DEBUG=wsl-sync:* npm run dev

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit changes: git commit -am 'Add your feature'
4. Push to branch: git push origin feature/your-feature
5. Submit a pull request

Code Style

• Use ESLint for JavaScript linting
• Follow React best practices
• Write tests for new features
• Update documentation as needed

Security

• Paths are validated to prevent directory traversal
• File operations are sandboxed within specified directories
• No data is sent to external servers
• Credentials are never stored

License

This project is licensed under the ISC License. See the LICENSE file for details.

Acknowledgments

• Built with Electron
• UI powered by React
• Styled with Tailwind CSS
• Icons from Lucide

Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing issues for solutions
• Read the documentation for technical details

---

Made with ❤️ for the Windows + Linux development community