From 3823998c90840ef5e70e6939cd75e4cde0fdea76 Mon Sep 17 00:00:00 2001 From: Rodrigo Espinosa Curbelo Date: Mon, 13 Apr 2026 13:19:56 -0300 Subject: [PATCH] docs: add man page and improve README Add a proper man page (doc/wt.1) covering all commands, options, shell integration, keyboard shortcuts, environment variables, and examples. Restructure the README with a quick start section and a full commands reference table. Update Makefile with install-man target and Homebrew formula to install the man page automatically. Co-Authored-By: Claude Opus 4.6 (1M context) --- Formula/wt.rb | 1 + Makefile | 7 ++- README.md | 79 ++++++++++++++++------- doc/wt.1 | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 234 insertions(+), 22 deletions(-) create mode 100644 doc/wt.1 diff --git a/Formula/wt.rb b/Formula/wt.rb index edb8b61..19519ba 100644 --- a/Formula/wt.rb +++ b/Formula/wt.rb @@ -9,6 +9,7 @@ class Wt < Formula def install bin.install "bin/wt" + man1.install "doc/wt.1" end test do diff --git a/Makefile b/Makefile index f4330a5..72b7915 100644 --- a/Makefile +++ b/Makefile @@ -4,7 +4,12 @@ install: install -d $(PREFIX)/bin install -m 755 bin/wt $(PREFIX)/bin/wt +install-man: + install -d $(PREFIX)/share/man/man1 + install -m 644 doc/wt.1 $(PREFIX)/share/man/man1/wt.1 + uninstall: rm -f $(PREFIX)/bin/wt + rm -f $(PREFIX)/share/man/man1/wt.1 -.PHONY: install uninstall +.PHONY: install install-man uninstall diff --git a/README.md b/README.md index 4628984..ca55703 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,12 @@ cd wt make install ``` +This installs `wt` to `/usr/local/bin` by default. Override with `PREFIX`: + +```sh +make install PREFIX=$HOME/.local +``` + ### Uninstall ```sh @@ -34,49 +40,80 @@ make uninstall # from source - `git` 2.5 or newer (for worktree support) - [fzf](https://github.com/junegunn/fzf) -## Usage +## Quick start -```sh -# Interactive fuzzy picker -wt +1. Install `wt` (see above). +2. Add shell integration to your rc file: -# Switch to a branch's worktree (creates it if it doesn't exist) -wt my-feature +```sh +# zsh +eval "$(wt init zsh)" -# Remove a worktree -wt -d my-feature +# bash +eval "$(wt init bash)" -# List all worktrees -wt -l +# fish +wt init fish | source ``` -The fzf picker shows a preview pane with the last 10 commits of the highlighted worktree. - -### Shell integration +3. Run `wt` inside any git repository. -`wt` ships a small shell function (via `wt init `) that wraps the binary and `cd`s into the selected worktree — a subprocess can't change the parent shell's directory on its own. Add to your `~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`: +## Usage ```sh -# zsh / bash -eval "$(wt init zsh)" # or bash - -# fish -wt init fish | source +wt # Interactive fuzzy picker +wt my-feature # Switch to branch worktree (creates if needed) +wt -d my-feature # Remove a worktree +wt -l # List all worktrees ``` -### Keyboard shortcuts in fzf +### Commands + +| Command | Description | +| ----------------- | -------------------------------------------------- | +| `wt` | Launch fzf to fuzzy-pick a worktree | +| `wt ` | Switch to the worktree for ``, creating it if it doesn't exist | +| `wt -d ` | Remove the worktree (and local branch) for `` | +| `wt -l` | List all worktrees with their paths | +| `wt init ` | Print shell integration for bash, zsh, or fish | +| `wt -h` | Show help | +| `wt -v` | Show version | + +### Shell integration + +`wt` prints the selected worktree path to stdout. A subprocess can't change the parent shell's working directory, so `wt init ` outputs a thin wrapper function that captures the path and `cd`s into it. It also provides tab completions for branches, worktrees, and options. + +### Keyboard shortcuts (fzf picker) | Key | Action | | -------- | ------------------------------- | | `Enter` | Select worktree (prints path) | | `Ctrl-D` | Delete the highlighted worktree | +The preview pane on the right shows the last 10 commits for the highlighted worktree. + ## Environment variables | Variable | Description | Default | | ------------- | ---------------------------------- | ------------------------ | | `WT_BASE_DIR` | Parent directory for new worktrees | Sibling of the repo root | +When `WT_BASE_DIR` is not set, new worktrees are created as siblings of the repository root. For example, if your repo is at `~/src/myproject`, worktrees are created under `~/src/`. + +## Man page + +A man page is included at `doc/wt.1`. To install it: + +```sh +# With make +make install-man + +# Or manually +cp doc/wt.1 /usr/local/share/man/man1/ +``` + +After installing, view it with `man wt`. + ## License -MIT +[MIT](LICENSE) diff --git a/doc/wt.1 b/doc/wt.1 new file mode 100644 index 0000000..3fccec6 --- /dev/null +++ b/doc/wt.1 @@ -0,0 +1,169 @@ +.TH WT 1 "2026-04-13" "wt 0.1.2" "User Commands" +.SH NAME +wt \- git worktree manager powered by fzf +.SH SYNOPSIS +.B wt +.RI [ branch ] +.br +.B wt +.B \-d +.I branch +.br +.B wt +.B \-l +.br +.B wt +.B init +.I shell +.SH DESCRIPTION +.B wt +is a command-line tool for managing git worktrees with an interactive +fuzzy finder interface provided by +.BR fzf (1). +It lets you quickly list, switch to, create, or remove worktrees without +remembering paths or typing long git commands. +.PP +With no arguments, +.B wt +launches +.B fzf +to fuzzy-pick from existing worktrees. +The preview pane shows the last 10 commits for the highlighted worktree. +.PP +With a +.I branch +argument, +.B wt +switches to the worktree for that branch, creating it if it doesn't exist. +.SH COMMANDS +.TP +.BI "init " shell +Print shell integration code for +.IR bash , +.IR zsh , +or +.IR fish . +The generated code defines a wrapper function and tab completions. +See +.B SHELL INTEGRATION +below. +.SH OPTIONS +.TP +.BI \-d " branch" +Remove the worktree for +.IR branch . +The worktree directory is deleted and the branch reference is cleaned up. +.TP +.B \-l +List all worktrees with their branch names and paths. +.TP +.B \-h +Show a brief help message and exit. +.TP +.B \-v +Show the version number and exit. +.SH SHELL INTEGRATION +A subprocess cannot change the parent shell's working directory. +The +.B init +command outputs a small shell function that wraps +.B wt +and automatically +.BR cd (1)s +into the selected worktree path. +It also provides tab completions for branches, worktrees, and options. +.PP +Add one of the following to your shell startup file: +.PP +.RS +.nf +# zsh (~/.zshrc) +eval "$(wt init zsh)" + +# bash (~/.bashrc) +eval "$(wt init bash)" + +# fish (~/.config/fish/config.fish) +wt init fish | source +.fi +.RE +.SH KEYBOARD SHORTCUTS +When using the interactive +.B fzf +picker: +.TP +.B Enter +Select the highlighted worktree (prints its path). +.TP +.B Ctrl-D +Delete the highlighted worktree. +.SH ENVIRONMENT +.TP +.B WT_BASE_DIR +Parent directory where new worktrees are created. +When not set, worktrees are created as siblings of the repository root +directory. +For example, if the repo is at +.IR ~/src/myproject , +worktrees are placed under +.IR ~/src/ . +.SH EXIT STATUS +.TP +.B 0 +Successful operation, or the user cancelled the fzf picker. +.TP +.B 1 +An error occurred (not a git repository, branch not found, etc.). +.SH EXAMPLES +Launch the interactive picker: +.PP +.RS +.nf +$ wt +.fi +.RE +.PP +Switch to (or create) a worktree for branch +.IR feature/login : +.PP +.RS +.nf +$ wt feature/login +.fi +.RE +.PP +Remove the worktree for branch +.IR feature/login : +.PP +.RS +.nf +$ wt -d feature/login +.fi +.RE +.PP +List all worktrees: +.PP +.RS +.nf +$ wt -l +main /home/user/src/myproject +feature/login /home/user/src/feature/login +.fi +.RE +.PP +Use a custom base directory for worktrees: +.PP +.RS +.nf +$ export WT_BASE_DIR=~/worktrees +$ wt feature/signup +.fi +.RE +.SH SEE ALSO +.BR git-worktree (1), +.BR fzf (1), +.BR git (1) +.SH AUTHORS +Rodrigo Espinosa Curbelo +.SH LICENSE +MIT License. See the LICENSE file in the source distribution.