Migration Decision Worksheet
A four-step worksheet for migrating a single-user workflow off Dropbox.
2026-05-07 16:11 PDT
This worksheet is the companion to the blog post ‘Migrating Off Dropbox: Beyond Dotfiles’. It walks through four steps: inventory, mechanism selection, migration order, and verification. Fill it in for your own setup; the result is a concrete migration plan whose moves are small and auditable.
The worksheet is layer-agnostic in the sense that it does not assume any particular sync mechanism. The choices it surfaces depend on the reader’s tolerance for new tools, willingness to host their own infrastructure, and constraints on cost and bandwidth.
1 Step 1: Inventory
List every sync-relevant artefact in $HOME and ~/Dropbox/ (or ~/Library/CloudStorage/Dropbox/). Classify each into exactly one of three layers.
1.1 Layer 1: Configuration (dotfiles)
These are files whose content is small, changes infrequently, is nearly always edited from a single machine, and benefits from version history.
These belong in the dotfiles repository established by post 24. If they are not there yet, the rest of the worksheet should wait; post 24 is the prerequisite.
1.2 Layer 2: Project content
These are directories holding research repositories, datasets, drafts, archives, and shared resources.
For each directory above, decide whether it splits further into ‘code’ (wants git) and ‘data’ (wants something else). Many readers find that prj/ is mostly code, docs/ is mixed, and shr/ is mostly data.
1.3 Layer 3: Append-only history
These are files written by tools that append rather than overwrite. Cloud sync handles them poorly.
If you are on a single machine and have never seen a ‘conflicted copy’ file, this layer’s payoff is small and you may skip it. If you have, this is where most of the friction lives.
1.4 Items NOT in any layer
Some files at $HOME are neither configuration nor project content nor history: caches, runtime state from individual applications, secrets. These are explicitly out of scope for this worksheet.
~/.cache/,~/Library/Caches/— regenerable; do not sync~/.aws/,~/.ssh/,~/.gnupg/,~/.password-store/— secrets; hand-installed per machine, never in any sync mechanism~/.docker/,~/.npm/,~/.lmstudio/— application state; treat as machine-local
2 Step 2: Mechanism Selection
For each layer, pick a sync mechanism. The choice depends on what the layer’s items actually need.
2.1 Layer 1: Dotfiles
Default: git remote (private repo). Use the dotfiles repository established by post 24. No alternative is competitive for this layer.
2.2 Layer 2: Project content
Decide for each subcategory below. Most readers will end up with two mechanisms (one for code, one for data).
2.2.1 Code (text-heavy, version-history-valuable)
2.2.2 Data (binary, large, often immutable)
2.2.3 Per-project decision
For each project directory listed in Step 1, write down:
- Code mechanism: ____________________
- Data mechanism: ____________________
- Excludes (
.gitignore,.stignore, etc.): ____________________
2.3 Layer 3: Append-only history
3 Step 3: Migration Order
Sequence the moves so the backup pipeline never points at a stale source path and the workflow is functional at every intermediate step.
| Step | Action | Why now |
|---|---|---|
| 1 | Confirm post 24’s dotfiles repo works on a clean account or VM | Foundation for everything else |
| 2 | Add PRJ_ROOT env var to ~/.zshenv; resolve to current Dropbox path |
Indirection lets the rest of the moves be one-line edits |
| 3 | Replace literal ~/Dropbox/prj references in scripts and configs with $PRJ_ROOT |
Same: indirection now, behaviour later |
| 4 | Move one pilot project to ~/prj/<project>/ (real path, outside cloud) |
Verifies the new mechanism in isolation |
| 5 | Push pilot to its chosen remote (per-project git, Syncthing folder, etc.) | Confirms the chosen mechanism end-to-end |
| 6 | Migrate the rest of project content, in batches | Bounded blast radius; backup pipeline never goes stale |
| 7 | Repoint $PRJ_ROOT to the new path |
The single switchover moment |
| 8 | Update backup scripts (backup-gdrive, backup-icloud, etc.) to source from $PRJ_ROOT |
Backup pipeline now follows the workflow |
| 9 | Apply the chosen Layer 3 strategy (per-machine, single-writer, or append-aware) | History is the last move because it has the least leverage |
| 10 | Verify on a clean account or VM | The end-to-end test that catches every assumption |
| 11 | Optional: uninstall Dropbox | Most readers skip this; Dropbox staying installed is fine |
The key invariant: at every step, the workflow on the current laptop continues to function. If you stop after step 4, you have a pilot. If you stop after step 8, you have full project-content independence and can defer history decisions indefinitely.
4 Step 4: Verification
The migration is complete when all four checks pass.
5 Notes
- This worksheet does not generate scripts. The reader still has to write the rclone or rsync command for their setup. The blog post body has worked examples for the most common cases.
- The mechanism table is current as of 2026-05; new entrants (Filen, S3-backed clients, etc.) may shift the optimal choice.
- The worksheet is layer-agnostic but assumes a single user. Team setups have an additional concern (the shared folder) that this worksheet does not address.
Rendered on 2026-05-07 at 16:11 PDT.
Source: ~/Dropbox/prj/qblog/posts/64-migrating-off-dropbox/migrating-off-dropbox/docs/migration-decision-worksheet.qmd