Getting started

From an empty list to a first synchronization in a few minutes. The examples use a site called My Site in C:\Users\<user>\Sites\my-site on Windows, or ~/sites/my-site elsewhere, published to sftp.example.com as demo-user.

1. Add a site

Open the Sync Servers view in the activity bar and choose Add Site, or run Sync Servers: Add Site from the Command Palette. A short input asks, one step at a time, with Back on each:

1. The site name, such as My Site, different from your other sites ignoring case.
2. The local site folder, from the folder picker.
3. Protocol: SFTP, FTPS, FTPS with implicit TLS, FTP, a local or network folder, or no server yet. Plain FTP asks a second time, because it sends the password in clear text.
4. Host: the FTP or SFTP host your hosting panel shows, such as sftp.example.com or 203.0.113.10. host:port works when the port is not the usual one, and a whole address such as sftp://demo-user@sftp.example.com/var/www/my-site fills the protocol, the user and the root directory too.
5. User, such as demo-user. Many hosts name FTP accounts in full, such as demo-user@example.com.
6. The password. Leave it empty to be asked when the server wants it.

Add Site then connects, before anything is added, under a notification you can cancel:

• A host key or a certificate seen for the first time is shown for you to decide on, as in Test the connection.
• When the server refuses the user name or password, Add Site asks for both again, up to three times.
• When it cannot connect at all, it offers Change the Host (or Try Again after refused sign-ins), Save Without Testing, which asks for the root directory as a path, and Cancel, which adds nothing.

Once connected, a list of the folders on the server opens where your account starts. Choose Use This Folder on the folder that holds the site, such as /var/www/my-site; .. goes up, a folder opens, and a path typed in the box goes straight there. When you choose /, the top of what the account can see, Add Site asks once whether synchronizing may delete files there.

The server is named after its host, such as sftp.example.com, and can be renamed in Site Settings. The password is saved in VS Code's secret storage only once the server has accepted it. The first server becomes the Remote server, the one Synchronize uses. A site added with sync-servers site add in a terminal shows up in the Sites view straight away, and the other way round: both read the same list.

2. Test the connection

Choose Test Connection on the server in the Sites view. The first connection to an SFTP server shows the server's host key fingerprint in a warning:

• Trust and Remember pins the key in the server's settings. A different key later stops the connection.
• Trust Once trusts it for this connection only.
• Closing the warning refuses the key.

An FTPS certificate that does not verify shows its names, its issuer, its validity dates and its SHA-256 fingerprint. When the certificate covers another name for the same server, such as server1.hosting.example.net for a certificate issued to *.hosting.example.net, the first choices keep full verification: Connect to server1.hosting.example.net changes the host, and Check as server1.hosting.example.net keeps the host and checks the certificate against that name. Trust and Remember and Trust Once trust the certificate by its fingerprint. An expired certificate, or one not valid yet, can only be cancelled.

Compare a fingerprint with the one your host publishes before trusting it. A passing test says how many items the root folder holds and which server software answered. A failing one offers the fix that fits: Choose Folder when the root directory is not found, Sign In Again when the user name or password is refused, and Edit Host when the host is not found or refuses the connection.

3. Open the site's folder

Choose Open Site Folder on the site. When the workspace is a site's local folder, that site is active on its own: the status bar shows My Site: sftp.example.com, the Explorer marks changed files, and its context menu offers Put, Get and Compare. Switch Site makes another site active without opening its folder.

4. Synchronize

1. Choose Synchronize... on the site, or click the status bar item.
2. Answer Put newer files to remote, then Keep remote files that are not on the local drive.
3. The Sync Preview opens with every file that would move, checked. Uncheck anything that should stay.
4. Choose Synchronize Checked Files in the preview's title bar.

A notification reports Synchronized 12 files. 0 failed. 0 skipped. From now on, the extension remembers what each side looked like, so a file changed on both sides waits for your decision. Synchronize covers the preview in full.

Sharing the list with the command line

The extension and sync-servers read the same sites.json: in %APPDATA%\sync-servers on Windows, ~/Library/Application Support/sync-servers on macOS, and ~/.config/sync-servers elsewhere. The setting syncServers.configDir, or SYNC_SERVERS_HOME, points both somewhere else. Passwords are the exception: each keeps its own, so each asks once.