Remote Diff SSH

Compare files in a local VS Code workspace with files on a remote server over SSH.

Remote Diff SSH is a free public beta. Transfer one file at a time with explicit confirmation, conflict protection, verified backups, and no remote project-file deletion commands.

Version 0.3.0 is distributed as a Marketplace pre-release. It includes guarded single-file downloads and opt-in guarded single-file uploads.

Why Remote Diff SSH

• Review server differences inside VS Code before transferring anything.
• Keep Upload disabled until each workspace explicitly enables it.
• Back up and verify both local downloads and remote uploads.
• Detect remote changes before overwriting another developer's work.
• Connect directly from your machine to your SSH server without a hosted relay.

Requirements

• Visual Studio Code 1.125.0 or newer
• An SSH server reachable from the machine running VS Code
• SSH private-key or agent authentication

Getting started

1. Copy .vscode/remote-diff.example.json to .vscode/remote-diff.json in the workspace you want to compare.
2. Update the SSH connection and remote path values.
3. Open the Command Palette and run Remote Diff: Test Connection.
4. Open a text file inside the workspace and run Remote Diff: Compare Current File. The command is also available from editor and Explorer context menus.
5. Run Remote Diff: Scan Workspace to populate the Remote Diff SSH view in Explorer.
6. To replace a local file with its remote version, use Remote Diff: Download Remote File from the editor, Explorer, or a Modified/Remote only result. Review the paths in the confirmation dialog before continuing.

The real .vscode/remote-diff.json file is ignored by Git to reduce the risk of publishing server details. Commit only the example file.

Configuration

{
  "name": "Staging server",
  "host": "staging.example.com",
  "port": 22,
  "username": "deploy",
  "remotePath": "/var/www/example",
  "privateKeyPath": "~/.ssh/id_ed25519",
  "useAgent": true,
  "keyboardInteractive": false,
  "connectTimeout": 10000,
  "enableUpload": false,
  "backup": {
    "maxVersionsPerFile": 5,
    "maxAgeDays": 30,
    "maxTotalSizeMB": 100
  },
  "remoteBackup": {
    "maxVersionsPerFile": 5,
    "maxAgeDays": 30,
    "maxTotalSizeMB": 100
  },
  "ignore": [
    ".git/**",
    "node_modules/**",
    ".env"
  ]
}

Do not place passwords, private-key contents, or other secrets in this file.

Current functionality

• Load connection settings from .vscode/remote-diff.json
• Authenticate with an SSH private key, encrypted key passphrase, or SSH agent
• Verify a pinned host fingerprint or ask before trusting a host on first use
• Open an SFTP session with read, stat, and directory-listing operations
• Test an SSH connection from the Command Palette
• Map a local workspace file to its counterpart below remotePath
• Open the local and remote UTF-8 text files in VS Code's Diff Editor
• Decode legacy Thai files that explicitly declare TIS-620, Windows-874, or CP874
• Recursively scan local and remote directories using configured ignore patterns
• Group files as Modified, Local only, Remote only, or Identical in an Explorer Tree View
• Use size and modification time as a fast path, then SHA-256 content hashes for ambiguous equal-sized files
• Batch remote metadata and hash commands when supported, with an SFTP fallback and in-memory hash cache
• Refresh workspace results and open Modified files in the Diff Editor
• Download one Modified or Remote only file after an explicit confirmation
• Back up an existing local file under .vscode/remote-diff-backups, write through a temporary file, verify its SHA-256 hash, and refresh the comparison
• Automatically remove backups over 5 versions per file, older than 30 days, or over 100 MB total (all limits are configurable)
• Reject dirty editors, path traversal, and local symbolic-link destinations during downloads
• Upload one Modified or Local only file when enableUpload is explicitly enabled
• Detect remote changes since Compare or Scan before uploading
• Back up an existing remote file under .remote-diff-backups, preserve its mode, upload through a temporary file, verify SHA-256, and atomically replace it
• Automatically remove remote backups over 5 versions per file, older than 30 days, or over 100 MB total
• Reject local or remote symbolic links and remove temporary upload files after failures or cancellation
• Reset a saved key passphrase and trusted host fingerprint from the Command Palette

Planned functionality

• Download or upload multiple selected files

Development

npm ci
npm run check-types
npm run lint
npm test
npm run package
npm run package:vsix
npm run package:marketplace

Press F5 in VS Code to launch an Extension Development Host.

Installation

For the public beta, open the VS Code Extensions view, find Remote Diff SSH, select Switch to Pre-Release Version when necessary, and install it. Marketplace builds receive automatic updates.

For local testing, build remote-diff-ssh-0.3.0.vsix with npm run package:marketplace. In VS Code, open the Extensions view, choose Views and More Actions…, select Install from VSIX…, and pick the generated file.

Security

On the first connection to a target without hostFingerprint, verify the displayed fingerprint through a trusted channel before selecting Trust Fingerprint. The accepted fingerprint is stored in VS Code global state and a changed key is rejected. For managed environments, pin hostFingerprint in the workspace configuration.

Encrypted private-key passphrases are stored in VS Code SecretStorage. Passwords and private-key contents must never be added to .vscode/remote-diff.json.

If a server key or private-key passphrase changes, run Remote Diff: Reset Credentials and Host Trust and reconnect. Verify a replacement server fingerprint before trusting it.

Remote files are opened read-only in a virtual document. UTF-8 is required unless a legacy Thai file explicitly declares TIS-620, Windows-874, or CP874 in its first 16 KB. Binary files and undecodable text are rejected instead of being decoded speculatively. For an accurate legacy-file comparison, use VS Code's Reopen with Encoding on the local file and choose Thai (Windows 874) before comparing.

Downloads affect only the local workspace. Existing files require confirmation and are copied to .vscode/remote-diff-backups before replacement. By default, cleanup retains up to 5 versions per file for 30 days and limits all workspace backups to 100 MB, deleting the oldest backups first. A single local file larger than the configured total limit is not replaced because it cannot be backed up safely. The extension also refuses to replace an unsaved editor or write through a symbolic link.

Uploads are disabled by default. Set "enableUpload": true, then Compare or Scan before uploading so the extension has a conflict snapshot. Existing remote files are backed up under <remotePath>/.remote-diff-backups and excluded from scans. By default, cleanup retains up to 5 versions per file for 30 days and limits remote backups to 100 MB, deleting the oldest managed backups first. Files not matching the extension's timestamped .bak format are never deleted. Uploads preserve the existing file mode, verify temporary and installed content, and refuse to write when the remote file changed after the snapshot. A remote file larger than the configured total backup limit is not replaced because it cannot be backed up safely.

Workspace scanning first compares file size and modification time. Equal-sized files with different modification times are read and compared using SHA-256 content hashes. Add generated files, dependencies, caches, logs, uploads, and other large directories to ignore to keep scans fast and reduce server load.

Please report security concerns privately to the repository owner instead of opening a public issue containing credentials or server details.

See SECURITY.md for private vulnerability reporting and PRIVACY.md for the extension's data-handling disclosure.

License

MIT