oh-my-worktree 0.10.2 → 0.14.1

package/README.md

@@ -1,100 +1,211 @@
 # owt (oh-my-worktree)
 
-A TUI tool for managing Git worktrees from either regular repositories or bare `.bare` layouts.
+[한국어](./README.ko.md) | [English](./README.md)
 
-Run it from a `.bare` worktree layout or from a regular non-bare Git repository. For regular repositories, new worktrees are created under `~/.owt/worktree/<repo-name>/` by default.
+A fast terminal UI for developers who use Git branches as working contexts, not bookmarks.
 
-## Installation
+<img width="786" height="580" alt="Image" src="./owt.png" />
+
+## Why owt exists
+
+Modern development rarely happens on one branch at a time. You might be reviewing a PR, testing a hotfix, keeping a long-running feature open, and checking main before a release. Plain `git switch` makes that workflow expensive because every context switch drags along uncommitted files, dependencies, editor state, and mental state.
+
+Git worktrees solve the underlying problem. `owt` makes them easy enough to use every day.
+
+Open `owt`, pick a worktree, create another one, delete the stale ones, fetch, pull, push, or merge without remembering the exact Git incantation. It works from a normal repository and from the `.bare` layout if you prefer keeping all worktrees side by side.
+
+## What you get
+
+- A keyboard-first TUI for browsing and managing worktrees
+- First-class support for existing regular repositories
+- Optional `.bare` project layout for teams that like sibling worktrees
+- Fast worktree creation from local or remote branches
+- Dirty-state, ahead/behind, last-commit, and GitHub PR status visibility
+- Built-in fetch, pull, push, upstream merge, branch merge, editor open, terminal open, and path copy
+- Shell integration so `Enter` can move your shell into the selected worktree
+
+## Install
+
+Current release with Cargo (`v0.13.0`):
+
+```bash
+cargo install --git https://github.com/dding-g/oh-my-worktree --tag v0.13.0 --force
+```
+
+Prebuilt binaries are attached to the latest [GitHub Release](https://github.com/dding-g/oh-my-worktree/releases/latest).
+
+This npm wrapper is also supported when the npm registry package is current:
 
 ```bash
 npm install -g oh-my-worktree
 ```
 
-Or use with npx:
+From source:
 
 ```bash
-npx oh-my-worktree
+git clone https://github.com/dding-g/oh-my-worktree.git
+cd oh-my-worktree
+cargo build --release
 ```
 
-## Quick Start
+## Start from the repo you already have
+
+You do not need to convert your repository.
 
 ```bash
-# Run directly inside an existing regular Git repository
-cd /path/to/regular-git-repo
+cd ~/src/my-app
 owt
+```
+
+In a regular repository, new worktrees are created under:
+
+```text
+~/.owt/worktree/<repo-name>/
+```
+
+Set `worktree_root` if you want them somewhere else.
+
+## Or start with a `.bare` workspace
 
-# Or clone into the .bare sibling layout
+If you like all worktrees living inside one project folder, use `owt clone`.
+
+```bash
 owt clone https://github.com/user/repo.git
 cd repo/main
+owt
+```
+
+That creates a layout like this:
 
-# Run TUI
+```text
+repo/
+├── .bare/
+├── main/
+├── feature-login/
+└── hotfix-api/
+```
+
+`owt init` prints a conversion guide if you want to move an existing repository into this layout manually.
+
+## Daily workflow
+
+```bash
 owt
 ```
 
-## Key Bindings
+Then use the TUI:
 
-### Navigation
 | Key | Action |
-|-----|--------|
-| `j` / `↓` | Move down |
-| `k` / `↑` | Move up |
-| `g` | Jump to current worktree |
-| `gg` | Jump to top |
-| `G` | Jump to bottom |
-| `/` | Search/filter |
-
-### Worktree Actions
-| Key | Action |
-|-----|--------|
-| `Enter` | Enter selected worktree |
-| `a` | Add new worktree |
-| `d` | Delete worktree |
-| `o` | Open in editor |
-| `t` | Open in terminal |
-| `y` | Copy path to clipboard |
-
-### Other
-| Key | Action |
-|-----|--------|
+| --- | --- |
+| `j` / `k` | Move selection |
+| `Enter` | Enter the selected worktree |
+| `a` | Add a worktree |
+| `d` | Delete a worktree |
 | `f` | Fetch remotes |
-| `r` | Refresh list |
+| `p` / `P` | Pull / push |
+| `m` / `M` | Merge upstream / merge selected branch |
+| `o` / `t` | Open in editor / terminal |
+| `y` | Copy path |
+| `/` | Filter |
 | `s` | Cycle sort mode |
-| `c` | Open config |
-| `?` | Show help |
+| `c` | View config |
+| `?` | Help |
 | `q` | Quit |
 
-## Adding Worktrees
+## What the list tells you
+
+| Signal | Meaning |
+| --- | --- |
+| `✓ clean` | No local changes |
+| `+ staged` | Staged changes |
+| `~ unstaged` | Unstaged changes |
+| `! conflict` | Merge conflict |
+| `* mixed` | Staged and unstaged changes |
+| `↑N` / `↓N` | Ahead / behind upstream |
+| `PR` | GitHub PR state: `open`, `closed`, `merged`, `draft`, or `-` |
+
+The `PR` column is GitHub-only and best-effort. No PR, non-GitHub remotes, missing auth, network failures, and unknown states all show `-` so the worktree list stays fast and reliable.
+
+## Plain CLI for agents
+
+Use noun command groups when you need stable, non-TUI output:
+
+```bash
+owt worktree list
+owt worktree create feature/login --base main
+owt worktree delete feature/login --branch --force
+owt worktree prune
+owt worktree prune --dry-run
+owt pr status --branch feature/login
+owt commit tree -n 12
+owt search login
+```
 
-Press `a`, type the new branch name, and press `Enter`. Use `Tab` in the add dialog to cycle the base branch for the new worktree.
+Agent bootstrap assets are versioned in the repository under `.agents/`: use `.agents/prompts/install-owt.md`, `.agents/skills/owt-install/SKILL.md`, and `.agents/skills/owt-worktree/SKILL.md` so worktree handling goes through `owt`.
 
-## Status Icons
+`worktree prune` logs every worktree decision as tab-separated output. Normal mode removes non-current clean worktrees whose branch is already merged into `HEAD`, except the `HEAD` branch worktree itself; `--dry-run` previews stale metadata pruning, prompts through removable candidates, and records selected candidates without deleting them.
 
-| Icon | Meaning |
-|------|---------|
-| `✓` | Clean |
-| `+` | Staged changes |
-| `~` | Unstaged changes |
-| `!` | Conflicts |
-| `*` | Staged + Unstaged |
+## Shell integration
 
-The worktree list also includes a `PR` column for GitHub pull request state. It shows only `open`, `closed`, `merged`, or `draft`; branches without a GitHub PR, non-GitHub remotes, lookup failures, and unknown states show `-`.
+Install the shell helper:
+
+```bash
+owt setup
+```
+
+Reload your shell. After that, pressing `Enter` in the TUI exits `owt` and moves the current shell into the selected worktree. When you create a worktree from the TUI, `owt` exits the TUI first, creates the worktree, runs copy/post-add/tmux steps in the normal terminal, then hands off to the new worktree path. Without shell integration, `owt` still prints the target path for wrapper scripts and manual use.
 
 ## Configuration
 
-Config file: `~/.config/owt/config.toml`
+Config file:
+
+```text
+~/.config/owt/config.toml
+```
+
+Example:
 
 ```toml
 editor = "code"
 terminal = "Ghostty"
 worktree_root = "~/.owt/worktree"
 copy_files = [".env", ".envrc"]
+post_add_script = ".owt/post-add.sh"
+tmux_worktree_mode = false
+run_post_add_script_in_tmux = false
 ```
 
+Useful options:
+
+| Option | Purpose |
+| --- | --- |
+| `editor` | Command used by `o` |
+| `terminal` | Terminal app used by `t` |
+| `worktree_root` | Root for new worktrees in regular repositories |
+| `copy_files` | Files copied into new worktrees. Only files are copied; copy problems are shown as warnings after creation. |
+| `post_add_script` | Script path for post-add setup. Relative paths use the current effective project root. |
+| `tmux_worktree_mode` | Open a tmux pane in each new worktree and focus an existing matching pane on `Enter`. |
+| `run_post_add_script_in_tmux` | Run the post-add script in detached tmux after creating a worktree. Only global config can enable this. |
+
+Project config in `.owt/config.toml` can override safe values, including `post_add_script`, but it cannot enable automatic post-add execution. A regular linked worktree only reads its own project config; it does not inherit an ancestor `.owt/config.toml`.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `owt [PATH]` | Open the TUI for a repository or worktree |
+| `owt clone <URL> [PATH]` | Clone into the `.bare` layout and create the first worktree |
+| `owt init` | Print a manual conversion guide for `.bare` layout |
+| `owt setup` | Install shell integration |
+| `owt --version` | Print version |
+
 ## Requirements
 
-- Git 2.5+ (for worktree support)
-- A Git repository
+- Git 2.5+
+- A regular Git repository or a `.bare` worktree layout
+- Optional: GitHub CLI `gh` for PR status
+- Optional: tmux for worktree pane mode and post-add setup scripts
 
-## More Information
+## License
 
-For more details, visit the [GitHub repository](https://github.com/dding-g/oh-my-worktree).
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-worktree",
-  "version": "0.10.2",
+  "version": "0.14.1",
   "description": "A TUI tool for managing Git worktrees in bare and regular repositories",
   "keywords": [
     "git",
@@ -20,7 +20,7 @@
     "type": "git",
     "url": "https://github.com/dding-g/oh-my-worktree"
   },
-  "homepage": "https://github.com/dding-g/oh-my-worktree#readme",
+  "homepage": "https://dding-g.github.io/oh-my-worktree/",
   "bugs": {
     "url": "https://github.com/dding-g/oh-my-worktree/issues"
   },