title: $:/plugins/linonetwo/watch-fs/readme
creator: LinOnetwo
type: text/vnd.tiddlywiki

!! About

This plugin enables TiddlyWiki to watch the change in your disk, and if you edit one of your tiddler using editor likes VSCode and save it on the disk, the change will immediately reflected in the browser.

See [[https://github.com/Jermolene/TiddlyWiki5/issues/3060]] for related discussions.

!! [[FileSystemMonitor.js|$:/plugins/linonetwo/watch-fs/FileSystemMonitor.js]]

This module watches the file system in the tiddlers folder and any changes to
the files in the folder that don't come from the browser are reported to the
browser. So if you make a new .tid file in the tiddlers folder it will appear
in the wiki in the browser without needing to restart the server. You can also
delete files to remove the tiddlers from the browser.

!! Installation

Some of the files are generated, but all the files are generated and ready to use in the `watch-fs` folder.

!! Usage

This plugin will cause trouble if you build wiki with it enabled,
so you have to remove it from your `tiddlywiki.info`, and add it to your wiki start arguments:

```shell
tiddlywiki +plugins/tiddlywiki/filesystem +plugins/tiddlywiki/tiddlyweb +plugins/linonetwo/watch-fs <path-to-wiki-folder> --listen
```

(why `+plugins/tiddlywiki/filesystem +plugins/tiddlywiki/tiddlyweb` here? See [[https://github.com/Jermolene/TiddlyWiki5/issues/4484#issuecomment-613200370]] for details)

!!! Liminitation

# can't handle rename in the disk, you can only rename from within the wiki (no such API to tell tw I've renamed a file)
# I haven't tested this with [[$:/config/FileSystemPaths]] and [[Fix file info PR|https://github.com/Jermolene/TiddlyWiki5/pull/4630]] , but I use this feature every day, so I will definitely support it.
# Can't handle if git change the tiddler while you are open its Draft tiddler (might be fixed by [[Deleting a draft tiddler should not also delete the original tiddler|https://github.com/Jermolene/TiddlyWiki5/issues/4792]] )

!!! Using on network share / NFS

If the files are mounted from a remote, you will most likely use polling instead of the OS-native watcher.
This is not done automaticly, since there is really no way for us to detect that.

If your files are on a remote, you should set the environment-variable `CHOKIDAR_USEPOLLING=1`.
You can also configure the polling interval (default 100ms) using `CHOKIDAR_INTERVAL`.

!! Implementation Details

!!! How to decide whether a change is comes from the browser?

We will compare disk file and wiki file, if there is any discrepancy,
then we know the change is not made from the wiki, it is made by git or VSCode, in this case we read data from the disc,
and add data to the tiddlywiki.

!!! How to sync changes to the browser?

we can't trigger sync from the server, so we have to set a smaller sync interval in the client side.

So this plugin ship with a large [[$:/config/SyncPollingInterval]] to disable the build-in sync,
and we add a new route `/linonetwo/watch-fs-can-sync` to the simple server, it will return `true` or `false`,
and browser will poll this route, to see if it needs to trigger a `$tw.syncer.syncFromServer()`.
