workforest 0.3.0__tar.gz → 0.4.0__tar.gz

{workforest-0.3.0 → workforest-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workforest
-Version: 0.3.0
+Version: 0.4.0
 Summary: Git worktree forest management: create, open, and clean up per-branch worktrees with project-defined setup hooks
 Project-URL: Homepage, https://github.com/ArkadyBuryakov/workforest
 Author-email: Arkady Buryakov <arkady@buryakov.pro>
@@ -44,8 +44,8 @@ opened, and cleaned up with one command.
 - **Create** a worktree for any branch (local, remote, or brand new) and have
   it set up automatically: symlinks for untracked assets (`node_modules`,
   `.env`, …) and project-defined setup scripts.
-- **Open** it in your editor — in the current shell, or in a new terminal
-  window via a configurable command template.
+- **Open** it in your editor — in your terminal, in a new terminal window or
+  multiplexer pane, or in a GUI app, all from a small shell-command config.
 - **Run** named project scripts with well-known `WF_*` environment variables.
 - **Delete** worktrees safely, or **checkout**: collapse one back into the
   main checkout.
@@ -106,27 +106,77 @@ Layered, YAML or JSON; later layers override earlier ones:
 | project (shared) | `.workforest.yaml` in the repo root | repo policy, committed |
 | project (local) | `.vscode/` or `.idea/` `.workforest.yaml` | personal overrides, untracked |
 
-Scalars and lists replace; the `scripts`/`openers` mappings merge per key
-(`null` removes an entry). `workforest config` shows the merged result and
-where each layer came from; `workforest init` scaffolds a project file
-(`--local` for a personal one).
+Scalars and lists replace; the `openers`/`wrappers`/`scripts` mappings
+merge per key (`null` removes an entry). `workforest config` shows the
+merged result and where each layer came from; `workforest init` scaffolds a
+project file (`--local` for a personal one). Nothing in the environment
+changes the result — files and flags only.
 
 All keys, with defaults:
 
 ```yaml
 worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"  # where the forest lives
-opener: ""              # default opener; "" → $VISUAL → $EDITOR
-openers: {}             # name -> shell command, e.g. edit: '$EDITOR "$WF_TARGET"'
-window_command: ""      # "" → current shell; or e.g. kitty --title "$WF_TITLE"
-                        #   --directory "$WF_WORKTREE" $SHELL -c "$WF_COMMAND"
+opener: ""              # default opener: an `openers` name or a shell command;
+                        #   "" → $VISUAL → $EDITOR
+openers: {}             # name -> what `-o NAME` runs, and where
+wrappers: {}            # name -> command that runs $WF_COMMAND elsewhere (window, pane, direnv)
 symlinks: []            # untracked assets linked from main into new worktrees
 setup_scripts: []       # shell snippets run in a fresh worktree
 scripts: {}             # name -> snippet for `wf run NAME`
 ```
 
-Openers and `window_command` are plain shell commands, run via `$SHELL -c`
-with one variable family in the environment — the same family the launched
-process and every script receive:
+### Openers
+
+An opener is a shell command that runs with the worktree root as working
+directory, either **in your terminal** (the default: the `wf` wrapper does
+`cd` there and runs it) or **in the background** (`background: true`:
+spawned detached, `wf` returns immediately — for GUI apps and commands that
+hand off to a daemon or multiplexer). Optionally it runs **through a
+wrapper**, a command that receives it as `$WF_COMMAND` and takes it
+somewhere else: a new terminal window, a tmux window, a `direnv exec`. With
+no config at all, `wf` runs `$VISUAL`/`$EDITOR` in your terminal.
+
+```yaml
+opener: win                 # what `wf create` / `wf open` run by default
+
+wrappers:                   # get the opener command as $WF_COMMAND
+  kitty:
+    command: kitty --title "$WF_TITLE" --directory "$WF_WORKTREE" $SHELL -c "$WF_COMMAND"
+    background: true
+  tmux:                     # the tmux server has its own environment: WF_ENV re-creates ours
+    command: tmux new-window -n "$WF_TITLE" -c "$WF_WORKTREE" "export $WF_ENV; $WF_COMMAND"
+    background: true
+
+openers:
+  edit: $EDITOR "$WF_TARGET"        # in your terminal
+  code:                             # GUI app: detached
+    command: code "$WF_WORKTREE"
+    background: true
+  kitty:                              # edit's command, in a new kitty window
+    from: edit
+    wrap: kitty
+  tmux:                              # edit's command, in a new tmux window
+    from: edit
+    wrap: tmux
+  git: lazygit
+```
+
+An entry is a shell command string, or a mapping with either `command` (a
+shell command, never a name) or `from` (another opener's command — one
+level: the target has a `command` of its own — inheriting its `background`
+unless the entry sets one), plus optionally `background: true` or
+`wrap: NAME`. `wrap` and `background` never sit on the same entry: the
+wrapper decides where the whole thing runs, via its own `background` flag.
+`-o VALUE` (and `opener:`) is an `openers` name, else a shell command;
+`-w NAME` on `create`/`open` overrides the opener's wrapper (`-w ''` for
+none). Wrappers are environment-specific, so they belong in the per-machine
+user config — a host without your terminal emulator simply has none.
+`from` and `wrap` names are checked when the config loads, so `wf config`
+reports a misspelled one.
+
+All of them are plain shell commands, run via `$SHELL -c` with one variable
+family in the environment — the same family the launched process and every
+script receive:
 
 | Variable | Value |
 |---|---|
