workshell 0.2.0 → 0.5.0

package/README.md

@@ -22,7 +22,7 @@
 ```bash
 $ npm i -g workshell  # aliases to `wk`
 $ wk --help
-wk v0.0.6 - Open branches in ephemeral subshells
+wk v0.5.0 - Open branches in ephemeral subshells
 
 Usage: wk <command> [options]
 # ...
@@ -40,7 +40,7 @@ Here's how it works (key points in **bold**).
 
 - You open a Git branch with `wk open <branch>` or create a new one with `wk new <branch>`.
 - An ephemeral worktree is created for this branch (in `~/.workshell/worktrees`) and **opened in a fresh subshell**.
-- You are now in an fresh checkout of your repo that is isolated on disk. Make changes with your agent/editor of choice and commit them.
+- You are now in a fresh checkout of your repo that is isolated on disk. Make changes with your agent/editor of choice and commit them.
 - You close the subshell with `wk close`. **The associated worktree is auto-pruned**.
 - Your changes still exist on the associated branch, as Git commits/branches are shared among all worktrees. The worktree is destroyed—but your commits aren't.
 
@@ -66,8 +66,9 @@ Here's how it works (key points in **bold**).
 
 This approach has some nice properties.
 
-- 🖥️ **Tab-local workspaces** — Normally a `git checkout`/`git switch` changes your active branch for all terminals. With workshells, you can functionality open branches *in the current tab only*.
-- 🌳 **Full isolation** — Each workshell is isolated on disk, so the changes you make don't interfere anything else you're doing.
+- 🖥️ **Tab-local workspaces** — Normally a `git checkout`/`git switch` changes your active branch for all terminals. With workshells, you can open branches *in the current tab only*.
+- 🌳 **Full isolation** — Each workshell is isolated on disk, so the changes you make don't interfere with anything else you're doing.
+- 📦 **Instant setup** — Common config files are automatically copied using [copy-on-write](https://notes.billmill.org/blog/2024/03/How_I_use_git_worktrees.html), and your package manager is auto-detected so `npm`/`yarn`/`pnpm`/`bun` install runs automatically.
 - 🙅‍♂️ **Never stash again** — You can `wk open` a branch even with uncommitted changes. When you exit the subshell, things will be exactly the same as they were. ☕️
 - 🪾 **Consistent with branch semantics** — As with regular `git switch`, `wk close` won't let you close the subshell if you have unstaged/uncommitted changes. This is a feature, not a bug! Regular worktrees make it easy to lose your work in a forgotten corner of your file system.
 - 🤖 **Agent-ready** — Spin up parallel workshells so multiple agents can work simultaneously without conflicts.
@@ -181,7 +182,7 @@ Usage: wk <command> [options]
 
 Commands:
   new [branch]    Create a branch and open it [--from <branch>]
-  open <branch>   Open a branch in a workshell
+  open <ref>      Open a branch or PR in a workshell
   close           Exit current workshell
   ls              List orphaned worktrees
   status          Show current branch
@@ -212,7 +213,7 @@ $ wk ls
 <br />
 
 
-### Open a branch in a workshell
+### Open a branch or PR in a workshell
 
 You can open any existing Git branch in a workshell. 
 
@@ -223,6 +224,19 @@ $ wk open feat-1
 Type 'wk close' to return.
 ```
 
+You can also open GitHub pull requests directly. `wk open` accepts anything that `gh pr view` understands — PR numbers, URLs, or branch names. The PR branch is automatically fetched if it doesn't exist locally. Requires [GitHub CLI](https://cli.github.com/) (`gh`).
+
+```sh
+# by PR number
+$ wk open 42
+
+# by GitHub URL
+$ wk open https://github.com/org/repo/pull/42
+
+# by branch name (tries local branch first, then GitHub PR)
+$ wk open feature/auth
+```
+
 <br />
 
 ### Show current branch status
@@ -270,7 +284,7 @@ If the branch hasn't been pushed to a remote, you'll be prompted to auto-merge:
 - `n` — skip (branch is kept, merge manually later)
 - `never` — permanently disable auto-merge prompt
 
