SyncIgnore is a Python CLI for keeping cloud-synced projects fast. It moves large generated directories, such as node_modules, .venv, target, build output, and media caches, into a local scratch area and leaves symlinks where tools expect those directories to be.
The result is simple: source files and project files keep syncing, while disposable machine-local artefacts stay off OneDrive, Google Drive, iCloud Drive, Dropbox, network home drives, and similar services.
Release version: 0.6.5
This release is focused on proving and stabilising the Python CLI. A web UI is on the roadmap; Streamlit is a likely candidate, but the interface choice is still being evaluated.
SyncIgnore has taken a lot of careful work to make filesystem changes feel predictable, reversible, and useful for real cloud-synced workspaces. If it saves you time, bandwidth, storage, or support headaches, please consider supporting the project through GitHub Sponsors or Ko-fi.
Small open-source contributions are often around $5, $10, or $20, but any
amount is appreciated. Every little bit helps keep the project moving.
For local development from this repository:
uv sync --all-extras
uv run syncignore --helpWhen installed as a published package:
uv tool install syncignore
syncignore --helpOther Python installers such as pipx or pip may also work once the package is published:
pipx install syncignore
pip install syncignoreRun a dry run before allowing SyncIgnore to move files:
cd your-project
syncignore init . --detect
syncignore process . --dry-run
syncignore process .
syncignore project info .
syncignore project listinit and process are callback-style commands. Use syncignore init . and syncignore process .; there is no init run or process run subcommand.
syncignore --help
syncignore --version
syncignore --explain
syncignore init . --detect
syncignore init . --project-type python
syncignore init --list-templates
syncignore init --template-info nodejs
syncignore process . --dry-run
syncignore process . --reverse
syncignore process --all
syncignore process validate
syncignore process status
syncignore project detect .
syncignore project list --grouped
syncignore project info .
syncignore project health
syncignore config show
syncignore config set scratch_dir=~/.syncignore/scratches --global
syncignore config validate
syncignore service status
syncignore template list
syncignore telemetry statusMost command groups support the global --json option for automation. Telemetry has command-specific JSON support for telemetry status --json and telemetry metrics --json.
Built-in detection and templates cover:
| Type | Common generated artefacts |
|---|---|
| Node.js | node_modules, dist, .next, cache folders |
| Python | .venv, venv, __pycache__, .pytest_cache, build output |
| Rust | target |
| Unity | Library, Temp, obj, build output |
| CMake | build directories and generated CMake files |
| Blender | render, cache, and temporary output |
| DaVinci Resolve | cache, render, proxy, and optimised media folders |
| Zephyr RTOS | build and generated output |
| Generic | user-defined patterns |
SyncIgnore is designed to be conservative with filesystem changes:
--dry-runpreviews planned operations.- Processing validates paths before mutation.
- Backups are enabled by default.
- Reverse processing can restore symlinked directories where supported.
- Platform-specific symlink behaviour is handled separately for POSIX/macOS/Linux and Windows.
Do not run real processing against important projects until the dry run output matches what you expect.
Current default locations:
| Data | Location |
|---|---|
| User config | ~/.syncignore/config.toml |
| Project config | <project>/.syncignore.toml |
| Project registry | ~/.syncignore/projects.json |
| Scratch storage | ~/.syncignore/scratches |
| Telemetry config | ~/.config/syncignore/telemetry-config.json |
Configuration is resolved in this order: CLI arguments, SYNCIGNORE_ environment variables, project config, user config, defaults.
English CLI help is complete. Partial localised command help exists for Spanish, Chinese, Maori, Hindi, Pitjantjatjara, Wiradjuri, and Kriol, with English fallback when a help file is missing.
Runtime language detection currently reads LC_ALL and LANG. It does not currently read SYNCIGNORE_LANG.
GitHub documentation is maintained in English for now. The codebase does not require release docs to be translated into every CLI help language.
Release documentation lives in _docs/:
_docs/README.md_docs/installation.md_docs/quick-start.md_docs/command-reference.md_docs/configuration.md_docs/templates.md_docs/language-support.md_docs/troubleshooting.md_docs/architecture.md_docs/testing.md_docs/roadmap.md_docs/release-checklist.md
Private planning notes under _my_docs/ are intentionally ignored and are not release documentation.
uv sync --all-extras
uv run pytest
uv run ruff check src tests
uv run ruff format src tests
uv run mypy src
uv buildSee CONTRIBUTING.md for contribution guidelines.
SyncIgnore is released under the MIT Licence. See LICENSE.