@@ -137,18 +187,21 @@ process and every script receive:
 | `WF_BRANCH` | its branch (empty if detached) |
 | `WF_TARGET` | the `-p` argument, default `.` (launch-only) |
 | `WF_TITLE` | window label, `project_name: feat-x` (launch-only) |
+| `WF_ENV` | all of the above as shell-quoted `NAME=value` assignments (launch-only) |
+| `WF_COMMAND` | in a wrapper: the opener command, unexpanded |
 
 Standard shell rules apply — there is no workforest template syntax:
 `"$WF_X"` is exactly one argument, bare `$WF_X` word-splits, and `$$`,
 braces, pipes, and `&&` mean whatever your shell says they mean (a
-misspelled `$WF_VAR` expands to empty, as in any shell). Openers run with
-the worktree root as working directory. In `window_command` the resolved
-opener command is additionally available as `$WF_COMMAND` — still
-unexpanded, so run it through a shell of its own for its `$WF_*` references
-to resolve: `$SHELL -c "$WF_COMMAND"`. Spawned windows shed activation
-state inherited from the invoking shell (Python venv, conda, nvm, rvm) so
-the new session starts clean instead of carrying an environment it cannot
-deactivate.
+misspelled `$WF_VAR` expands to empty, as in any shell). `$WF_COMMAND`
+reaches the wrapper unexpanded, so run it through a shell of its own for its
+`$WF_*` references to resolve: `$SHELL -c "$WF_COMMAND"`. When that shell
+runs somewhere this environment is not inherited — a tmux server, an ssh
+host — hand the family over as text: `"export $WF_ENV; $WF_COMMAND"` is
+re-parsed on the far side, quoting intact. Background
+processes shed activation state inherited from the invoking shell (Python
+venv, conda, nvm, rvm) so a new window starts clean instead of carrying an
+environment it cannot deactivate.
 
 Fully commented reference configs:
 [`config.yaml`](src/workforest/examples/config.yaml) (user/system) and
