rex-worktrees 0.4.0 → 0.4.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -107
- package/dist/rex-worktrees +1 -1
- package/dist/rex-worktrees.js +310 -422
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,173 +1,123 @@
|
|
|
1
1
|
# Rex Worktrees
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A keyboard-driven [Rex](https://www.superlogical.com/rex/docs) plugin for opening and creating **Git worktrees** and **Jujutsu (JJ) workspaces**. Pick a project, machine, checkout, and session; it opens a shell there. No agent or model required.
|
|
4
|
+
|
|
5
|
+
<img width="693" height="236" alt="image" src="https://github.com/user-attachments/assets/fadd8e3c-30fc-4f94-98ca-41132a23ff36" />
|
|
4
6
|
|
|
5
7
|
## Install
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
Requires Rex and its CLI, a running Rex server, and Git 2.42+. JJ projects also need Jujutsu 0.46+. Standalone builds support Apple Silicon macOS 15+ and Linux x64; no Bun runtime is needed.
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
**Install or update on macOS (Apple Silicon):**
|
|
10
12
|
|
|
11
13
|
```sh
|
|
12
14
|
npm install -g rex-worktrees
|
|
13
|
-
rex-worktrees setup
|
|
15
|
+
rex-worktrees setup
|
|
14
16
|
rex config reload
|
|
15
17
|
```
|
|
16
18
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
### GitHub Releases
|
|
19
|
+
npm installs the CLI; `setup` registers the Lua plugin with Rex and copies its executable to `~/.local/bin/rex-worktrees` for the plugin to use. No executable path is needed. Run setup from a shell that can find `rex`, `git`, and optionally `jj`; unrelated Rex settings are preserved. Repeat all three commands to update.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
**Without npm / Linux:** download your platform's archive from [GitHub Releases](https://github.com/samuelho-dev/rex-worktrees/releases/latest), verify it against `SHA256SUMS`, and extract it. From the extracted directory:
|
|
22
22
|
|
|
23
23
|
```sh
|
|
24
|
-
|
|
25
|
-
rex config reload
|
|
24
|
+
./rex-worktrees setup && rex config reload
|
|
26
25
|
```
|
|
27
26
|
|
|
28
|
-
|
|
27
|
+
Setup copies the executable to the same stable location, so the extracted directory is not needed afterward. `setup --bin /absolute/path/to/rex-worktrees` is only for keeping an executable at a custom or package-managed location.
|
|
29
28
|
|
|
30
|
-
|
|
29
|
+
## Use
|
|
31
30
|
|
|
32
|
-
|
|
31
|
+
Open **Open Worktree…** from the Rex palette, or run:
|
|
33
32
|
|
|
34
33
|
```sh
|
|
35
|
-
|
|
36
|
-
bun run build
|
|
37
|
-
./dist/rex-worktrees setup
|
|
38
|
-
rex config reload
|
|
34
|
+
rex do worktrees_open
|
|
39
35
|
```
|
|
40
36
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
37
|
+
1. **Project:** select a discovered project or type an absolute repository path.
|
|
38
|
+
2. **Machine:** choose this machine or an existing Rex host.
|
|
39
|
+
3. **Checkout / Workspace:** select an existing checkout, or type a new Git branch or JJ workspace name. New JJ workspaces also need a **Start from** revision; a valid `trunk()` is selected automatically.
|
|
40
|
+
4. **Session:** select an existing session, or type a name to create one.
|
|
41
|
+
5. Choose **Open / Create / Clone** or press **Ctrl+S** from the form.
|
|
46
42
|
|
|
47
|
-
|
|
43
|
+
**Mode** reuses a matching tab by default; choose a new tab or split instead. New Git checkouts can have a custom **Directory** name, separate from the branch.
|
|
48
44
|
|
|
49
|
-
|
|
45
|
+
| Key | Action |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| Tab / Shift+Tab | Move between fields and buttons |
|
|
48
|
+
| ↑ / ↓ | Navigate fields or choices |
|
|
49
|
+
| Enter | Edit a field, accept its value, or activate a focused button |
|
|
50
|
+
| Ctrl+S | Submit the form; inside an editor, only accept that field |
|
|
51
|
+
| Esc | Leave the editor, or close the form |
|
|
52
|
+
| PageUp / PageDown | Scroll long details |
|
|
50
53
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
```sh
|
|
54
|
-
rex do worktrees_open
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
No keyboard shortcut is installed by default. To add one, put an unused native binding outside the managed section of your Rex config:
|
|
54
|
+
Optional shortcut—add outside the managed section of your Rex config, then reload:
|
|
58
55
|
|
|
59
56
|
```lua
|
|
60
57
|
rex.bind("ctrl+alt+w", "worktrees_open")
|
|
61
58
|
```
|
|
62
59
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
The chooser is one flat form: **Project**, **Machine**, **Checkout** (or **Workspace**), **Session**, and **Mode** for an ordinary open. Only applicable fields appear; there is no Options menu. Machine is always explicit:
|
|
66
|
-
|
|
67
|
-
- **Project:** select a known Git or JJ project, type a project name, or enter an absolute repository path. Linked checkouts appear under their canonical project. After an explicit project selection, the inspected checkout on the chosen machine is selected by default when available; a same-named directory on another host is never assumed to be that checkout.
|
|
68
|
-
- **Machine:** select this machine or an existing Rex host. Changing machines keeps the logical project choice but clears host-bound checkout, base, clone destination, and session bindings; select or enter an actual project directory on the destination. The selected machine appears immediately with a disabled loading form while its connection and project choices are fetched; previous-machine checkout and session choices are not available during the wait.
|
|
69
|
-
- **Checkout / Workspace:** Git offers exact existing checkout paths and branches together. Selecting a checkout opens that path; typing a branch name attaches a free branch or creates that branch and its checkout, while an occupied branch opens its existing checkout. Typed branch text is never a directory name. For a new Git branch, the form also shows **Directory**, an independent optional checkout directory name; select **Use default** to clear a custom name. JJ offers registered workspaces, including unavailable locations (visible but not openable), or a name for a new workspace. New JJ workspaces show **Start from**; an existing JJ workspace opens unchanged without it.
|
|
70
|
-
- **Clone to:** when cloning a project, the form displays the literal absolute destination path; editing it changes only that destination. **Branch** (Git) or **Start from** (JJ) and an optional separate **Directory** (Git) or **Workspace** (JJ) name are visible on the same form. A Git clone without a default branch requires a branch choice. Select **Use default** to clear the optional checkout name; typing `none` is a literal name, not a clearing command. A project name unsafe as a directory requires an absolute destination. Destination collisions and writability errors appear on submit without opening a task, and the destination remains editable.
|
|
71
|
-
- **Session:** select an existing session by its exact ID, or type a name to create a new session on the selected machine. A typed name remains new even if an existing session has the same label; the form shows **New: NAME** before submission. An empty session list still permits typing a name. Names must be nonblank, at most 128 characters, and contain no ASCII control characters.
|
|
72
|
-
|
|
73
|
-
**Mode** for an ordinary open reuses a matching live tab, opens another tab, or splits a matching task; a split without a matching task opens a new tab. Cloning always starts a new tab, so it has no Mode field. New JJ workspaces default **Start from** to the repository-configured `trunk()` mainline when it resolves to one valid commit; otherwise choose a source candidate or type a singular revision. A selected bookmark or revision overrides the default and pins its full commit ID without changing the entered workspace name. A JJ clone can use its native default or select/type a source revision resolved on the source machine. Bookmarks are optional and never created automatically. Source-only unpublished JJ changes and unpushed Git branches are unavailable to a destination clone.
|
|
74
|
-
|
|
75
|
-
Use arrows or `j`/`k` to move, Tab/Shift+Tab to change fields, and Enter to edit or select the form action. In an editor, Enter or Ctrl+S **only accepts that field** and returns to the form; it never reviews or launches. Submit explicitly from the form: the first submit validates the current plan and opens or creates the selected checkout, JJ workspace, clone, or new session when there is no warning. A warning, display limitation, or reviewed path differing from an explicitly selected existing checkout shows the actual plan and requires another submit; if a previously reviewed plan changes, its updated destination or target is shown and must be submitted again. Clone validation includes the source URL and destination; only pushed history transfers. No agent or model is required; the task opens a shell.
|
|
60
|
+
### Add projects
|
|
76
61
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
## Projects and checkout locations
|
|
80
|
-
|
|
81
|
-
Configuration is optional and belongs in the **execution machine's Rex `init.lua`**, in the managed registration installed by setup:
|
|
62
|
+
Without configuration, the current pane's repository is suggested. To list more projects, edit the existing registration in your Rex `init.lua`, then run `rex config reload`:
|
|
82
63
|
|
|
83
64
|
```lua
|
|
84
|
-
-- BEGIN rex-worktrees
|
|
85
65
|
require("rex-worktrees").setup({
|
|
86
|
-
projects = {
|
|
87
|
-
"/absolute/path/to/project",
|
|
88
|
-
{ path = "/absolute/path/to/another-project", worktreeRoot = "/absolute/path/to/another-project-checkouts" },
|
|
89
|
-
},
|
|
66
|
+
projects = { "/absolute/path/to/project" },
|
|
90
67
|
roots = { "/absolute/path/to/projects" },
|
|
91
|
-
worktreeRoot = "/absolute/path/to/checkouts",
|
|
92
68
|
})
|
|
93
|
-
-- END rex-worktrees
|
|
94
69
|
```
|
|
95
70
|
|
|
96
|
-
`projects`
|
|
97
|
-
|
|
98
|
-
Setup leaves user-owned `setup({...})` settings untouched on upgrades, whether inside or outside the `-- BEGIN rex-worktrees` markers; it never appends a second registration to an existing unmarked `require("rex-worktrees")` configuration. Its installed binary path lives in the managed module, so no `bin` setting is needed. An explicit `bin` option overrides that installed path. After editing `init.lua`, run `rex config reload` on that machine. A default setup invocation migrates the former `${XDG_CONFIG_HOME:-~/.config}/rex-worktrees/config.json` to native Lua settings, resolving relative paths against the old JSON directory. Only after native installation succeeds does it remove `config.json`, any old `config.json.backup`, and the old directory if empty; other files in that directory are untouched. If user-owned Lua registration conflicts with legacy JSON, setup stops before making changes: transfer the legacy values into your registration, back up and remove the JSON file yourself, then rerun. `setup --config` targets an explicit Rex init and never migrates or removes the current user's JSON file. Runtime association state remains separate at `${XDG_STATE_HOME:-~/.local/state}/rex-worktrees/associations`.
|
|
99
|
-
|
|
100
|
-
For a popup launched from a Rex pane on this machine, the chooser checks that exact pane's reported directory (a local OSC 7 `file://` URI or absolute path). If that directory is absent or its URI is not trusted as local, it uses the same verified pane's foreground process `cwd` when available. A remote pane or foreign URI is never treated as a local path. Context can legitimately be absent if the pane has no usable local directory, or the directory is not inside a Git or JJ repository; select or enter a project in that case. `--no-context` explicitly disables origin discovery.
|
|
101
|
-
|
|
102
|
-
New checkout location follows this order: a project's `worktreeRoot/<name>`, the global `worktreeRoot/<primary-project-name>/<name>`, or, by default, a sibling `<main-checkout>.worktrees/<name>`. `~` refers to the destination user's home; relative paths resolve against that machine's Rex config directory (the directory containing `init.lua`). Checkout locations must be outside existing checkouts and version-control metadata. Collisions and escaping paths are rejected rather than renamed. JJ's own `git.colocate` setting governs whether its workspace also has Git metadata; the helper does not emulate colocation.
|
|
103
|
-
|
|
104
|
-
## CLI
|
|
105
|
-
|
|
106
|
-
```sh
|
|
107
|
-
rex-worktrees popup
|
|
108
|
-
rex-worktrees launch-popup --session session:FULL-ID
|
|
109
|
-
rex-worktrees launch-popup --session session:FULL-ID --host workstation
|
|
110
|
-
|
|
111
|
-
rex-worktrees open --repo /absolute/path/project \
|
|
112
|
-
--branch feature/name --worktree-name feature-task \
|
|
113
|
-
--session session:FULL-ID --name Feature
|
|
71
|
+
Both settings are optional. `projects` lists repositories explicitly; `roots` discovers them up to two directory levels deep. New checkouts default to a sibling `<repository>.worktrees/<name>` directory. Set `worktreeRoot` globally or on a project object (`{ path = "…", worktreeRoot = "…" }`) to override it. Setup preserves these settings on upgrades and migrates the former JSON configuration.
|
|
114
72
|
|
|
115
|
-
|
|
116
|
-
--worktree /destination/path/existing-checkout \
|
|
117
|
-
--session session:DESTINATION-ID --name Existing
|
|
73
|
+
### Other machines
|
|
118
74
|
|
|
119
|
-
|
|
120
|
-
--revision 'main@origin' --worktree-name task \
|
|
121
|
-
--session session:FULL-ID --name Task
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Standalone CLI invocations obtain settings from the execution machine's native `worktrees_config` Rex action; register `require("rex-worktrees").setup(...)` there and reload Rex first. An unregistered action is an error, not a fallback to the former JSON file. The popup and Rex action paths pass those settings directly to the destination helper.
|
|
125
|
-
|
|
126
|
-
`popup` runs the chooser in the invoking terminal; `launch-popup` opens its floating UI in the source Rex window. For `launch-popup` from an external terminal, supply `--session`; inside Rex, the originating session is available automatically. The `worktrees_open` shortcut delegates to the originating Rex server when invoked from a remote tab, so its popup and helper run on that machine. `launch-popup --host` keeps the UI on the caller's server while selecting another execution host. `--host` accepts an existing Rex host label or registry ID; find exact destination session IDs with `rex -S HOST ls --json`. `open --session` still requires an existing exact ID; new-session naming is available in the popup. Remote `--repo` and `--worktree` paths must be absolute paths on the destination.
|
|
75
|
+
Install and run setup on each execution machine, with matching plugin versions and local Git/JJ tools. Connect the host through Rex first. Paths and configuration belong to the selected machine.
|
|
127
76
|
|
|
128
|
-
|
|
77
|
+
The chooser can clone a known project to another directory or host. Only pushed history transfers—not uncommitted work, unpublished changes, or credentials. Cross-host execution and cloning are experimental; live remote Linux destinations have not been verified.
|
|
129
78
|
|
|
130
|
-
## Safety
|
|
79
|
+
## Safety
|
|
131
80
|
|
|
132
|
-
|
|
81
|
+
- Existing checkouts open unchanged. The plugin does not switch, reset, stash, clean, or delete your work.
|
|
82
|
+
- **Creating a JJ workspace runs `jj workspace add`, which may snapshot its source workspace.**
|
|
83
|
+
- Closing the chooser or a tab does not delete a checkout or stop an already-submitted task.
|
|
84
|
+
- If a launch times out or says **needs inspection**, inspect the destination and session before retrying; a task may already exist.
|
|
133
85
|
|
|
134
|
-
|
|
86
|
+
## CLI and development
|
|
135
87
|
|
|
136
|
-
|
|
88
|
+
Run `rex-worktrees --help` for direct `open` commands and host/session options. `rex-worktrees popup` runs the chooser in the current terminal.
|
|
137
89
|
|
|
138
|
-
|
|
90
|
+
Build from source with Bun 1.3.13:
|
|
139
91
|
|
|
140
92
|
```sh
|
|
141
|
-
bun install
|
|
93
|
+
bun install --frozen-lockfile
|
|
142
94
|
bun run check
|
|
143
95
|
bun run test
|
|
144
96
|
bun run build
|
|
97
|
+
./dist/rex-worktrees setup
|
|
98
|
+
rex config reload
|
|
145
99
|
```
|
|
146
100
|
|
|
147
|
-
|
|
101
|
+
Source-build setup installs to `~/.local/bin/rex-worktrees`. To uninstall, remove the `BEGIN rex-worktrees` / `END rex-worktrees` section and adjacent `rex-worktrees.lua` from your active Rex config (`rex config check --json`), remove the executable, and reload. Repositories are retained.
|
|
148
102
|
|
|
149
|
-
|
|
103
|
+
Releases publish the tested macOS archive to npm through GitHub Actions OIDC, then verify registry version and tarball integrity. The npm trusted publisher must authorize `samuelho-dev/rex-worktrees`, workflow `release.yml`, for direct publishing; no npm token is used. Tag a matching package version (`vX.Y.Z`) to release.
|
|
150
104
|
|
|
151
|
-
|
|
152
|
-
<summary>Rebuilding with a modified runtime</summary>
|
|
105
|
+
## License
|
|
153
106
|
|
|
154
|
-
|
|
107
|
+
[MIT](LICENSE). Standalone builds embed Bun; see [third-party notices](licenses/THIRD-PARTY-NOTICES).
|
|
108
|
+
|
|
109
|
+
<details>
|
|
110
|
+
<summary>Runtime sources and rebuilding</summary>
|
|
155
111
|
|
|
156
|
-
|
|
112
|
+
Release archives include the relinkable `rex-worktrees.js` bundle. Matching Bun 1.3.13, WebKit, and tinycc sources and checksums are in the [runtime-source release](https://github.com/samuelho-dev/rex-worktrees/releases/tag/v0.1.1). Extract all three source archives, placing WebKit at `bun-source/vendor/WebKit` and tinycc at `bun-source/vendor/tinycc` (strip each archive's top-level directory).
|
|
157
113
|
|
|
158
|
-
|
|
114
|
+
Follow [Bun's build prerequisites](https://github.com/oven-sh/bun/blob/bun-1.3.13/CONTRIBUTING.md), then run in `bun-source`:
|
|
159
115
|
|
|
160
116
|
```sh
|
|
161
|
-
mkdir -p bun-source/vendor/WebKit bun-source/vendor/tinycc
|
|
162
|
-
tar -xzf bun-1.3.13-source.tar.gz -C bun-source --strip-components 1
|
|
163
|
-
tar -xzf bun-webkit-source.tar.gz -C bun-source/vendor/WebKit --strip-components 1
|
|
164
|
-
tar -xzf bun-tinycc-source.tar.gz -C bun-source/vendor/tinycc --strip-components 1
|
|
165
|
-
cd bun-source
|
|
166
117
|
bun install --frozen-lockfile
|
|
167
118
|
GIT_SHA=bf2e2cecf27e800962b1e7f03d66278f9d5d2e79 bun run build:release:local
|
|
168
|
-
./build/release-local/bun build /absolute/path/to/rex-worktrees.js
|
|
169
|
-
|
|
170
|
-
codesign --force --sign - /absolute/path/to/rex-worktrees-relinked
|
|
119
|
+
./build/release-local/bun build /absolute/path/to/rex-worktrees.js --compile --outfile /absolute/path/to/rex-worktrees-relinked
|
|
120
|
+
codesign --force --sign - /absolute/path/to/rex-worktrees-relinked # macOS only
|
|
171
121
|
```
|
|
172
122
|
|
|
173
123
|
</details>
|
package/dist/rex-worktrees
CHANGED