rex-worktrees 0.1.2 → 0.2.0
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 +26 -18
- package/dist/rex-worktrees +2 -2
- package/dist/rex-worktrees.js +1637 -407
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Rex Worktrees
|
|
2
2
|
|
|
3
|
-
Rex Worktrees opens Git worktrees in an exact [Rex](https://www.superlogical.com/rex/docs) session on this machine or an existing Rex host. Its keyboard-driven chooser runs in a floating Rex terminal. Rex manages hosts, connections, and sessions; this tool creates or selects a checkout and opens a shell there.
|
|
3
|
+
Rex Worktrees opens Git worktrees or Jujutsu (JJ) workspaces in an exact [Rex](https://www.superlogical.com/rex/docs) session on this machine or an existing Rex host. Its keyboard-driven chooser runs in a floating Rex terminal. Rex manages hosts, connections, and sessions; this tool creates or selects a checkout and opens a shell there. When a selected logical project has no directory on the destination, the chooser can clone published history and open it there.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Standalone binaries are built for Apple Silicon Macs running macOS 15 or later and Linux x64 (Ubuntu 24.04 CI runner). Git 2.42 or later, the Rex CLI, and a running local Rex server are required for interactive use; JJ projects additionally require Jujutsu 0.46 or later. Node.js and npm are needed only to install the macOS ARM64 npm package, not to run either standalone executable; Bun is not required.
|
|
8
8
|
|
|
9
9
|
### npm
|
|
10
10
|
|
|
@@ -18,14 +18,14 @@ rex config reload
|
|
|
18
18
|
|
|
19
19
|
### GitHub Releases
|
|
20
20
|
|
|
21
|
-
Download
|
|
21
|
+
Download both `rex-worktrees-macos-arm64.tar.gz` and `rex-worktrees-linux-x64.tar.gz` plus `SHA256SUMS` from [the latest GitHub Release](https://github.com/samuelho-dev/rex-worktrees/releases/latest). Verify them with `shasum -a 256 -c SHA256SUMS` (or `sha256sum -c SHA256SUMS` on Linux), then extract the archive for your platform to a permanent location. Run setup with the absolute path to the extracted executable:
|
|
22
22
|
|
|
23
23
|
```sh
|
|
24
24
|
/absolute/path/to/rex-worktrees setup --bin /absolute/path/to/rex-worktrees
|
|
25
25
|
rex config reload
|
|
26
26
|
```
|
|
27
27
|
|
|
28
|
-
Keep the executable at that path when replacing it with a newer release, then repeat setup and `rex config reload`. Each
|
|
28
|
+
Keep the executable at that path when replacing it with a newer release, then repeat setup and `rex config reload`. Each platform archive contains the relinkable bundle and license notices described below. The stable asset names can be fetched through `releases/latest/download/` without pinning a release version.
|
|
29
29
|
|
|
30
30
|
### Build from source
|
|
31
31
|
|
|
@@ -40,9 +40,11 @@ rex config reload
|
|
|
40
40
|
|
|
41
41
|
Source-build setup copies the executable to `~/.local/bin/rex-worktrees`; `setup --bin PATH` instead registers an existing executable without copying or modifying it. Add `~/.local/bin` to `PATH` for source-build CLI use.
|
|
42
42
|
|
|
43
|
-
All installation methods place the Lua module beside the active Rex config and add a managed registration without replacing unrelated config. Setup needs `rex` on `PATH`, or `REX_BIN_DIR` set to its absolute directory. Setup from uncompiled source is not supported. Each execution machine needs its own installation; setup does not pair or deploy to another host.
|
|
43
|
+
All installation methods place the Lua module beside the active Rex config and add a managed registration without replacing unrelated config. Setup needs `rex` on `PATH`, or `REX_BIN_DIR` set to its absolute directory. Setup from uncompiled source is not supported. Setup records **this host's executable search `PATH`** for stored Rex actions, whose server-side process may otherwise lack shell-installed tools; run setup from a shell that can find Git and, for JJ projects, `jj`, then `rex config reload`. Repeat setup and reload after changing the tools' search path. Each execution machine needs its own helper installation and, for JJ projects, its own JJ and Git installations; setup does not pair or deploy to another host. The source machine also needs the helper to inspect clone sources.
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
For a stopped Rex server or an image built before Rex starts, run `rex-worktrees setup --config /absolute/path/to/rex/init.lua --bin /absolute/path/to/rex-worktrees`. This uses that explicit config without calling `rex config check`, starting Rex, or reloading it; its managed action registration is loaded when Rex next starts. The file must be a regular file or absent (not a symlink), and the Rex CLI must still be installed in `PATH` or `REX_BIN_DIR` so its directory can be recorded. The managed registration preserves unrelated Lua settings and is safe to repeat.
|
|
46
|
+
|
|
47
|
+
To update a source build, rebuild and repeat setup and config reload. To uninstall, locate the active Rex config with `rex config check --json`, remove the section from `-- BEGIN rex-worktrees` through `-- END rex-worktrees`, and delete `rex-worktrees.lua` beside that config. Remove the executable with `npm uninstall -g rex-worktrees`, or delete the standalone executable or `~/.local/bin/rex-worktrees` for other installations, then run `rex config reload`. Git worktrees, JJ workspaces, and association state are retained.
|
|
46
48
|
|
|
47
49
|
## Open a worktree
|
|
48
50
|
|
|
@@ -60,16 +62,16 @@ rex.bind("ctrl+alt+w", "worktrees_open")
|
|
|
60
62
|
|
|
61
63
|
For a manual Lua installation, supply an absolute executable path with `require("rex-worktrees").setup({ bin = "/absolute/path/to/rex-worktrees" })`.
|
|
62
64
|
|
|
63
|
-
The chooser has six fields:
|
|
65
|
+
The chooser has six fields (five when opening an existing JJ workspace):
|
|
64
66
|
|
|
65
|
-
- **Project:** select a known Git project, type a project name, or enter an absolute repository path. Linked checkouts appear under their canonical project.
|
|
66
|
-
- **Machine:** select this machine or an existing Rex host. Changing machines keeps the logical project choice but clears checkout,
|
|
67
|
-
- **Worktree:**
|
|
68
|
-
- **Branch:**
|
|
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.
|
|
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.
|
|
69
|
+
- **Worktree / Workspace:** Git shows worktrees; JJ shows all registered workspaces, including unavailable entries with an unknown/missing location (visible but not openable). Select an available checkout, type a name for a new checkout/workspace, or choose **Clone this project…** for a known logical project. A clone destination must be an editable absolute path on the destination machine; configured project roots offer suggestions. When cloning, typing a name here optionally creates a separate checkout/workspace; type `none` to use the clone's default.
|
|
70
|
+
- **Branch / Start from:** Git branches retain their existing behavior: attach an unoccupied branch or create a new branch from the reviewed base. For a new JJ workspace, **Start from** selects the repository-configured `trunk()` mainline when it resolves to one valid commit. If no valid mainline is available, choose a source candidate or type a singular revision before creating the workspace. A bookmark or revision selection overrides the default; the action pins its full commit ID. This field is hidden when opening a selected existing JJ workspace, which opens unchanged. A JJ clone can use the clone's native default without a pin, or select/type a source revision resolved on the actual source machine before cloning. Bookmarks are optional; this tool never creates one automatically. Source-only unpublished JJ changes and unpushed Git branches are not available in a destination clone.
|
|
69
71
|
- **Session:** choose an exact session on the selected machine.
|
|
70
|
-
- **Mode:** reuse a matching live tab, open another tab, or split a matching task. If a split has no matching task, it opens a new tab.
|
|
72
|
+
- **Mode:** reuse a matching live tab, open another tab, or split a matching task. If a split has no matching task, it opens a new tab. Cloning always starts a new tab.
|
|
71
73
|
|
|
72
|
-
Use arrows or `j`/`k` to move, Tab/Shift+Tab to change fields, and Enter to edit or submit. In an editor, type to filter or create, use arrows for existing options, and Ctrl+U to clear. Esc cancels an edit or, from the form, closes the chooser. Review the checkout path and action before submitting. No agent or model is required; the task opens a shell.
|
|
74
|
+
Use arrows or `j`/`k` to move, Tab/Shift+Tab to change fields, and Enter to edit or submit. In an editor, type to filter or create, use arrows for existing options, and Ctrl+U to clear. In the popup, Ctrl+S commits a valid selection or typed edit and submits the reviewed action when available; an invalid edit does not submit, and plain Enter still only selects. Esc cancels an edit or, from the form, closes the chooser. Project and checkout paths appear in the selection lists rather than as extra lines on the main form. Review the checkout path and action before submitting. A clone proposal displays its validated source URL and exact destination, and requires **Clone & Open** consent; merely changing machines never starts cloning. No agent or model is required; the task opens a shell.
|
|
73
75
|
|
|
74
76
|
## Projects and checkout locations
|
|
75
77
|
|
|
@@ -89,9 +91,11 @@ Configuration is optional and belongs on the **execution machine** at `${XDG_CON
|
|
|
89
91
|
}
|
|
90
92
|
```
|
|
91
93
|
|
|
92
|
-
`projects` explicitly registers paths; optional `roots` scans two directory levels for projects. Without either, the originating Rex pane's directory (or the CLI caller's directory) can suggest its Git project, but no parent directory is scanned. A local directory suggestion is not sent to another machine: enter or select the project directory on that destination. A path typed in the form is interpreted there. Git, not
|
|
94
|
+
`projects` explicitly registers paths; optional `roots` scans two directory levels for projects and offers destination-path suggestions when cloning. Without either, the originating Rex pane's directory (or the CLI caller's directory) can suggest its Git or JJ project, but no parent directory is scanned. A local directory suggestion is not sent to another machine: enter or select the project directory on that destination. A path typed in the form is interpreted there. Git and JJ, not configuration, determine their existing checkouts and branches/revisions. A missing directory for a known source project with a validated origin can be proposed for Clone & Open; an existing valid directory continues through ordinary open.
|
|
95
|
+
|
|
96
|
+
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 Rex has not reported one, it uses the same 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.
|
|
93
97
|
|
|
94
|
-
New checkout location follows this order: a project's `worktreeRoot/<
|
|
98
|
+
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 configuration paths resolve against the config file's directory. 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.
|
|
95
99
|
|
|
96
100
|
## CLI
|
|
97
101
|
|
|
@@ -107,17 +111,21 @@ rex-worktrees open --repo /absolute/path/project \
|
|
|
107
111
|
rex-worktrees open --host workstation --repo /destination/path/project \
|
|
108
112
|
--worktree /destination/path/existing-checkout \
|
|
109
113
|
--session session:DESTINATION-ID --name Existing
|
|
114
|
+
|
|
115
|
+
rex-worktrees open --repo /absolute/path/jj-workspace \
|
|
116
|
+
--revision 'main@origin' --worktree-name task \
|
|
117
|
+
--session session:FULL-ID --name Task
|
|
110
118
|
```
|
|
111
119
|
|
|
112
120
|
`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. `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`. Remote `--repo` and `--worktree` paths must be absolute paths on the destination.
|
|
113
121
|
|
|
114
|
-
`open`
|
|
122
|
+
`open` detects Git or JJ at `--repo`; no VCS switch is needed. Git accepts `--branch` or `--worktree`, with `--worktree-name` for a new branch checkout. JJ accepts `--worktree` for an existing workspace, or `--revision` plus `--worktree-name` for a new workspace. `--repo` is the actual invoking JJ workspace on the destination: relative revisions such as `@-` resolve there, and creating a new workspace may snapshot it. `--name` independently labels the tab or pane. By default, a matching live tab is reused; `--additional` opens another tab, and `--split` splits a matching task or falls back to a new tab. These two flags cannot be combined. `--client ID` selects an exact Rex app client when needed. See `rex-worktrees --help` for popup origin/context flags.
|
|
115
123
|
|
|
116
124
|
## Safety and limits
|
|
117
125
|
|
|
118
|
-
A submitted checkout task can continue after the chooser closes, and closing a tab does not delete its checkout. If a launch times out or Rex reports an uncertain result, inspect
|
|
126
|
+
A submitted checkout or clone task can continue after the chooser closes, and closing a tab does not delete its checkout or clone. If a launch times out or Rex reports an uncertain result, inspect the destination repository and exact session before retrying; partial/registered JJ workspaces and clone destinations are retained rather than blindly removed or retried. Opening or browsing an existing JJ workspace does not snapshot, edit, update-stale, rebase, or move bookmarks. **Creating a JJ workspace invokes native `jj workspace add`, which may snapshot the actual source workspace and change its JJ working-copy commit and Git index intent-to-add entries**; the review notice names that source. Git worktrees keep their separate files, HEAD, and index while sharing refs, objects, remotes, and config. The tool does not force checkout, switch, stash, reset, clean, or prune. A cross-host clone transfers only published Git history from the source origin, not uncommitted files, local-only commits/branches/changes, source credentials, or environment. An explicitly pinned JJ base must be reachable after destination clone or the retained clone requires inspection; omitting a pin uses the clone's native default. Destination credentials and network access must work independently. Shells are not confined to the checkout. Associations live per destination at `${XDG_STATE_HOME:-~/.local/state}/rex-worktrees/associations`; Git/JJ inventory remains authoritative if an association becomes stale.
|
|
119
127
|
|
|
120
|
-
|
|
128
|
+
The release workflow builds and checks macOS ARM64 and Linux x64 executables in their native CI runners, including Git/JJ integration tests and malformed-request smoke checks. Linux destinations have not been verified against a live remote Rex/JJ setup; cross-host execution and cloning remain experimental. Each execution machine requires a matching Rex Worktrees build (older helper protocols are rejected), its own Git/JJ executables as applicable, and a connected Rex host. Native app navigation requires Rex Remote Control permission. Local endpoints must be Unix endpoints; Windows named pipes are not supported. For a custom local Unix server, set `REX_WORKTREES_LOCAL_ENDPOINT=unix:///absolute/path/server.sock` in the plugin environment.
|
|
121
129
|
|
|
122
130
|
## Contributing
|
|
123
131
|
|
package/dist/rex-worktrees
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
1
|
[diffend] Oversized file quarantined before diffing.
|
|
2
2
|
name: package/dist/rex-worktrees
|
|
3
|
-
size:
|
|
4
|
-
sha256:
|
|
3
|
+
size: 64491792 bytes
|
|
4
|
+
sha256: 5220c32f018d4e838d037d7c364c1cee719591a2b66f42befb8ca827de4388d8
|