Skip to main content
Concept · files

Use when

The person wants a collection to follow a folder, a vault or a notes account, or you must check, pause or stop one.

Looking for something else?

One-off uploads of documents (recipe bring-in-a-corpus). A newer copy of one document (recipe new-edition). Grouping Files without a folder behind them (card collection).

​
For

A synced folder ties one collection to a place that keeps its own documents. The place is a folder or Obsidian vault on a computer, a folder in Google Drive, or the notes of a Granola account. Penumbra brings each document in as a File. A change in the folder becomes a new version of the same File. A renamed document keeps its File. A deleted document goes to Trash. The folder is the authority. Its Files read as ordinary Files, with versions, passages and search, but Penumbra refuses to change them. To change one, change the document in its folder, or stop syncing.

​
Use when

  • The person has a folder, a vault or a notes account that changes, and wants Penumbra to follow it.
  • You must see whether a synced folder is up to date, and what its last run changed.
  • A File refuses a change and says it is kept in sync with its folder.
  • The person wants to pause, resume or stop syncing.

​
Not this

  • Documents that you add once: use recipe bring-in-a-corpus.
  • A newer copy of one document: use recipe new-edition. A synced File takes its new editions from the folder (rule source.1).
  • Files that you group by hand: use a collection (card collection).

​
Rules

  1. source.1 The folder wins. Enforced: a change to a synced File is refused with file_write_constrained and exit code 3. The refusal covers penumbra files replace, penumbra files trash, edits and a move to another folder. The folder owns the File’s name and path. A rename in the same folder (penumbra files move) is not refused. It sets the File’s title (card file, rule file.12). The name and path stay the folder’s, so a note’s [[link]] to the File still resolves. Your job: change the document in its folder and sync again, or stop syncing (rule source.9). Do not work around the refusal by uploading a copy: the project then holds two editions (problem two-editions-two-files).
  2. source.2 Syncing has three kinds, and each has its own start. Your job: for a folder or vault on this computer, run penumbra sync <folder>. For Granola, run penumbra sources connect granola, then penumbra sources link granola --all or --folder <folder-id>. A Google Drive folder can only be started in the App.
  3. source.3 Plan before you apply. Your job: run penumbra sync <folder> --dry-run. It prints what is new, changed, renamed and removed, what it skips, and a plan id. Show the person the removals. Enforced when you ask: penumbra sync <folder> --plan <plan-id> applies that plan, and refuses if the folder changed since.
  4. source.4 Some files are never sent. Enforced: a sync skips the Obsidian settings folder, .git, the .penumbra folder and other hidden files. It also skips symlinks that lead outside the folder, and unsafe names. The plan counts them under “skipped”.
  5. source.5 The first sync ties the folder to a collection, and later syncs send only what changed. Your job: name the collection with --collection "<name>". Without it, Penumbra uses or makes one named after the folder.
  6. source.6 A large removal needs a decision. Enforced: a sync that removes every file, or over half of the files when that is more than 25, is refused. The code is removal_review_required, the exit code is 3, and nothing is sent. Your job: read the list with --dry-run, ask the person, and only then run again with --allow-removals.
  7. source.7 A removal goes to Trash and can be restored. Enforced: a deleted document leaves the collection as a File in Trash, not as a purge. Penumbra removes nothing from a list it could not read completely. A Google Drive folder that Penumbra can no longer read keeps its Files, marked as possibly out of date.
  8. source.8 A run is done when its status says so. Your job: run penumbra sources status <source>. Tell the person the folder is current only when the latest run succeeded and the status says “Up to date” and “All searchable”. Penumbra cannot see a folder on a computer between syncs, so its status says “Last synced” with the time instead. Tell the person that time, never that the folder is current. penumbra sync <folder> brings in changes made since. penumbra sources changes <source> lists what the run added, changed, renamed, removed and skipped.
  9. source.9 Stopping and pausing differ. Enforced: penumbra sources pause stops new content and keeps the Files read-only, and penumbra sync of a paused folder is refused with source_paused. penumbra sources disconnect ends syncing for good, asks to confirm, and releases the Files as ordinary editable Files. Without a terminal it needs --yes, or it exits with confirmation_required and changes nothing. Your job: tell the person that changes in the folder stop arriving.
  10. source.10 Syncing the same folder again picks up where it ended. Enforced: penumbra sync <folder> after a stop uses the folder’s earlier collection and matches a File at the same path with the one already there. Files added in Penumbra while syncing was off stay as they are.
  11. source.11 Synced folders belong to a person. Enforced: a key or a connected agent that runs penumbra sources list, penumbra sync or any other synced-folder command is refused with human_session_required. Members read synced folders. Owners and admins change them.
  12. source.12 Access can be lost. Your job: when penumbra sources status shows a Drive folder or a Granola key that no longer works, tell the person. Nothing was deleted. For Drive, the person reconnects in the App under Synced folders: open the folder and choose Reconnect Google Drive. For Granola, run penumbra sources connect granola, then penumbra sources reconnect <source>.
  13. source.13 A Granola key is a secret. Enforced: the command penumbra sources connect granola has no argument for the key. It asks with nothing shown on screen, or reads it from stdin with --key-stdin. Your job: never ask the person to paste a key into the chat.

​
Failure signs

  • A File refuses a change and says it is kept in sync with its folder: rule source.1.
  • A sync exits with removal_review_required: rule source.6.
  • A sync exits with source_paused: rule source.9.
  • Search shows the old text after the folder changed: the last run is not done (rule source.8). Or a new File is not ready yet (problem new-file-not-searchable-yet).
  • Two copies of one document: problem two-editions-two-files.

​
Doors

penumbra sources sync <source> starts a run of a Google Drive or Granola folder now. A folder on a computer syncs only with penumbra sync <folder>. The person connects Google Drive in the App under Synced folders, and chooses Connect Google Drive.

​
The CLI word

The CLI calls a synced folder a source. This is not the source of a citation or the source date (card passage, card file).

​
HTTP reference

​
Keep going

Collection · File · Bring a set of documents into the project · Bring in a new edition of a document · A new edition is a separate File · Identical bytes make no new version · A File has no source date