pf 0.0.4 → 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pullfrog, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,57 +1,259 @@
-# pf
+<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/>
 
-A humane utility for git worktrees.
+<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/>
+
+## 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`. 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**).
+
+- 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`. **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. -->
+
+<!-- 
+## How does it work
+
+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).
+
+Here's how it works (key points in **bold**).
+
+- **A fresh worktree is created** — The `pf` utility a) creates a new worktree in `.git/pf/worktrees` and b) opens it in a *subshell*.
+- **Make edits and commit** — From the worksh your preferred IDE/agent.
+- **Commit your changes** — Though your file system is isolated, Git commit history (including branches) is still shared among all worktrees. 
+- **Exit the subshell** — Run `pf close` to exit the subshell. As with `git switch`, `pf close` won't let you close the subshell if you have unstaged/uncommitted changes.
+- **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. -->
+
+<br/>
+
+## Features
+
+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.
+- 🙅‍♂️ **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/>
+
+## Quickstart
+
+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
 ```
 
-## Usage
+<br/>
+
+Then clone a repo (any repo works):
 
+```bash
+$ git clone git@github.com:colinhacks/zod.git
+$ cd zod
 ```
-pf <command> [options]
 
-Commands:
-  new [name]   Create a branch and worktree with the specified name (default: "pf-[hash]")
-  open <name>  Open a worktree in a subshell
-  ls           List all tracked worktrees
-  rm <name>    Remove a worktree
+<br/>
 
-Options:
-  --help, -h       Show help
-  --version, -v    Show version
+After cloning, the `main` branch is checked out. Let's say we want to start work on a new feature:
+
+```bash
+$ pf new feat-1
+
+✓ feat-1 (from main)
+Opened branch in ephemeral subshell at .git/pf/worktrees/zod@feat-1
+Type 'pf close' to return.
 ```
 
-## Why `pf`?
+<br/>
+
+You're now in a workshell. Check where you are:
+
+```bash
+$ pwd
+/Users/colinmcd94/Documents/repos/zod/.git/pf/worktrees/zod@feat-1
+
+$ 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.
 
-In agentic development, you often want to spin up isolated workspaces for specific tasks—without stashing or committing your current changes. pf makes this effortless.
+```bash
+$ pf close
+⚠ Uncommitted changes found. Commit, stash, or reset your changes first.
+  Or use --force/-f to discard changes
+    pf close -f
+```
+
+<br/>
 
-Create a new worktree for a task:
+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"
 ```
-$ pf new add-login-button
+
+<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
+✓ 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'
 ```
 
-This creates a branch and worktree, then drops you into a subshell. Open it in your editor or point an AI coding agent at it. Your changes are completely independent of any other work on your machine.
+<br/> 
+
+## CLI
+
+```sh
+pf v0.x.y - Human- and agent-friendly Git multitasking
 
-When you're done, push to GitHub and create a PR:
+Usage: pf <command> [options]
 
+Commands:
+  new [branch]    Create a branch and open it [--from <branch>]
+  open <branch>   Open a branch in a workshell
+  close           Exit current workshell
+  ls              List orphaned worktrees
+  status          Show current branch
+  rm <branch>     Remove a branch's worktree
+
+Options:
+  --help, -h      Show help
+  --version, -v   Show version
 ```
-$ git push -u origin add-login-button
+
+<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 │ 1 changed │ 5 minutes ago │
+└────────┴───────────┴───────────────┘
 ```
 
-Or merge directly back into main:
+<br />
+
+
+### Open a branch in a workshell
 
+You can open any existing Git branch in a workshell. 
+
+```sh
+$ pf open feat-1
+
+✓ feat-1 (existing worktree)
+Type 'pf close' to return.
 ```
-$ git checkout main && git merge add-login-button
+
+<br />
+
+### Show current branch status
+
+```sh
+$ pf status
+branch:    main (root)
+worktree:  /path/to/zod
+status:    clean
 ```
 
-Then just `exit` to pop out of the worktree and back to your main repo. Clean up when you're done:
+<br />
 
+### Remove a worktree 
+
+Remove the worktree for a branch (the branch itself is kept):
+
+```sh
+$ pf rm feat-1
+
+✓ Pruned worktree for feat-1
 ```
-$ pf rm add-login-button
+
+<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
+✓ 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'
 ```
 
-Use `pf ls` to see your active worktrees, and `pf open <name>` to return to one later.
+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 uncommitted changes**.
+
+```sh
+$ pf close --force
+```