# branchout

create new git branches from the right source branch inside [pi](https://pi.dev), without memorizing branch names.

![branchout demo](media/demo.gif)

## why install it

- `/branchout` opens a branch picker, asks for a new branch name, and creates it from the selected source.
- direct forms still work for fast keyboard-driven workflows.
- every git operation is explicit, argv-only, and runs in pi's current working directory.
- no telemetry, daemon, shell interpolation, force operations, stashing, rebasing, merging, or automatic commits.

## install

```bash
pi install npm:branchout
```

then run `pi` in any git repository and use `/branchout`.

## commands

| command | behavior |
| --- | --- |
| `/branchout` | pick a local source branch, enter a new branch name, and create it from the updated source |
| `/branchout new-branch` | create `new-branch` from `main` |
| `/branchout -b source-branch new-branch` | create `new-branch` from `source-branch` |

## what it runs

`/branchout` validates branch names with `git check-ref-format --branch`, then runs:

```bash
git fetch origin <source>
git checkout <source>
git pull --ff-only origin <source>
git checkout -b <new> <source>
```

All git commands are executed with argv arrays in pi's current working directory. No shell interpolation, stashing, resetting, rebasing, merging, force operations, automatic commits, telemetry, or background service.

## behavior notes

- bare `/branchout` lists local branches only.
- `main` appears first when present; other branches stay recent-first.
- cancelling the picker or input prompt does not mutate git state.
- `/branchout` uses `--ff-only`; divergent source updates fail instead of merging.
- repositories without `origin` fail normally because the command fetches and pulls from `origin`.
- dirty worktrees are left to git: compatible edits may carry across; conflicting checkouts fail.

## update / remove

```bash
pi update npm:branchout
pi remove npm:branchout
```

## pi package gallery

branchout is published as a pi package with the `pi-package` keyword and a `pi.extensions` manifest, so it is discoverable through the pi package gallery after npm indexing.

## troubleshooting

see [docs/troubleshooting.md](docs/troubleshooting.md).

## development

see [docs/development.md](docs/development.md).

## security

see [SECURITY.md](SECURITY.md) and [docs/security-model.md](docs/security-model.md).