[INIT]

README.md

@@ -0,0 +1,50 @@
+# merged-repl-plugin
+
+Neovim plugin that synchronizes a REPL repository with a main repository and provides a Perl REPL workflow inside Neovim.
+
+Features
+- Automatic synchronization of REPL repo branches with main repo (polling-based)
+- `:REPL` command to open the REPL session file
+- `:RUN` command to execute the REPL script and show output in a readonly buffer
+- Auto-commit of REPL repo changes by default
+
+Defaults
+- `auto_commit = true` (auto-commit changes in REPL repo if dirty)
+- `output_target = 'buffer'` (REPL output appears in an in-editor readonly buffer)
+- `auto_start = false` (sync timer not started automatically)
+
+Installation
+1. Place the `lua/` directory inside your Neovim config or as part of a plugin path.
+2. In your `init.lua` add:
+
+```lua
+require('merged-repl-plugin').setup{
+  main_repo_path = '/path/to/main/repo',
+  repl_repo_path = '/path/to/repl/repo',
+  repl_file = '/path/to/repl/repo/repl.pl',
+  auto_commit = true, -- default
+  output_target = 'buffer', -- default
+  auto_start = false, -- default
+}
+```
+
+Usage
+- `:REPL` — open the configured `repl.pl` file for editing
+- `:RUN` — save and run `repl.pl`; output streams to a buffer called `REPL Output: <repo-name>`
+- `require('merged-repl-plugin').start_auto_sync()` — start automatic polling for branch changes
+- `require('merged-repl-plugin').stop_auto_sync()` — stop automatic polling
+
+Testing
+- A basic integration test script is provided at `tests/run_tests.sh`.
+- Run it from the project root: `./tests/run_tests.sh`
+
+Notes & Caveats
+- The plugin performs Git operations (add/commit/checkout). `auto_commit` will create commits automatically using the repo's configured Git author.
+- The plugin runs Git and Perl via asynchronous jobs to avoid blocking the editor, but operations may still fail due to hooks or merge conflicts — the plugin will notify and leave repositories unchanged in those cases.
+- `auto_start` is `false` by default to avoid surprising behavior. Call `start_auto_sync()` when you're ready to enable automatic syncing.
+
+Contributing
+- Feel free to open PRs for improvements: add `auto_stash` behavior, enable file-based output for headless environments, or enhance logging.
+
+License
+- MIT