Seamlessly synchronize cSpell dictionaries between projects, workspace, and your global settings. This extension ensures that your custom words, dictionaries, and spelling preferences remain consistent across all your projects.
Features
Automatic Project to Global Sync: Automatically synchronizes project-specific spelling dictionaries with your global VS Code dictionary.
Bidirectional Sync: Sync words from global dictionary back to project settings, allowing centralized word management.
Custom Dictionary Management: Create, update, and synchronize custom dictionaries.
Flexible Configuration: Control exactly which sources to sync and how sync operations should behave.
Multiple Sync Sources:
Project settings (cSpell.words)
Custom dictionaries
Language-specific settings
Combined.txt files (temporary word lists)
Multiple Sync Targets:
Global dictionary (cSpell.userWords)
Project settings
Workspace settings
New or existing custom dictionaries
Commands
The extension provides the following commands that you can execute through:
The VS Code Command Palette (press F1 or Ctrl+Shift+P and type "cSpell Sync")
Keyboard shortcuts
The extension's status bar item ($(sync) icon in the bottom status bar)
cSpell Sync: Sync Words from Projects to Global Dictionary (Ctrl+Alt+S / Cmd+Alt+S)
Syncs words from all configured project sources to global dictionary
Runs automatically on startup (if enabled in settings)
Can also be triggered manually when needed
cSpell Sync: Sync Words from Global Dictionary to Projects (Ctrl+Alt+G / Cmd+Alt+G)
Syncs words from global dictionary to configured project targets
Can be set to run automatically when global dictionary changes (see bidirectionalSyncMode setting)
cSpell Sync: Sync Words from Custom Dictionaries to Global Dictionary
Specifically syncs words from custom dictionaries to global dictionary
Available through Command Palette only (no default keyboard shortcut)
Configuration Options
General Settings
cspell-sync.autoSyncOnStartup: Automatically sync when VS Code starts (default: true)
cspell-sync.initialSyncDelay: Delay in milliseconds before running initial sync (default: 5000)
cspell-sync.logToOutputChannel: Log detailed operations to output channel (default: false)
cspell-sync.showNotifications: Show notifications when words are synced (default: true)
Source Settings (Project to Global)
cspell-sync.syncProjectSettings: Sync from project settings.json (default: true)
cspell-sync.syncCombinedTxt: Sync from combined.txt files (default: true)
cspell-sync.syncCustomDictionaries: Sync from custom dictionaries (default: true)
cspell-sync.syncLanguageSettings: Sync from language-specific settings (default: true)
cspell-sync.combinedFileWaitTime: Time to wait before checking combined.txt file (default: 1000)
cspell-sync.customToGlobalSync: Sync words from custom dictionaries to global when running project-to-global sync (default: false)
Target Settings (Global to Project)
cspell-sync.enableBidirectionalSync: Enable syncing from global to project (default: true)
cspell-sync.bidirectionalSyncMode: How to sync words from global to project (default: shortcut)
shortcut: Only via keyboard shortcut
automatic: Also sync when global dictionary changes
disabled: Turn off bidirectional syncing
Sync Target Options
cspell-sync.projectLevelSync: Settings for syncing to project level settings
enabled: Enable syncing to project level settings (default: true)
target: Which setting to sync to (cSpell.words, cSpell.userWords, or cSpell.ignoreWords)
cspell-sync.customDictionarySync: Settings for syncing to existing custom dictionaries
enabled: Enable syncing to a custom dictionary file (default: false)
dictionaryName: Dictionary name to sync to (must exist in cSpell.customDictionaries)
cspell-sync.workspaceSync: Settings for syncing to workspace-level settings
enabled: Enable syncing to workspace settings (default: false)
target: Which workspace setting to sync to (default: cSpell.words)
cspell-sync.newDictionarySync: Settings for creating and syncing to a new dictionary
enabled: Enable creating/syncing to a new dictionary file (default: false)
name: Name for the new dictionary (default: project-dictionary)
format: Format for the dictionary file (txt or json, default: json)
Working with Combined.txt
The extension can detect a special file called combined.txt which can be used as a temporary collection of words. This is useful for:
Quickly adding multiple words without editing settings
Sharing words with team members
Importing words from external sources
When a combined.txt file is detected, the extension will:
Extract all words from the file
Add any new words to your global dictionary
Remove the file (unless configured to keep it)
You can disable the auto-remove behavior by configuring the project setting:
{
"cspell-sync.combined-auto-remove": false
}
Example Workflows
Basic Usage
Open a project with custom spelling words in .vscode/settings.json
Let cSpell Sync automatically add these words to your global dictionary
Words will now be recognized in all your projects
Advanced Dictionary Management
Configure newDictionarySync to create a project-specific dictionary
Use Ctrl+Alt+G to sync your global words to this dictionary
The dictionary will be automatically registered in your project settings
Team Dictionary Sharing
Configure customDictionarySync to target a shared dictionary
Add words to your global dictionary normally
Use Ctrl+Alt+G to sync these words to the shared dictionary
Commit the updated dictionary file to share with your team
