dbxignore

First-time setup

dbxignore init [PATH] writes a starter .dropboxignore into PATH (or the current directory). The packaged template covers common dev artifacts across ecosystems — Node.js (node_modules, npm/yarn/pnpm caches and logs), Python (virtualenvs, bytecode, tool caches), Rust (target/), JVM (.gradle/), .NET (bin/, obj/), frontend frameworks (.next/, .nuxt/, .svelte-kit/, .turbo/, etc.), generic build/dist outputs, and OS detritus (.DS_Store, Thumbs.db, vim swap files).

dbxignore init                       # writes ./.dropboxignore
dbxignore init ~/Dropbox/proj        # writes ~/Dropbox/proj/.dropboxignore
dbxignore init --stdout              # preview without writing
dbxignore init --force               # overwrite an existing file

The header of the generated file lists which marker-bait directories were detected in your tree at depth ≤ 3 (e.g., # Detected in this tree at depth <= 3: node_modules, __pycache__). All template patterns are emitted as active rules; the header is the cue for which ones are immediately load-bearing. Edit the file afterward to remove patterns that don't apply to your tree.

Applying rules

dbxignore apply runs one reconcile pass — the same operation the daemon performs on every .dropboxignore save and on its hourly recovery sweep. Useful for forcing a one-shot run without waiting for the daemon (or when no daemon is installed).

dbxignore apply --dry-run            # preview what would be marked/cleared
dbxignore apply --yes                # skip the confirmation prompt
dbxignore apply ~/Dropbox/proj       # scope to a subtree
dbxignore apply --from-gitignore ~/Dropbox/proj/.gitignore --yes

A confirmation prompt fires by default and summarizes how many paths will be marked or cleared. Both directions are destructive — see Behaviour for what marker mutations do to cloud sync. Pass --yes for scripted use.

If apply finds nothing to mark and nothing to clear (the steady-state case where the daemon has already converged the tree), it exits with Nothing to apply (rules already in sync). and skips the prompt.

Unlike clear, apply does not refuse to run while the daemon is alive — the daemon performs the same operation continuously, so racing it is normal usage.

Clearing all markers

dbxignore clear walks the watched roots and clears every ignore marker, the inverse of apply. Useful for staging a manual sync change or testing that Dropbox re-syncs previously-ignored content from the cloud. Unlike uninstall --purge, it leaves .dropboxignore rule files and state.json untouched.

dbxignore clear --dry-run            # preview what would be cleared
dbxignore clear --yes                # skip the confirmation prompt
dbxignore clear ~/Dropbox/proj       # scope to a subtree
dbxignore clear --force --yes        # override daemon-alive guard

clear refuses to run when the daemon is alive — the daemon's next sweep would re-apply rule-driven markers within seconds (rule-reload events) or within the hour (recovery sweep tick). Stop the daemon first (dbxignore uninstall) or pass --force for known short-window tests where you'll restart the daemon yourself.

A confirmation prompt fires by default. After the clear, Dropbox starts syncing previously-ignored paths — for a node_modules previously kept out of sync, that's potentially gigabytes of upload, so the prompt is a footgun guard. Pass --yes for scripted use.

Status-bar integration

dbxignore status --summary emits a stable single-line summary on stdout, suitable for status-bar widgets (polybar, tmux, i3blocks, sketchybar) and cron-friendly polling.

The format is part of the public API per SemVer: adding new fields is non-breaking, but renaming or removing existing fields bumps MINOR pre-1.0 / MAJOR post-1.0.

state=<token> [pid=N] marked=N cleared=N errors=N conflicts=N

State tokens:

• running — state.json present and the recorded PID corresponds to a live dbxignore daemon process.
• not_running — state.json present but the recorded PID is no longer a live daemon (cleanly stopped, or stale state).
• no_state — no state.json (daemon never ran). Only state and conflicts are emitted in this case.
• starting — daemon is alive but the initial sweep has not yet completed.

state=starting is emitted when the daemon is alive but the initial sweep has not yet completed. During this window, the summary contains only state and pid — marked, cleared, errors, and conflicts are omitted because they would all be 0 and would falsely imply the daemon swept and found nothing. The transition to state=running happens when the initial sweep completes (a fresh install of a 27,000-directory Dropbox tree took ~50s in testing).

pid=N is omitted when no PID was recorded (rare partial-write case). The remaining fields (marked, cleared, errors) are present whenever a state.json exists, even if the daemon never finished a sweep — they default to zero.

Examples:

state=running pid=12345 marked=7 cleared=1 errors=0 conflicts=0
state=not_running pid=12345 marked=7 cleared=1 errors=0 conflicts=0
state=no_state conflicts=0

A polybar module reading the daemon state could grep state=\S+ for the at-a-glance indicator and errors=\S+ for an error-count badge.

Command parity with git

For users coming from git, this table maps each dbxignore command to its closest git counterpart. Some align cleanly; others have a deceptively-similar git verb with materially different consequences.

Negations and Dropbox's ignore inheritance

Dropbox marks files and folders as ignored using xattrs. When a folder carries the ignore marker, Dropbox does not sync that folder or anything inside it — children inherit the ignored state regardless of whether they individually carry the marker. This matters for gitignore-style negation rules in your .dropboxignore.

A negation can only re-include a path if no strict ancestor directory of that path is marked ignored. The case dbxignore drops is when an earlier rule marks a directory and a later negation tries to re-include something inside that directory:

build/                               # marks the directory build/ itself
!build/keep/                         # ← dropped: build/ is already ignored, inheritance wins

dbxignore detects this at the moment you save the .dropboxignore, logs a WARNING naming both rules, and drops the conflicted negation from the active rule set.

The git-canonical pattern works because it marks only the children of build/, not build/ itself:

build/*                              # marks immediate children
!build/keep/                         # except this one
!build/keep/**                       # re-include everything under it

If you wrote build/ only to except a child, switch the trailing / to /* — the two forms differ (build/ marks the directory itself; build/* does not), so only switch when the negation is the load-bearing reason for the rule.

Other negations that don't conflict with an ignored ancestor work normally. For example:

*.log
!important.log

Here nothing marks a parent directory as ignored (*.log matches files, not dirs), so the negation works — important.log gets synced, the other .log files don't.

Semantic divergence between the two files

A .gitignore says "git doesn't track this file." A .dropboxignore marker tells Dropbox to stop syncing the path and remove it from cloud sync. Most rules transfer cleanly (build outputs, dependency caches, IDE state) — but transplanting a .gitignore verbatim can mark files for cloud removal that you didn't intend to remove. Review the source file before running apply --from-gitignore, or run generate --stdout to preview.

Interaction with the running daemon

If dbxignore daemon is running, writing a .dropboxignore (whether by generate, by hand, or by any other means) triggers a watchdog event. The daemon classifies it as a RULES event, debounces, and reconciles the affected root. End state: the markers are written and Dropbox starts removing matched paths from cloud sync. generate is therefore not a "preview-only" verb when the daemon is running — use --stdout to preview without committing the file.

Negations

A pattern like !build/keep/ (re-include a path under an ignored ancestor) is dropped silently; Dropbox's ignored-folder model does not support negation through ignored ancestors. Use dbxignore explain <path> to see which rule masked a dropped negation.