@@ -187,8 +240,8 @@ scripts:
 ## Commands
 
 ```
-workforest create [BRANCH] [-o OPENER] [-p PATH] [--no-hooks] [--no-open]
-workforest open   [NAME]   [-o OPENER] [-p PATH]
+workforest create [BRANCH] [-o OPENER] [-w WRAPPER] [-p PATH] [--no-hooks] [--no-open]
+workforest open   [NAME]   [-o OPENER] [-w WRAPPER] [-p PATH]
 workforest list   [--porcelain]
 workforest delete NAME...  [--force] [--delete-branch | --keep-branch]
 workforest checkout NAME   [--force]

{workforest-0.3.0 → workforest-0.4.0}/README.md

@@ -24,8 +24,8 @@ opened, and cleaned up with one command.
 - **Create** a worktree for any branch (local, remote, or brand new) and have
   it set up automatically: symlinks for untracked assets (`node_modules`,
   `.env`, …) and project-defined setup scripts.
-- **Open** it in your editor — in the current shell, or in a new terminal
-  window via a configurable command template.
+- **Open** it in your editor — in your terminal, in a new terminal window or
+  multiplexer pane, or in a GUI app, all from a small shell-command config.
 - **Run** named project scripts with well-known `WF_*` environment variables.
 - **Delete** worktrees safely, or **checkout**: collapse one back into the
   main checkout.
@@ -86,27 +86,77 @@ Layered, YAML or JSON; later layers override earlier ones:
 | project (shared) | `.workforest.yaml` in the repo root | repo policy, committed |
 | project (local) | `.vscode/` or `.idea/` `.workforest.yaml` | personal overrides, untracked |
 
-Scalars and lists replace; the `scripts`/`openers` mappings merge per key
-(`null` removes an entry). `workforest config` shows the merged result and
-where each layer came from; `workforest init` scaffolds a project file
-(`--local` for a personal one).
+Scalars and lists replace; the `openers`/`wrappers`/`scripts` mappings
+merge per key (`null` removes an entry). `workforest config` shows the
+merged result and where each layer came from; `workforest init` scaffolds a
+project file (`--local` for a personal one). Nothing in the environment
+changes the result — files and flags only.
 
 All keys, with defaults:
 
 ```yaml
 worktrees_dir: "$WF_MAIN/../worktrees/$WF_NAME"  # where the forest lives
