pf 0.0.5 → 0.0.6

package/README.md

@@ -1,28 +1,45 @@
-# `pf` — Human- and agent-friendly Git multitasking 
-
-<br/><br/>
+<p align="center">
+  <h1 align="center">🌲<br/><code>pf</code></h1>
+  <p align="center">Human- and agent-friendly Git multitasking. Powered by worktrees.
+    <br/>
+    by <a href="https://x.com/colinhacks">@colinhacks</a>
+  </p>
+</p>
+<br/>
+
+<p align="center">
+<a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/pullfrog/pf" alt="License"></a>
+<a href="https://www.npmjs.com/package/pf" rel="nofollow"><img src="https://img.shields.io/npm/dw/pf.svg" alt="npm"></a>
+<a href="https://github.com/pullfrog/pf" rel="nofollow"><img src="https://img.shields.io/github/stars/pullfrog/pf" alt="stars"></a>
+</p>
+
+<br/>
+<br/>
+<br/>
 
 ## Install
 
 ```bash
-npm i -g pf
+$ npm i -g pf
 ```
 
-<br/><br/>
+<br/>
 
-## How does it work
+## How `pf` works
 
-There have been many attempts to nail a DX for parallel work in the agentic coding era. Most are thin wrappers over `git worktree`. That's not what `pf` is (though worktrees are used internally).
+There have been many attempts to nail a DX for parallel work in the agentic coding era. Most are thin wrappers over `git worktree`. Instead `pf` introduces a new paradigm: the *workshell*. 
+
+**A _workshell_ is an ephemeral worktree whose lifecycle is bound to a subshell.**
 
