workshell 0.4.0 → 0.5.1

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,9 +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.
-- 📦 **Instant setup** — Untracked files (`.env.*`, etc) are automatically copied using [copy-on-write](https://notes.billmill.org/blog/2024/03/How_I_use_git_worktrees.html). For JS projects, the package manager is auto-detected and `npm/yarn/pnpm/bun install` runs automatically.
+- 🖥️ **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.
@@ -112,7 +112,7 @@ After cloning, the `main` branch is checked out. Let's say we want to start work
 $ wk new feat-1
 
 ✓ feat-1 (from main)
-Opened branch in ephemeral subshell
+Opening branch in ephemeral subshell
 Type 'wk close' to return.
 ```
 
@@ -182,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
@@ -213,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. 
 
@@ -224,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
@@ -271,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
@@ -313,40 +326,62 @@ Choice (1/2): 1
 
 ## Automatic file copying
 
-When you create a workshell, `wk` automatically copies all gitignored files from your repo root to the new worktree using **copy-on-write**. This means:
+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.
 
-- `.env`, `.venv`, etc. are instantly available
-- Copy-on-write is near-instant and uses zero extra disk space (until files are modified)
+<details>
+<summary>Default copy patterns (click to expand)</summary>
 
-This works automatically on macOS (APFS) and Linux (Btrfs/XFS). On other filesystems, files are copied normally.
+```
+.env*
+.npmrc*
+.yarnrc*
+.pnpmfile.*
+.pnpmrc*
+.tool-versions
+.node-version
+.nvmrc
+.ruby-version
+.python-version
+.mise*.toml
+.dir-locals.el
+.editorconfig.local
+```
 
-### JS package manager detection
+</details>
 
-For JavaScript projects, `wk` auto-detects your package manager from lockfiles:
+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.
 
-| Lockfile | Package Manager |
-|----------|-----------------|
-| `pnpm-lock.yaml` | pnpm |
-| `yarn.lock` | yarn |
-| `bun.lockb` / `bun.lock` | bun |
-| `package-lock.json` | npm |
+You can override which gitignored files get copied with the `copy` option in `workshell.toml`:
 
-When detected, `node_modules` is skipped during copying and `<pm> install` runs automatically. This is faster than copying large `node_modules` directories.
+```toml
+# override default patterns (default: .env*, .npmrc*, .nvmrc, .tool-versions, etc.)
+copy = [".env*", ".secret*", "data/fixtures/**"]
+```
 
-### Python package manager detection
+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.).
 
-For Python projects, `wk` auto-detects your package manager from lockfiles:
+### Package manager detection
 
-| Lockfile | Package Manager | Install Command |
-|----------|-----------------|-----------------|
-| `uv.lock` | uv | `uv sync` |
-| `poetry.lock` | poetry | `poetry install` |
-| `Pipfile.lock` | pipenv | `pipenv install` |
-| `pdm.lock` | pdm | `pdm install` |
+`wk` auto-detects your package manager and runs install automatically:
 
-When detected, `.venv` and `venv` are skipped during copying and the install command runs automatically. Mixed JS+Python projects are supported: both ecosystems are detected and their installs run in sequence.
+| 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` |
 
-To disable auto-detection, add a custom `setup` script in `workshell.toml`.
+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 />
 
@@ -366,12 +401,14 @@ You can optionally configure `wk` with a `workshell.toml` file.
 ### Options
 
 ```toml
-# Optional: setup script executed in subshell after initialization
-# Variable substitutions:
-#   `{{ 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`
+# 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"
 ```
-
-Note: Setting `setup` disables automatic package manager detection. If you want both, include the install command in your setup script.