In our web based plugin editor, clicking Save overwrites all markup and settings. The inline undo button can help with accidental changes, but it's limited to your browser history.

For better versioning over time, git is the gold standard, and GitHub (90% uptime) is a great place to host plugin data.

Syncing is automated from TRMNL → GitHub, and manual from GitHub → TRMNL.

Inside TRMNL > Plugins > Private Plugins, scroll down the right side margin of any given settings instance.

Here you can click the GitHub icon to be walked through the syncing process and select (or create) a dedicated repository for your plugin's data.

The connect form also has an optional Folder in the repository field. Leave it blank when the repository holds one plugin, and TRMNL writes to the repository root. Name a folder such as plugins/clock to keep several plugins in one repository, and this plugin writes to plugins/clock/src/ instead.

You may disconnect at any time.

How often does TRMNL sync with GitHub?

Whenever you click Save on a plugin settings form or the markup editor, the TRMNL Sync app will trigger a git commit. These are debounced by ~15 seconds, so multiple saves within that period will be combined in 1 commit.

What happens if the GitHub repo is updated?
The TRMNL Sync app subscribes to "push" events and will surface the option to import the latest changes from GitHub.

When several plugins share a repository, only the plugins whose own files changed are offered the import. Force pushes are the exception, along with pushes of 20 commits or more, because GitHub stops listing every changed path at that point. When the event cannot say what changed, every plugin in the repository is flagged.

How does this help with collaboration?

Any published or unlisted plugin in the marketplace that is synced to a public GitHub repo will include a couple links which point to the repository homepage and Issues generator.

Is this feature compatible with trmnlp?

Yes, you can continue push/pull development with our trmnlp local development suite. The same repository you use for trmnlp source code can be connected with GitHub Sync, as the same archiver utility is used to parse the code.

On the first push, TRMNL also writes a .trmnlp.yml beside your plugin, at the repository root or inside its folder. trmnlp refuses a directory that has no config file, so this is the piece that makes trmnlp serve work on a fresh clone. If you already keep your own .trmnlp.yml there, we leave it alone. In a repository holding several plugins, run trmnlp serve from inside the plugin's folder.

What if a TRMNL team member changes my plugin settings a synced repository?

Sometimes while reviewing plugins that have been submitted for publication, we are granted permission by the author (you) to tweak their code or settings. In this case, a synced repository will showcase that commit with [admin team] appended to the commit message.

Is it possible to sync multiple plugins to a single GitHub repository?

Yes. Give each plugin its own folder in the Folder in the repository field when you connect it. A plugin in plugins/clock keeps its markup and settings in plugins/clock/src/, and importing from GitHub reads that same folder back.

One folder belongs to one plugin. If you name a folder another plugin in that repository already uses, the connect form refuses it. A blank folder is a claim on the repository root, so only one plugin per repository can sit there. The seeded README is written for that root plugin only.

If you had already pointed several plugins at one repository root, they were overwriting each other, and only one of them ever heard about changes on GitHub. We have moved all but the most recently synced one into folders named after the plugin. Nothing was removed from GitHub. Check the folder on each plugin's sync card before your next save, and move the files on GitHub if you want them somewhere else.