-Instead `pf` introduces a new paradigm: the *workshell*. A workshell is **an ephemeral worktree whose lifecycle is bound to a subshell**. Here's how it works (key points in **bold**).
+Here's how it works (key points in **bold**).
 
 - You open a Git branch with `pf open <branch>` or create a new one with `pf new <branch>`.
 - An ephemeral worktree is created for this branch (in `.git/pf/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 close the subshell with `pf close`, which **auto-prunes the associated worktree**.
-- Your changes still exist on the associated branch.
+- You close the subshell with `pf 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.
 
-That's it. **Ephemeral worktrees whose lifecycle is bound to a subshell.** When the subshell exits, the worktree is destroyed—but your commits aren't.
+<!-- That's it. **Ephemeral worktrees whose lifecycle is bound to a subshell.** When the subshell exits, the worktree is destroyed—but your commits aren't. -->
 
 <!-- 
 ## How does it work
@@ -38,30 +55,30 @@ Here's how it works (key points in **bold**).
 - **The worktree is auto-pruned** — This is key. The lifecycle of the worktree is tied to the subshell. When the subshell is closed, the worktree is destroyed. But *the commits you made inside the subshell* still exist.
 - **Merge in your changes** — Merge/rebase your branch as you normally would, or push to GitHub to open a PR. -->
 
-This approach has some nice properties.
-
-🙅‍♂️ **Never stash again** — You can `pf open` a branch even with uncommitted changes. When you exit the subshell, things will be exactly the same as they were. ☕️
+<br/>
 
-🖥️ **Tab-local checkouts** — 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*.
+## Features
 
-🌳 **Isolated workspaces** — Each workshell is isolated on disk, so the changes you make don't affect anything else you're doing.
-
-🪾 **Maintains branch semantics** — As with regular `git checkout`, `pf close` won't let you close the subshell if you have unstaged/uncommitted changes. Vanilla worktrees are too forgiving in this regard; it makes it far too easy to leave half-finished work in a forgotten corner of your file system.
+This approach has some nice properties.
 
-🤖 **Agent-ready** — Spin up parallel workshells so multiple agents can work simultaneously without conflicts.
+- 🖥️ **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.
+- 🙅‍♂️ **Never stash again** — You can `pf 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`, `pf 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.
 
-<br/><br/>
+<br/>
 
 ## Quickstart
 
-This section is entirely linear and self-contained. You can run all these commands in order to get a feel for how `pf` works. 
-
-First, install `pf`.
+This section is entirely linear and self-contained. Try running all these commands in order to get a feel for how `pf` works. First, install `pf`.
 
 ```bash
 $ npm i -g pf
 ```
 
+<br/>
+
 Then clone a repo (any repo works):
 
 ```bash
@@ -69,6 +86,8 @@ $ git clone git@github.com:colinhacks/zod.git
 $ cd zod
 ```
 
+<br/>
+
 After cloning, the `main` branch is checked out. Let's say we want to start work on a new feature:
 
 ```bash
@@ -79,6 +98,8 @@ Opened branch in ephemeral subshell at .git/pf/worktrees/zod@feat-1
 Type 'pf close' to return.
 ```
 
+<br/>
+
 You're now in a workshell. Check where you are:
 
 ```bash
@@ -89,12 +110,16 @@ $ git branch --show-current
 feat-1
 ```
 
+<br/>
+
 Now let's make some changes. (You can also open the repo in an IDE, start an agent run, etc.)
 
 ```bash
 $ touch a.txt
 ```
 
+<br/>
+
 Now let's try to close the workshell.
 
 ```bash
@@ -104,13 +129,17 @@ $ pf close
     pf close -f
 ```
 
+<br/>
+
 We aren't able to close because we have uncommitted changes. Let's commit them.
 
 ```bash
 $ git add -A && git commit -am "Add a.txt"
 ```
 
-Now we can close again. On a successful close, you'll be prompted to merge your changes into the base branch.
+<br/>
+
+Now we can try closing again. Since our changes can be fast-forwarded from the base branch, `pf` offers to auto-merge the changes.
 
 ```bash
 $ pf close
@@ -124,16 +153,12 @@ $ pf close
 ✓ Merged 'feat-1' into 'main'
 ```
 
-If you type `n`, you can manually handle your own merging logic. The changes you made are still available in the `feat-1` branch.
-
-If you type `never`, you can permanently disable the auto-merge prompt.
-
-<br/><br/> 
+<br/> 
 
 ## CLI
 
-```
-pf v0.x.y - Open branches in workshells
+```sh
+pf v0.x.y - Human- and agent-friendly Git multitasking
 
 Usage: pf <command> [options]
 
@@ -143,28 +168,33 @@ Commands:
   close           Exit current workshell
   ls              List orphaned worktrees
   status          Show current branch
-  rm <branch>     Delete a branch and its worktree
+  rm <branch>     Remove a branch's worktree
 
 Options:
   --help, -h      Show help
   --version, -v   Show version
 ```
 
+<br />
+
 ### List orphaned worktrees
 
 Normally the worktree will be auto-pruned when you close its associated workshell. If a worktree is left behind for some reason, you can list them with `pf ls`.
 
 ```sh
 $ pf ls
-┌──────────────────────┬────────┬─────────────────┐
-│ branch               │ status │ created         │
-├──────────────────────┼────────┼─────────────────┤
-│ main                 │ clean  │ -               │
-│ feat-1 *             │ clean  │ 5 minutes ago   │
-└──────────────────────┴────────┴─────────────────┘
+┌────────┬───────────┬───────────────┐
+│ branch │ status    │ created       │
+├────────┼───────────┼───────────────┤
+│ main * │ clean     │ -             │
+│ feat-1 │ 1 changed │ 5 minutes ago │
+└────────┴───────────┴───────────────┘
 ```
 
-### Open a branch
+<br />
+
+
+### Open a branch in a workshell
 
 You can open any existing Git branch in a workshell. 
 
@@ -175,6 +205,8 @@ $ pf open feat-1
 Type 'pf close' to return.
 ```
 
+<br />
+
 ### Show current branch status
 
 ```sh
@@ -184,25 +216,44 @@ worktree:  /path/to/zod
 status:    clean
 ```
 
-### Remove a branch
+<br />
+
+### Remove a worktree 
+
+Remove the worktree for a branch (the branch itself is kept):
 
 ```sh
 $ pf rm feat-1
 
-✓ Deleted feat-1
+✓ Pruned worktree for feat-1
 ```
 
+<br />
+
 ### Closing a workshell
 
 This closes the current workshell and auto-prunes the associated worktree. Your changes survive in your branch commits. 
 
 ```sh
-pf close
+$ pf close
+✓ Back in main
+  Pruned worktree. Your changes are still in the 'feat-1' branch.
+  To merge your changes:
+    git merge feat-1
+
+  Auto-merge? (y/n/never) y
+
+✓ Merged 'feat-1' into 'main'
 ```
 
+If the branch hasn't been pushed to a remote, you'll be prompted to auto-merge:
+
+- `y` — merge into base branch
+- `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 your changes**.
+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**.
 
 ```sh
-pf close --force
+$ pf close --force
 ```

package/dist/index.js

@@ -6337,19 +6337,6 @@ function newCommand(branchName, fromBranch) {
 import { mkdirSync as mkdirSync4 } from "fs";
 import { basename as basename4, dirname as dirname4, join as join4, relative as relative2 } from "path";
 function openCommand(branch) {
-  if (branch === "root") {
-    const mainWorktree2 = getMainWorktree();
-    const rootBranch = getWorktreeBranch(mainWorktree2);
-    console.log();
-    console.log(success(bold(rootBranch)), dim(`(root worktree)`));
-    console.log(dim("Type 'pf close' to return."));
-    console.log();
-    spawnShell(mainWorktree2);
-    console.log();
-    console.log(success("Exited root worktree"));
-    console.log();
-    return;
-  }
   if (isInsideWorktree()) {
     const currentBranch = getCurrentBranch();
     console.log();
@@ -7259,51 +7246,50 @@ function lsCommand(plain = false) {
 import { execSync as execSync3 } from "child_process";
 import { resolve as resolve2 } from "path";
 function rmCommand(branch, force = false) {
-  if (!branchExists(branch)) {
-    console.error(`Error: branch '${branch}' not found`);
+  const mainWorktree = getMainWorktree();
+  const mainBranch = getWorktreeBranch(mainWorktree);
+  if (branch === mainBranch) {
+    console.error(`Error: cannot remove root worktree`);
     process.exit(1);
   }
   const worktreePath = getWorktreeForBranch(branch);
-  if (worktreePath) {
-    const cwd = process.cwd();
-    const absWtPath = resolve2(worktreePath);
-    const absCwd = resolve2(cwd);
-    if (absCwd.startsWith(absWtPath)) {
-      console.error("Error: cannot remove current branch's worktree");
-      console.error(dim(`  Try: `) + cyan(`pf close`));
-      process.exit(1);
-    }
-    const status = getWorktreeStatus(worktreePath);
-    const isDirty = status !== "clean" && status !== "";
-    if (isDirty && !force) {
-      console.error(warn("Uncommitted changes found. Commit, stash, or reset your changes first."));
-      console.error(dim(`  Or run: `) + cyan(`pf rm ${branch} -f`));
-      process.exit(1);
-    }
-    if (isDirty && force) {
-      try {
-        execSync3(`git -C "${worktreePath}" reset --hard HEAD`, { stdio: "ignore" });
-        execSync3(`git -C "${worktreePath}" clean -fd`, { stdio: "ignore" });
-      } catch {
-      }
-    }
+  if (!worktreePath) {
+    console.error(`Error: no worktree found for branch '${branch}'`);
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  const absWtPath = resolve2(worktreePath);
+  const absCwd = resolve2(cwd);
+  if (absCwd === absWtPath || absCwd.startsWith(absWtPath + "/")) {
+    console.error("Error: cannot remove current worktree");
+    console.error(dim(`  Try: `) + cyan(`pf close`));
+    process.exit(1);
+  }
+  const status = getWorktreeStatus(worktreePath);
+  const isDirty = status !== "clean" && status !== "";
+  if (isDirty && !force) {
+    console.error(warn("Uncommitted changes found. Commit, stash, or reset your changes first."));
+    console.error(dim(`  Or run: `) + cyan(`pf rm ${branch} -f`));
+    process.exit(1);
+  }
+  if (isDirty && force) {
     try {
-      removeGitWorktree(worktreePath);
+      execSync3(`git -C "${worktreePath}" reset --hard HEAD`, { stdio: "ignore" });
+      execSync3(`git -C "${worktreePath}" clean -fd`, { stdio: "ignore" });
     } catch {
     }
-    pruneWorktrees();
-    const store = loadStore();
-    const worktreeId = getWorktreeId(worktreePath);
-    removeWorktreeMeta(store, worktreeId);
-    saveStore(store);
   }
   try {
-    deleteBranch(branch);
+    removeGitWorktree(worktreePath);
   } catch {
-    console.error(`Warning: failed to delete branch ${branch}`);
   }
+  pruneWorktrees();
+  const store = loadStore();
+  const worktreeId = getWorktreeId(worktreePath);
+  removeWorktreeMeta(store, worktreeId);
+  saveStore(store);
   console.log();
-  console.log(success(`Deleted ${bold(branch)}`));
+  console.log(success(`Pruned worktree for ${bold(branch)}`));
 }
 
 // commands/status.ts
@@ -7387,10 +7373,6 @@ function precloseCommand(force) {
     process.exit(0);
   }
   if (force) {
-    console.log();
-    if (!confirm("Force-closing will discard your unstaged changes. Continue?")) {
-      process.exit(1);
-    }
     try {
       execSync5("git reset --hard HEAD", { stdio: "ignore" });
       execSync5("git clean -fd", { stdio: "ignore" });
@@ -7405,7 +7387,7 @@ function precloseCommand(force) {
 }
 
 // index.ts
-var VERSION = "0.0.5";
+var VERSION = "0.0.6";
 function printHelp() {
   const dim2 = import_picocolors3.default.dim;
   const cyan2 = import_picocolors3.default.cyan;
@@ -7420,7 +7402,7 @@ ${import_picocolors3.default.bold("Commands:")}
   ${green2("close")}           Exit current subshell
   ${green2("ls")}              List open branches
   ${green2("status")}          Show current branch
-  ${green2("rm")} ${dim2("<branch>")}     Delete a branch and its worktree
+  ${green2("rm")} ${dim2("<branch>")}     Remove a branch's worktree
 
 ${import_picocolors3.default.bold("Options:")}
   ${cyan2("--help")}, ${cyan2("-h")}      Show help
@@ -7511,20 +7493,20 @@ ${import_picocolors3.default.bold("Description:")}
 function printRmHelp() {
   const dim2 = import_picocolors3.default.dim;
   const cyan2 = import_picocolors3.default.cyan;
-  console.log(`${import_picocolors3.default.bold("pf rm")} - Delete a branch and its worktree
+  console.log(`${import_picocolors3.default.bold("pf rm")} - Remove a branch's worktree
 
 ${import_picocolors3.default.bold("Usage:")} ${cyan2("pf rm")} ${dim2("<branch>")} ${dim2("[options]")}
 
 ${import_picocolors3.default.bold("Arguments:")}
-  ${dim2("<branch>")}  Branch to delete ${dim2("(required)")}
+  ${dim2("<branch>")}  Branch whose worktree to remove ${dim2("(required)")}
 
 ${import_picocolors3.default.bold("Options:")}
-  ${cyan2("-f")}, ${cyan2("--force")}  Discard uncommitted changes and delete
+  ${cyan2("-f")}, ${cyan2("--force")}  Discard uncommitted changes and remove
 
 ${import_picocolors3.default.bold("Description:")}
-  Deletes the specified branch and removes its worktree if one exists.
-  Fails if branch has uncommitted changes (use -f/--force to discard).
-  Cannot delete a branch you're currently inside.`);
+  Removes the worktree for the specified branch. The branch itself is kept.
+  Fails if worktree has uncommitted changes (use -f/--force to discard).
+  Cannot remove a worktree you're currently inside.`);
 }
 function printStatusHelp() {
   const cyan2 = import_picocolors3.default.cyan;
@@ -7602,9 +7584,6 @@ switch (cmd) {
     }
     openCommand(args[1]);
     break;
-  case "root":
-    openCommand("root");
-    break;
   case "ls":
     if (isHelp(args[1])) {
       printLsHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pf",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Agent- and human-friendly Git multitasking, powered by worktrees",
   "type": "module",
   "license": "MIT",