From 87a710dd852074f0993bd339f6f45c754ae0e1b9 Mon Sep 17 00:00:00 2001 From: Petr Nyc Date: Tue, 29 Sep 2026 22:31:51 +0200 Subject: [PATCH] readme --- README.org | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/README.org b/README.org index 45eed41..ff16265 100644 --- a/README.org +++ b/README.org @@ -44,6 +44,84 @@ - automatically appears in profiles; set it as default and you should be going - TODO - table of defined keys +** BetterTouchTool + +Presets are stored as uncompressed JSON exports in +=~/.config/bettertouchtool/=. Ansible installs BetterTouchTool and checks out +dotfiles on initial setup; it does not import or continuously synchronize BTT +settings. BTT continues to own its live configuration. + +*** Restore on a new Mac + +1. Install and start BetterTouchTool, activate your licence separately, and + grant the macOS permissions requested by BTT. +2. If BTT already has configuration you want to keep, export those presets + before importing anything from dotfiles. +3. Open the Presets interface (top-right preset button) and import + =Default.bttpreset= from =~/.config/bettertouchtool/=. Use Cmd+Shift+G in the + file picker to enter this hidden directory. This export includes BTT's + exportable general settings, including window move/resize preferences. + Allow importing these settings when prompted. +4. Import =clipboard.bttpreset=, =BTT Clipboard Manager.bttpreset= and + =btt-mobile-example.bttpreset= from the same directory. These exports do not + include general settings. +5. Select the imported =Default= as the master preset and enable all four + imported presets to reproduce the source setup. Avoid keeping duplicate + copies enabled; if a preset with the same name already exists, review the + import/replacement prompt rather than blindly adding another copy. +6. Check the window move/resize preferences and test them on an ordinary + window. Test a configured browser gesture (for example, a Firefox TipTap + gesture), and check the clipboard manager and mobile menus if you use them. + Clipboard history is not restored. + +The snapshot was exported from BTT 5.750 on 2026-09-25. The source master is +=Default= (activation state 2); =clipboard=, =BTT Clipboard Manager= and +=btt-mobile-example= have activation state 1. The =clipboard= preset currently +contains app scopes but no triggers; it is retained to preserve the setup. + +*** Update the exports + +After changing BTT settings, export the affected presets again from BTT's +Presets interface to the same filenames. Choose uncompressed JSON; include +general settings only in =Default.bttpreset=. Re-export =Default= when changing +general preferences, even if no shortcuts changed. Preserve the names above +and update this section if the master or enabled presets change. + +Before adding exports to Git, review the diff for passwords, API keys, private +paths, typed-text actions and scripts. Remove =BTTFloatingMenuRenderedPreview= +fields from JSON exports: these are cached menu snapshots, not configuration. +Validate the resulting JSON, for example: + +#+begin_src sh + python3 -m json.tool ~/.config/bettertouchtool/Default.bttpreset >/dev/null + config diff -- .config/bettertouchtool README.org +#+end_src + +New files must be added explicitly with the existing =config= Git alias. +Exports may receive new preset UUIDs, so inspect import prompts on subsequent +restores and ensure only one intended copy of each preset is enabled. +Do not add BTT's Application Support directory, preferences plist, clipboard +database, licences, automatic backups or user-variable stores to Git. + +*** Portability notes + +- App-specific bindings target iTerm2, Finder, Firefox and Microsoft Edge; + install the relevant apps before testing those bindings. The mobile example + also includes Safari actions. Hardware-specific gestures and window geometry + may need adjustment for a different keyboard, pointing device or display. +- No user-specific absolute paths were found in these exports. The mobile + example contains JavaScript menu widgets and a =say hello= shell action; + import only trusted presets and review scripts before enabling them. +- Two custom mobile-menu images are already absent from the source Mac: + =AE909FCE-DACE-4774-823D-36F7C2864EB5-BTTMenuItemImage.png= and + =ED4B7AB4-D7E6-474C-B4A4-7BDCA93F25DB-BTTMenuItemImage.png=. + Their =BTT_PRESET_PATH= references remain in the export, but those icons + cannot be restored from this snapshot. Re-select images in BTT if needed. +- Cached rendered menu previews are intentionally omitted. The clipboard + presets contain configuration only, not copied text or clipboard history. + +See [[https://docs.folivora.ai/docs/configuration/presets][BTT's preset documentation]] for export/import behaviour. + ** fonts For iTerm on mac, the preferred fonts are installed automatically. You can also download fonts like this: