pf 0.0.2 → 0.0.5

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

@@ -0,0 +1,208 @@
+# `pf` — Human- and agent-friendly Git multitasking 
+
+<br/><br/>
+
+## Install
+
+```bash
+npm i -g pf
+```
+
+<br/><br/>
+
+## 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).
+
+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`, which **auto-prunes the associated worktree**.
+- Your changes still exist on the associated branch.
+
+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. -->
+
+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. ☕️
+
+🖥️ **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*.
+
+🌳 **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.
+
+🤖 **Agent-ready** — Spin up parallel workshells so multiple agents can work simultaneously without conflicts.
+
+<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`.
+
+```bash
+$ npm i -g pf
+```
+
+Then clone a repo (any repo works):
+
+```bash
+$ git clone git@github.com:colinhacks/zod.git
+$ cd zod
+```
+
+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.
+```
+
+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
+```
+
+Now let's make some changes. (You can also open the repo in an IDE, start an agent run, etc.)
+
+```bash
+$ touch a.txt
+```
+
+Now let's try to close the workshell.
+
+```bash
+$ pf close
+⚠ Uncommitted changes found. Commit, stash, or reset your changes first.
+  Or use --force/-f to discard changes
+    pf close -f
+```
+
+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.
+
+```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'
+```
+
+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/> 
+
+## CLI
+
+```
+pf v0.x.y - Open branches in workshells
+
+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>     Delete a branch and its worktree
+
+Options:
+  --help, -h      Show help
+  --version, -v   Show version
+```
+
+### 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   │
+└──────────────────────┴────────┴─────────────────┘
+```
+
+### Open a branch
+
+You can open any existing Git branch in a workshell. 
+
+```sh
+$ pf open feat-1
+
+✓ feat-1 (existing worktree)
+Type 'pf close' to return.
+```
+
+### Show current branch status
+
+```sh
+$ pf status
+branch:    main (root)
+worktree:  /path/to/zod
+status:    clean
+```
+
+### Remove a branch
+
+```sh
+$ pf rm feat-1
+
+✓ Deleted feat-1
+```
+
+### Closing a workshell
+
+This closes the current workshell and auto-prunes the associated worktree. Your changes survive in your branch commits. 
+
+```sh
+pf close
+```
+
+
+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**.
+
+```sh
+pf close --force
+```