Change or stop syncing a folder

Make a folder hold only some items, leave some files alone, pause it for a while, stop following it in one directory, or retire it everywhere.

A folder's settings live on your instance, so a change reaches every directory that follows the folder. Stopping never deletes an item. The examples use the Home folder in ~/Documents/Home, from Sync a folder.

Hold only some items

Edit .marfa/folder.yaml in any directory that follows the folder, and the next sync sends the change. Leave folder and version to Marfa.

Home/.marfa/folder.yaml
folder: 01a1f46f-bed0-7310-bb7c-840868eb64ac
version: 1
title: Home
query:
  types:
    - core.note
    - core.file
  filter: "tags contains \"home\""
defaults:
  tags:
    - home
ignore:
  - drafts/
  • query says which items the folder holds: here notes and files tagged home.
  • defaults says what a new file gets when it doesn't say, here the tag home.
  • ignore lists the paths the folder leaves alone, in the form .gitignore takes.

To clear a setting, empty its value: a setting you delete from the file is refused. While the first sync waits for you, the file isn't read, so change the settings with marfa folders update instead, as the folder type shows with every setting.

What a narrower or wider query does

  • Items the query now holds are written as new files. Widening a query can write many.
  • Items it no longer holds keep their files, which go on syncing. Nothing moves to the bin. Two directories that follow this folder on one computer each keep their own file, and when the query widens again each writes its own.

To take those files away, list them, then remove them. Their items stay as they were:

Terminal
marfa folders unmatched ~/Documents/Home
1 unmatched file(s), 1 of them removable with `folders unmatched --remove`
Tram.md

marfa folders unmatched ~/Documents/Home --remove asks first, and keeps a file you've changed since the folder wrote it. Use it rather than your file manager: deleting a file by hand moves its item to the bin.

Stop syncing for a while

There's no pause command yet: between pushes, a folder syncs only while a watch runs. Run marfa folders autostart off to stop the watch, and every folder on the computer with it. Edit the files meanwhile if you like: when you turn autostart on again, the watch sends your changes and takes in what changed elsewhere.

To stop one folder and keep the others syncing, stop following it in its directory, and add it again later.

Stop following in one directory

Run marfa folders push ~/Documents/Home first, so no edit stays only on disk, then:

Terminal
marfa folders remove ~/Documents/Home
/Users/sam/Documents/Home is no longer a folder; its files stay

The files stay as plain files that no longer sync, and other directories go on. remove is refused while edits wait to be sent. marfa folders add with the folder's ID follows it again: each note, and each file you haven't changed since, rejoins its item, and a file you changed comes back as a new item.

Retire a folder everywhere

A retired folder's items stay, but no directory can sync it again, so send every edit first:

  1. In each directory that follows the folder, run marfa folders push.
  2. Run marfa folders revoke with the folder's ID.
  3. In each directory, run marfa folders remove to keep its files as plain files.

A directory you miss says so at its next sync:

marfa: the folder 01a1f46f-bed0-7310-bb7c-840868eb64ac is revoked, and a revoked folder has no settings to follow

On this page