feat: add wtt init command and symlink_files config support (#6)

Author: songtov

.wtt.toml

@@ -1,3 +1,17 @@
+# wtt configuration
+# See: https://github.com/songtov/wtt
 
+# Directory for worktrees (relative to repo root)
+# worktree_dir = "../<reponame>-worktrees"
+
+# Files to copy into new worktrees
 copy_files = [".env", ".gitignore"]
 
+# Directories to copy into new worktrees
+# copy_dirs = []
+
+# Files to symlink (shared with main repo) into new worktrees
+symlink_files = [".claude/settings.local.json"]
+
+# Commands to run after creating a worktree
+post_create = ["echo hello"]

Makefile

@@ -1,4 +1,4 @@
-VERSION ?= v0.5.0
+VERSION ?= v0.6.0
 
 build:
 	go build -ldflags "-X github.com/songtov/wtt/cmd.Version=$(VERSION)" -o wtt-bin .

README.md

@@ -1,8 +1,10 @@
 # wtt — Git Worktree Manager
 
-**wtt** stands for **worktree-tov**.
+A fast, opinionated Git worktree manager.
 
-`wtt` wraps `git worktree` to create, navigate, and remove worktrees with minimal friction.
+**wtt** = **w**ork**t**ree-**tov**
+
+---
 
 ## Installation
 
@@ -11,74 +13,219 @@ brew tap songtov/tap
 brew install wtt
 ```
 
-To update to the latest version:
+To update:
 
 ```sh
 brew update && brew upgrade wtt
 ```
 
-Then add the shell integration so `wtt` can `cd` for you.
+[fzf](https://github.com/junegunn/fzf) is optional but recommended — used for interactive pickers.
+
+### Shell integration
+
+The shell wrapper is what lets `wtt` `cd` into worktrees. Add one of these to your shell config and reload.
 
-**zsh** — add to `~/.zshrc`:
+**zsh** — `~/.zshrc`:
 ```sh
 eval "$(wtt-bin --init zsh)"
 ```
 
-**bash** — add to `~/.bashrc` or `~/.bash_profile`:
+**bash** — `~/.bashrc` or `~/.bash_profile`:
 ```sh
 eval "$(wtt-bin --init bash)"
 ```
 
-**fish** — add to `~/.config/fish/config.fish`:
+**fish** — `~/.config/fish/config.fish`:
 ```sh
 wtt-bin --init fish | source
 ```
 
-Reload your shell after (`source ~/.zshrc` or equivalent).
+`--init` also wires up [shell prompt integration](#shell-prompt) automatically — no extra config needed.
 
-## Usage
+---
+
+## Quick Start
 
 ```sh
-# Create a worktree — auto-generates a branch name if omitted
+# Create a worktree with a random branch name, then navigate into it
 wtt create
+
+# Create a worktree for a specific branch
 wtt create feature/login
 
-# Navigate to a worktree (cds into the directory)
-wtt feature/login
+# Create a worktree branching from a specific ref
+wtt create feature/login -b main
 
-# Pick a worktree interactively with fzf, then navigate
+# Pick a worktree interactively and navigate to it
 wtt list
 
-# Remove a worktree — pick interactively if no branch given
-wtt remove
+# Remove a worktree (interactive picker if no branch given)
 wtt remove feature/login
-wtt remove --force feature/login   # skip confirmation
 ```
 
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `wtt create [branch]` | Create a new worktree |
+| `wtt list` | List worktrees and navigate interactively |
+| `wtt remove [branch]` | Remove a worktree |
+| `wtt <branch>` | Navigate directly to a worktree |
+| `wtt init` | Scaffold a `.wtt.toml` config file |
+| `wtt repo list` | Switch the active repository context |
+| `wtt repo remove` | Remove a repo from the known repos list |
+| `wtt version` | Print version |
+
+### `wtt create [branch]`
+
+Creates a new worktree and navigates into it.
+
+```sh
+wtt create                      # random name (e.g. myrepo-crisp-summit)
+wtt create feature/login        # specific branch
+wtt create feature/login -b main  # branch from main instead of HEAD
+```
+
+| Flag | Description |
+|---|---|
+| `-b, --base <ref>` | Base commit/branch/ref (default: `HEAD`) |
+
+### `wtt list`
+
+Opens an fzf picker to select and navigate to a worktree. Falls back to a numbered list if fzf is not installed.
+
+```sh
+wtt list
+```
+
+### `wtt remove [branch]`
+
+Removes a worktree. Opens an interactive picker if no branch is given.
+
+```sh
+wtt remove                      # pick interactively
+wtt remove feature/login
+wtt remove -f feature/login     # skip confirmation + force-remove from git
+```
+
+| Flag | Description |
+|---|---|
+| `-f, --force` | Skip confirmation prompt and pass `--force` to `git worktree remove` |
+
+### `wtt <branch>`
+
+Navigate directly to a worktree by branch name.
+
+```sh
+wtt feature/login
+```
+
+### `wtt init`
+
+Scaffolds a `.wtt.toml` in the repo root with commented-out defaults.
+
+```sh
+wtt init          # fails if .wtt.toml already exists
+wtt init -f       # overwrite existing file
+```
+
+| Flag | Description |
+|---|---|
+| `-f, --force` | Overwrite an existing `.wtt.toml` |
+
+### `wtt repo list`
+
+Switches the active repository context — kubens-style. After switching, all `wtt` commands (`create`, `list`, `remove`) operate on the selected repo, even when run from outside it.
+
+```sh
+wtt repo list
+```
+
+### `wtt repo remove`
+
+Removes a repository from the known repos list.
+
+```sh
+wtt repo remove
+wtt repo remove -f    # skip confirmation
+```
+
+| Flag | Description |
+|---|---|
+| `-f, --force` | Skip confirmation prompt |
+
+---
+
 ## Configuration
 
-Create `.wtt.toml` in your repo root to customize behavior:
+Run `wtt init` to create a `.wtt.toml` in your repo root, then edit it:
+
+```sh
+wtt init
+```
+
+### Config keys
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `worktree_dir` | string | `../<repo>-worktrees` | Directory where worktrees are created |
+| `copy_files` | list | `[".gitignore"]` | Files copied from the main worktree into each new worktree |
+| `copy_dirs` | list | `[]` | Directories copied recursively into each new worktree |
+| `symlink_files` | list | `[]` | Files symlinked (not copied) — changes in one worktree are shared across all |
+| `post_create` | list | `[]` | Shell commands run inside the new worktree after creation |
+
+### Example `.wtt.toml`
 
 ```toml
-# Where to put worktrees (default: ../<repo>-worktrees)
+# Where to create worktrees (default: ../<repo>-worktrees)
 worktree_dir = "../myproject-worktrees"
 
-# Files to copy from main worktree into each new worktree (default: [".gitignore"])
+# Files copied into each new worktree
 copy_files = [".gitignore", ".env.local"]
 
-# Directories to copy recursively
-copy_dirs = []
+# Directories copied recursively
+copy_dirs = ["scripts"]
+
+# Files symlinked — edits in any worktree are reflected everywhere
+symlink_files = [".env.secrets"]
 
-# Commands to run inside the new worktree after creation
+# Commands run inside the new worktree after creation
 post_create = ["npm install"]
 ```
 
+---
+
+## Shell Prompt
+
+`--init` automatically injects the active repository name into your shell prompt — no manual configuration needed.
+
+| Shell | Where it appears | Framework notes |
+|---|---|---|
+| zsh | Right prompt (`RPROMPT`) | Auto-injects into Powerlevel10k as a custom segment; falls back to generic `RPROMPT` for plain zsh and oh-my-zsh |
+| bash | Left prompt (`PS1`) | Prepended via `PROMPT_COMMAND` |
+| fish | Right prompt | Defines `fish_right_prompt` if not already set; for Tide/Starship call `wtt_segment` from your theme hook |
+
+The prompt segment is powered by `wtt-bin context` internally. There is no separate `wtt context` command intended for direct use.
+
+---
+
 ## How It Works
 
-A child process can't change the parent shell's directory, so `wtt` ships as `wtt-bin` plus a shell wrapper function. When a command prints a directory path, the wrapper `cd`s into it — the same pattern used by `nvm` and `direnv`.
+A child process can't change the parent shell's directory, so `wtt` ships as two parts:
+
+1. **`wtt-bin`** — the Go binary that does the work
+2. **`wtt`** — a shell function (installed by `--init`) that runs `wtt-bin` and `cd`s into the output if it's a directory
+
+This is the same pattern used by tools like `nvm` and `direnv`.
 
 Worktrees land at `../<repo>-worktrees/<branch>/` by default. Slashes in branch names become dashes (`feature/login` → `feature-login`).
 
+When fzf is not installed, interactive pickers fall back to a numbered list — `wtt list` and `wtt remove` always work regardless.
+
+---
+
 ## Contributing
 
 Contributions are welcome! Here's how to get started:

cmd/create.go

@@ -72,6 +72,9 @@ func runCreate(cmd *cobra.Command, args []string) error {
 	if err := worktree.CopyDirs(repoRoot, worktreePath, cfg.CopyDirs); err != nil {
 		fmt.Fprintf(os.Stderr, "Warning: copying dirs: %v\n", err)
 	}
+	if err := worktree.SymlinkFiles(repoRoot, worktreePath, cfg.SymlinkFiles); err != nil {
+		fmt.Fprintf(os.Stderr, "Warning: symlinking files: %v\n", err)
+	}
 
 	// Run post_create commands
 	for _, command := range cfg.PostCreate {

cmd/init.go

@@ -0,0 +1,63 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+)
+
+const wttTomlTemplate = `# wtt configuration
+# See: https://github.com/songtov/wtt
+
+# Directory for worktrees (relative to repo root)
+# worktree_dir = "../<reponame>-worktrees"
+
+# Files to copy into new worktrees
+copy_files = [".env", ".gitignore"]
+
+# Directories to copy into new worktrees
+# copy_dirs = []
+
+# Files to symlink (shared with main repo) into new worktrees
+symlink_files = [".claude/settings.local.json"]
+
+# Commands to run after creating a worktree
+# post_create = []
+`
+
+var initForce bool
+
+func init() {
+	initCmd.Flags().BoolVarP(&initForce, "force", "f", false, "Overwrite existing .wtt.toml")
+}
+
+var initCmd = &cobra.Command{
+	Use:   "init",
+	Short: "Create a .wtt.toml configuration file",
+	Long:  `Scaffold a .wtt.toml configuration file in the repo root.`,
+	Args:  cobra.NoArgs,
+	RunE:  runInit,
+}
+
+func runInit(cmd *cobra.Command, args []string) error {
+	repoRoot, err := repoRootWithFallback()
+	if err != nil {
+		return err
+	}
+
+	dest := filepath.Join(repoRoot, ".wtt.toml")
+
+	if _, err := os.Stat(dest); err == nil && !initForce {
+		fmt.Fprintf(os.Stderr, "`.wtt.toml` already exists. Use `wtt init -f` to overwrite.\n")
+		return nil
+	}
+
+	if err := os.WriteFile(dest, []byte(wttTomlTemplate), 0o644); err != nil {
+		return fmt.Errorf("writing .wtt.toml: %w", err)
+	}
+
+	fmt.Fprintf(os.Stderr, "Created %s\n", dest)
+	return nil
+}

cmd/root.go

@@ -34,6 +34,7 @@ func init() {
 	rootCmd.AddCommand(versionCmd)
 	rootCmd.AddCommand(repoCmd)
 	rootCmd.AddCommand(contextCmd)
+	rootCmd.AddCommand(initCmd)
 }
 
 // repoRootWithFallback returns the git repo root for the current directory.