Status: Done keeps cloud-synced projects fast by moving disposable generated directories and files out of the synced workspace while leaving tools a familiar path to use.
Overview Of SyncIgnore
SyncIgnore is a developer and studio workflow tool for reducing cloud-sync noise from folders that can be rebuilt locally, such as dependencies, build output, caches, and temporary assets.
SuyncIgnore is now
OpenSource
SyncIgnore is now in github.
Got to our SocIt2Em SyncIgnore public page to see more SocIt2Em Github SyncIgnore. Fully documented.
Simple Setup
Auto detect, dry run, process.
back
Simple setup should start with detection, a dry run, then real processing only after the preview looks correct.
back
Basic Detect Setup
Use Basic Detect Setup for a single project when SyncIgnore should detect the project type and recommended generated folders.
This sequence moves from the project directory, initializes detection, previews the filesystem changes, applies them, then checks the registered project state.
| Command | Brief |
|---|---|
|
Open the project directory before running SyncIgnore. |
|
Detect the project type and prepare SyncIgnore configuration. |
|
Preview which generated folders would move to scratch storage. |
|
Apply the plan and create the symlink replacements. |
|
Show registered project status and symlink information. |
Template Setup
Use this when the project type is known and a built-in template should drive the initial configuration.
cd your-project
syncignore init . --template python
syncignore process . --dry-run
syncignore process .
Set And Forget Workflow
Use this when SyncIgnore should keep helping after the first setup.
After the project is configured and the dry run looks right, SyncIgnore can support a set-and-forget workflow through registered projects, project health checks, and service mode.
This keeps the story simple for marketing pages: set up once, preview safely, then let SyncIgnore keep generated folders out of cloud sync as projects keep changing.
Custom Scratch Setup
Use this when generated folders must be stored in a specific local scratch location outside the cloud-synced project.
cd your-project
syncignore init . --detect --scratch-dir ~/.syncignore/scratches
syncignore process . --dry-run
syncignore process .
Registered Projects Setup
Use this when projects are already registered and need to be reviewed or processed as a group.
syncignore project list
syncignore process --all --dry-run
syncignore process --all
syncignore project health
Reverse Setup
Use this when symlinked folders need to be restored back into the project directory.
cd your-project
syncignore process . --reverse --dry-run
syncignore process . --reverse
Project Detection
Project detection identifies common project types and generated folders so users do not need to configure every path by hand.
Overview Of Project Detection
SyncIgnore scans project files and known directory patterns to suggest safe candidates for local-only storage.
Existing Ignore Files
SyncIgnore can work with the project patterns developers already use.
Project detection and processing can draw from existing ignore-style configuration, including familiar .gitignore patterns, so teams do not need to describe every generated folder from scratch.
This makes the first setup feel natural: SyncIgnore starts from the project structure and existing ignore intent, then turns rebuildable folders into local-only storage candidates.
Detector Coverage
Detector coverage is plugin-based.
The registry loads built-in detectors, template-backed detectors, and detectors exposed through the syncignore.detectors entry point group.
Core built-in detectors cover Node.js, Python, Rust, Unity, and Generic projects. The aggregator sorts detections by confidence and resolves high-confidence conflicts by project-type priority.
Template Coverage
Templates extend detection coverage.
Built-in templates currently include Node.js, Python, Rust, Unity, Generic, CMake, Blender, DaVinci Resolve, and Zephyr RTOS.
Templates define confidence factors and exclusion patterns. Project and user templates can override or extend built-in behavior through the template manager.
Local Scratch Storage
Local scratch storage keeps large generated folders on the current machine instead of inside the cloud-synced project tree.
Overview Of Local Scratch Storage
SyncIgnore moves selected folders to a scratch location and keeps the project layout predictable for local tools.
Default Scratch Path
The default scratch path is ~/.syncignore/scratches.
The configuration model stores this value as scratch_dir, and the README lists it as the default scratch storage location.
Processing builds target paths under the scratch area by project name and relative folder path, keeping moved content organized outside the project tree.
Configuration Control
Configuration is layered.
SyncIgnore resolves settings from CLI arguments, supported SYNCIGNORE_ environment variables, project config, user config, then defaults.
The scratch path is configurable through config files and CLI config commands. Current environment variable handling does not map SYNCIGNORE_SCRATCH_DIR directly.
Symlink Replacement
Symlink replacement lets applications continue reading and writing the original folder paths after the data has been moved.
Overview Of Symlink Replacement
SyncIgnore leaves a symlink where the folder used to be, pointing back to the local scratch copy.
Operation Flow
Processing starts with a plan.
The process adapter gathers ignore patterns from project config, metadata, templates, or detector recommendations, then builds create or remove operations.
Dry-run mode simulates operations before mutation. Real processing validates paths, creates backups, moves directories, creates links, verifies results, and reports structured process results.
Platform Handling
Platform behavior is strategy-based.
The platform factory selects a POSIX or Windows symlink strategy and caches it for reuse.
POSIX supports normal symlinks, relative targets, absolute targets, and cross-filesystem links. Windows uses junction-focused directory behavior, supports junction detection, and requires same-volume handling for junctions.
Backup And Rollback
Backup and rollback behavior protects users from partial filesystem changes during processing.
Overview Of Backup And Rollback
SyncIgnore can back up folders before moving them and attempts to restore a safe state if an operation fails.
Backup Defaults
Backups are enabled by default.
The configuration model sets backup_before_process = true, and the symlink manager creates backups before create and remove operations.
Backup metadata records the operation ID, operation type, source path, target path, backup path, timestamp, size, file count, and checksum when available.
Rollback Behavior
Rollback uses stored metadata.
If symlink creation or removal fails, the symlink manager asks the backup manager to roll back the operation.
Reverse processing removes symlinks and restores original content from the target when supported. Transaction rollback runs recorded operations in reverse order.
Monitoring And Service Mode
Monitoring and service mode support set-and-forget workflows for projects that keep regenerating ignored folders.
Overview Of Monitoring And Service Mode
SyncIgnore can watch configured projects and help keep generated folders out of cloud sync over time.
File Monitoring
Monitoring uses filesystem events.
The file monitor uses watchdog observers, queues events, debounces bursts, tracks stats, and starts background threads for event processing and performance monitoring.
Critical or high-priority paths include .syncignore, package.json, node_modules, .venv, target, dist, and build.
Service Commands
Service commands manage background operation.
The CLI exposes service status, install, uninstall, start, stop, restart, health, and config commands.
The service manager is selected by platform, with macOS, Linux, Windows, and generic managers available. Service availability depends on platform support and privileges.
Summary
SyncIgnore keeps generated files local, keeps source files synced, and keeps project folders usable through predictable symlink handling.