-opener: ""              # default opener; "" → $VISUAL → $EDITOR
-openers: {}             # name -> shell command, e.g. edit: '$EDITOR "$WF_TARGET"'
-window_command: ""      # "" → current shell; or e.g. kitty --title "$WF_TITLE"
-                        #   --directory "$WF_WORKTREE" $SHELL -c "$WF_COMMAND"
+opener: ""              # default opener: an `openers` name or a shell command;
+                        #   "" → $VISUAL → $EDITOR
+openers: {}             # name -> what `-o NAME` runs, and where
+wrappers: {}            # name -> command that runs $WF_COMMAND elsewhere (window, pane, direnv)
 symlinks: []            # untracked assets linked from main into new worktrees
 setup_scripts: []       # shell snippets run in a fresh worktree
 scripts: {}             # name -> snippet for `wf run NAME`
 ```
 
-Openers and `window_command` are plain shell commands, run via `$SHELL -c`
-with one variable family in the environment — the same family the launched
-process and every script receive:
+### Openers
+
+An opener is a shell command that runs with the worktree root as working
+directory, either **in your terminal** (the default: the `wf` wrapper does
+`cd` there and runs it) or **in the background** (`background: true`:
+spawned detached, `wf` returns immediately — for GUI apps and commands that
+hand off to a daemon or multiplexer). Optionally it runs **through a
+wrapper**, a command that receives it as `$WF_COMMAND` and takes it
+somewhere else: a new terminal window, a tmux window, a `direnv exec`. With
+no config at all, `wf` runs `$VISUAL`/`$EDITOR` in your terminal.
+
+```yaml
+opener: win                 # what `wf create` / `wf open` run by default
+
+wrappers:                   # get the opener command as $WF_COMMAND
+  kitty:
+    command: kitty --title "$WF_TITLE" --directory "$WF_WORKTREE" $SHELL -c "$WF_COMMAND"
+    background: true
+  tmux:                     # the tmux server has its own environment: WF_ENV re-creates ours
+    command: tmux new-window -n "$WF_TITLE" -c "$WF_WORKTREE" "export $WF_ENV; $WF_COMMAND"
+    background: true
+
+openers:
+  edit: $EDITOR "$WF_TARGET"        # in your terminal
+  code:                             # GUI app: detached
+    command: code "$WF_WORKTREE"
+    background: true
+  kitty:                              # edit's command, in a new kitty window
+    from: edit
+    wrap: kitty
+  tmux:                              # edit's command, in a new tmux window
+    from: edit
+    wrap: tmux
+  git: lazygit
+```
+
+An entry is a shell command string, or a mapping with either `command` (a
+shell command, never a name) or `from` (another opener's command — one
+level: the target has a `command` of its own — inheriting its `background`
+unless the entry sets one), plus optionally `background: true` or
+`wrap: NAME`. `wrap` and `background` never sit on the same entry: the
+wrapper decides where the whole thing runs, via its own `background` flag.
+`-o VALUE` (and `opener:`) is an `openers` name, else a shell command;
+`-w NAME` on `create`/`open` overrides the opener's wrapper (`-w ''` for
+none). Wrappers are environment-specific, so they belong in the per-machine
+user config — a host without your terminal emulator simply has none.
+`from` and `wrap` names are checked when the config loads, so `wf config`
+reports a misspelled one.
+
+All of them are plain shell commands, run via `$SHELL -c` with one variable
+family in the environment — the same family the launched process and every
+script receive:
 
 | Variable | Value |
 |---|---|
@@ -117,18 +167,21 @@ process and every script receive:
 | `WF_BRANCH` | its branch (empty if detached) |
 | `WF_TARGET` | the `-p` argument, default `.` (launch-only) |
 | `WF_TITLE` | window label, `project_name: feat-x` (launch-only) |
+| `WF_ENV` | all of the above as shell-quoted `NAME=value` assignments (launch-only) |
+| `WF_COMMAND` | in a wrapper: the opener command, unexpanded |
 
 Standard shell rules apply — there is no workforest template syntax:
 `"$WF_X"` is exactly one argument, bare `$WF_X` word-splits, and `$$`,
 braces, pipes, and `&&` mean whatever your shell says they mean (a
-misspelled `$WF_VAR` expands to empty, as in any shell). Openers run with
-the worktree root as working directory. In `window_command` the resolved
-opener command is additionally available as `$WF_COMMAND` — still
-unexpanded, so run it through a shell of its own for its `$WF_*` references
-to resolve: `$SHELL -c "$WF_COMMAND"`. Spawned windows shed activation
-state inherited from the invoking shell (Python venv, conda, nvm, rvm) so
-the new session starts clean instead of carrying an environment it cannot
-deactivate.
+misspelled `$WF_VAR` expands to empty, as in any shell). `$WF_COMMAND`
+reaches the wrapper unexpanded, so run it through a shell of its own for its
+`$WF_*` references to resolve: `$SHELL -c "$WF_COMMAND"`. When that shell
+runs somewhere this environment is not inherited — a tmux server, an ssh
+host — hand the family over as text: `"export $WF_ENV; $WF_COMMAND"` is
+re-parsed on the far side, quoting intact. Background
+processes shed activation state inherited from the invoking shell (Python
+venv, conda, nvm, rvm) so a new window starts clean instead of carrying an
+environment it cannot deactivate.
 
 Fully commented reference configs:
 [`config.yaml`](src/workforest/examples/config.yaml) (user/system) and
@@ -167,8 +220,8 @@ scripts:
 ## Commands
 
 ```
-workforest create [BRANCH] [-o OPENER] [-p PATH] [--no-hooks] [--no-open]
-workforest open   [NAME]   [-o OPENER] [-p PATH]
+workforest create [BRANCH] [-o OPENER] [-w WRAPPER] [-p PATH] [--no-hooks] [--no-open]
+workforest open   [NAME]   [-o OPENER] [-w WRAPPER] [-p PATH]
 workforest list   [--porcelain]
 workforest delete NAME...  [--force] [--delete-branch | --keep-branch]
 workforest checkout NAME   [--force]

