Work with the files in a synced folder
Add, change, rename, delete, tag and attach the files and notes in a synced folder, and know what each change does to your items.
You and your agents work with a synced folder's files in any app. Each file is an item, and each change you make reaches your instance at the next sync. The examples follow the Home folder from Sync a folder.
Files
A file such as a PDF, a photo or a spreadsheet holds the item's own bytes.
- Add a file and it becomes an item, titled with its file name, such as
water.pdf, and tagged by the folder's defaults. - Put it in a subdirectory, such as
Bills/water.pdf, and it sits there in every directory that follows the folder. - Change a file and the same item gets the change, as a new version.
- Rename or move a file and the item stays the same. Its title follows the new name only if it was the old file name: a title you set yourself stays.
- Names that differ only in case, such as
Plan.mdandplan.md, are one name to a folder, as a Mac's disk compares them. On a disk that keeps them apart, such as most Linux disks, the folder keeps the file it already holds and leaves the other as you wrote it, not sent, until you rename one. - Delete a file and its item moves to the bin, where you can restore it. Many deletions at once wait for you, as Fix a folder shows.
A file has no room for tags, so tag its item from the CLI or an agent, with the ID that marfa search shows:
marfa items tags add 01a1f471-38e8-72d9-a656-9ada7595454a billstagged 01a1f471-38e8-72d9-a656-9ada7595454a; it now has home, billsNotes
A note is a Markdown file. Add one with only a body, such as Ideas.md, and it becomes a note titled Ideas. Marfa then writes its details at the top of the file:
---
type: core.note
tier: library
tags:
- home
title: Ideas
marfa_id: 01a1f471-38fb-76f9-81f4-efc639a26cd8
marfa_version: 1
---
Try the tram.Edit title and tags; leave the marfa_ lines to Marfa. Retitle a note anywhere and the next sync renames its file. A copy of a note under a new name becomes a new note, and two notes with the same title are written as two files, such as Plan (2).md.
Files a folder leaves alone
A folder never takes in a file whose name a secret goes by, such as .env or server.pem, files your computer keeps for itself, such as .DS_Store, temporary files, or links. A push names each secret it leaves out:
server.pem: not taken, because its name is one a secret goes byA name that starts with a period is skipped too, unless the folder's settings include it. A hidden .marfa-kept-<id>.tmp file is one Marfa moved aside while it wrote: it settles it at the next scan, and never deletes it. What a folder takes in lists every name.
Link to another item
Write a link in a note's body with double brackets, naming another item by its title or file name:
Book the room from [[Hotel in Lisbon]], and pack from [[Packing list|the list]].The text after | is what the note shows. A link follows a retitled note, and can name a note that doesn't exist yet. A name that fits several items connects to none, and the sync says so: rename one, or write the item's ID, as in [[01a1f471-38fb-76f9-81f4-efc639a26cd8]].
Attach a file to a note
List the file on the note's has-attachment line:
has-attachment:
- "[[water.pdf]]"An attached file follows its note to the bin and back. Take it off the line and the attachment ends, but the file stays an item. A picture from the folder that you embed in the body, such as , shows in the note and links to the photo, but doesn't attach it.
How a folder treats files has every rule a folder follows.