-That command will fail if you have unstaged/uncommited changes. Use the `--force`/`-f` flag to force close the workshell; **this will discard uncommitted changes**.
+That command will fail if you have unstaged/uncommitted changes. Use the `--force`/`-f` flag to force close the workshell; **this will discard uncommitted changes**.
 
 ```sh
 $ wk close --force
@@ -310,9 +324,70 @@ Choice (1/2): 1
 
 <br />
 
+## Automatic file copying
+
+When you create a workshell, `wk` automatically copies common config files from your repo to the new worktree using **copy-on-write**. This includes env files, package manager config, version manager config (`asdf`, `mise`, `nvm`), and editor overrides.
+
+<details>
+<summary>Default copy patterns (click to expand)</summary>
+
+```
+.env*
+.npmrc*
+.yarnrc*
+.pnpmfile.*
+.pnpmrc*
+.tool-versions
+.node-version
+.nvmrc
+.ruby-version
+.python-version
+.mise*.toml
+.dir-locals.el
+.editorconfig.local
+```
+
+</details>
+
+Copy-on-write is near-instant and uses zero extra disk space (until files are modified). This works automatically on macOS (APFS) and Linux (Btrfs/XFS). On other filesystems, files are copied normally.
+
+You can override which gitignored files get copied with the `copy` option in `workshell.toml`:
+
+```toml
+# override default patterns (default: .env*, .npmrc*, .nvmrc, .tool-versions, etc.)
+copy = [".env*", ".secret*", "data/fixtures/**"]
+```
+
+Patterns without `/` match at any depth (e.g. `.env*` matches both `.env` and `packages/api/.env.local`). Patterns with `/` are anchored to the repo root. Full glob syntax is supported (`*`, `**`, `?`, `[abc]`, etc.).
+
+### Package manager detection
+
+`wk` auto-detects your package manager and runs install automatically:
+
+| Lockfile | Command |
+|----------|---------|
+| `pnpm-lock.yaml` | `pnpm install` |
+| `yarn.lock` | `yarn install` |
+| `bun.lockb` / `bun.lock` | `bun install` |
+| `package-lock.json` | `npm install` |
+| `uv.lock` | `uv sync` |
+| `poetry.lock` | `poetry install` |
+| `Pipfile.lock` | `pipenv install` |
+| `pdm.lock` | `pdm install` |
+
+Detection requires the binary to be installed. If the install command fails, a warning is printed and setup continues. Mixed JS+Python projects are supported.
+
+Setting a `setup` script in `workshell.toml` disables automatic package manager detection. Include the install command in your setup script if you want both:
+
+```toml
+setup = "pnpm install && nvm use"
+```
+
+<br />
+
 ## `workshell.toml`
 
-You can configure `wk` with a `workshell.toml` file. This is useful for running setup scripts when opening a workshell (e.g., `npm install`).
+You can optionally configure `wk` with a `workshell.toml` file.
 
 `wk` looks for config files in the following order:
 
@@ -323,13 +398,17 @@ You can configure `wk` with a `workshell.toml` file. This is useful for running
 
 <br />
 
-Currently only one setting is supported: `setup`.
+### Options
 
 ```toml
-# setup script executed in subshell after initialization
-# the following variable substitutions are supported
-#   `{{ branch }}` — The name of the opened branch, e.g. `feature/auth` 
-#   `{{ repo_path }}` — The absolute path to main repo, e.g. `/path/to/repo`
-#   `{{ worktree_path }}` — The absolute path to worktree, e.g. `~/.workshell/worktrees/.../repo@feat`
-setup = "npm install && cp {{ repo_path }}/.env {{ worktree_path }}/.env"
+# optional: override which gitignored files get copied (default: .env*, .npmrc*, .nvmrc, etc.)
+copy = [".env*", ".secret*"]
+
+# optional: setup script executed in subshell after initialization
+# disables automatic package manager detection (see above)
+# variable substitutions:
+#   `{{ branch }}` — name of opened branch, e.g. `feature/auth` 
+#   `{{ repo_path }}` — absolute path to main repo, e.g. `/path/to/repo`
+#   `{{ worktree_path }}` — absolute path to worktree, e.g. `~/.workshell/worktrees/.../repo@feat`
+setup = "nvm use"
 ```