{workforest-0.3.0 → workforest-0.4.0}/src/workforest/__init__.py

@@ -1,3 +1,3 @@
 """Workforest — git worktree forest management."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{workforest-0.3.0 → workforest-0.4.0}/src/workforest/cli.py

@@ -68,6 +68,7 @@ def _handle_create(ns: argparse.Namespace) -> CommandResult:
         ctx,
         ns.branch,
         opener=ns.opener,
+        wrap=ns.wrap,
         path_arg=ns.path,
         no_hooks=ns.no_hooks,
         no_open=ns.no_open,
@@ -76,7 +77,7 @@ def _handle_create(ns: argparse.Namespace) -> CommandResult:
 
 def _handle_open(ns: argparse.Namespace) -> CommandResult:
     ctx = commands.build_context()
-    return commands.cmd_open(ctx, ns.name, opener=ns.opener, path_arg=ns.path)
+    return commands.cmd_open(ctx, ns.name, opener=ns.opener, wrap=ns.wrap, path_arg=ns.path)
 
 
 def _handle_list(ns: argparse.Namespace) -> CommandResult:
@@ -149,6 +150,12 @@ def build_parser() -> argparse.ArgumentParser:
 
     def opener_args(p: argparse.ArgumentParser) -> None:
         p.add_argument("-o", "--opener", help="opener name or shell command")
+        p.add_argument(
+            "-w",
+            "--wrap",
+            metavar="WRAPPER",
+            help="run the opener through this `wrappers` entry ('' for none)",
+        )
         p.add_argument(
             "-p", "--path", help="path inside the worktree, passed to the opener as $WF_TARGET"
         )

{workforest-0.3.0 → workforest-0.4.0}/src/workforest/commands.py

@@ -118,6 +118,7 @@ def cmd_create(
     branch: str | None,
     *,
     opener: str | None = None,
+    wrap: str | None = None,
     path_arg: str | None = None,
     no_hooks: bool = False,
     no_open: bool = False,
@@ -164,6 +165,7 @@ def cmd_create(
         worktrees_dir=ctx.worktrees_dir,
         branch=branch,
         opener_arg=opener,
+        wrap_arg=wrap,
         path_arg=path_arg,
     )
 
@@ -173,6 +175,7 @@ def cmd_open(
     name: str | None,
     *,
     opener: str | None = None,
+    wrap: str | None = None,
     path_arg: str | None = None,
 ) -> CommandResult:
     if name:
@@ -190,6 +193,7 @@ def cmd_open(
         worktrees_dir=ctx.worktrees_dir,
         branch=worktree.branch,
         opener_arg=opener,
+        wrap_arg=wrap,
         path_arg=path_arg,
     )
 

{workforest-0.3.0 → workforest-0.4.0}/src/workforest/completions.py

@@ -7,7 +7,7 @@ names; the `commands` topic emits `NAME<TAB>KIND<TAB>DESCRIPTION` and the
 (zsh) do, while others take field 1.
 """
 
-from workforest import commands, gitutil
+from workforest import commands, gitutil, launch
 from workforest.config import Config, load_config
 from workforest.errors import WorkforestError
 
@@ -50,13 +50,13 @@ def _commands() -> list[str]:
     from workforest.cli import SUBCOMMAND_HELP, _known_subcommands
 
     known = _known_subcommands()
-    openers = _config().openers
+    config = _config()
     # An opener sharing a subcommand's name is shadowed by it (cli._preprocess
     # dispatches known subcommands first), so don't offer it.
     return [f"{name}\tcommand\t{SUBCOMMAND_HELP[name]}" for name in sorted(known)] + [
         # collapse whitespace: a tab/newline in an opener command would break the line protocol
-        f"{name}\topener\t{' '.join(openers[name].split())}"
-        for name in sorted(openers)
+        f"{name}\topener\t{' '.join(launch.describe_opener(config, name).split())}"
+        for name in sorted(config.openers)
         if name not in known
     ]