worktree-aid 1.0__py3-none-any.whl

worktree_aid-1.0.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: worktree-aid
+Version: 1.0
+Summary: Linux command line tool to aid creating, switching, and removing git worktrees
+Author-email: Mark Blakeney <mark.blakeney@bullet-systems.net>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/bulletmark/worktree-aid
+Keywords: git,worktree,fzf
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: coolname
+
+# worktree-aid
+[![PyPi](https://img.shields.io/pypi/v/worktree-aid)](https://pypi.org/project/worktree-aid/)
+[![AUR](https://img.shields.io/aur/version/worktree-aid)](https://aur.archlinux.org/packages/worktree-aid/)
+
+This is a Linux command line tool to conveniently add, remove, and change
+directories for [git worktrees][gitw]. A [fuzzy finder][fzf] is used to show
+current worktrees and prompt user for the name if not given.
+
+After following the instructions in the [Installation](#installation-or-upgrade)
+and [Setup](#setup) sections below, an `wt` shell command/alias is available to
+use to manage git worktrees. There are 3 commands typically used:
+
+- `wt add` (or `wt a`) to add a new worktree + branch and automatically cd to
+  it. If you don't specify a worktree name, a new unique name will be
+  automatically created for you.
+
+- `wt cd` (or `wt c`) to change directory to a specified worktree. You can use
+  `/` as a shortcut to the toplevel repository directory. If you don't specify a
+  worktree name, then a [fuzzy finder][fzf] will prompt you with a list of
+  worktrees to select from and be cd'd to.
+
+- `wt rm` (or `wt r`) to remove a worktree + branch. If you don't specify a
+  worktree name, then a [fuzzy finder][fzf] will prompt you with a list of
+  worktrees to select from. The current worktree is first in the list and is the
+  default selection to remove. If you delete the current worktree then you will
+  be automatically cd'd to the toplevel repository directory.
+
+There are some other options and commands available, as described in later
+sections. Type `wt` to see an overall help/usage summary, or `wt <command> -h`
+to see specific help/usage for any individual command.
+
+The project homepage and latest documentation is at
+https://github.com/bulletmark/worktree-aid.
+
+## Usage
+
+Type `wt` or `wt -h` to view the usage summary:
+
+```
+usage: wt [-B BASEDIR] [-R] [-U] [-F FUZZY] [-h] [-v]
+                       {add,a,rm,r,cd,c,ls,l,init} ...
+
+Linux command line tool to conveniently add, remove, and change directories
+for git worktrees. Prompts user to select worktree using fuzzy finder if no
+worktree name is given.
+
+options:
+  -B, --basedir BASEDIR
+                        base directory for newly added worktrees,
+                        default="../worktrees/{repo}".
+  -R, --relative        display worktree paths relative instead of absolute
+  -U, --no-user         do not substitute "~" for home directory
+  -F, --fuzzy FUZZY     fuzzy finder program, default="fzf"
+  -h, --help            show help message and exit
+  -v, --version         show program version and exit
+
+Commands:
+  {add,a,rm,r,cd,c,ls,l,init}
+    add (a)             Add new worktree + branch.
+    rm (r)              Remove worktree + branch.
+    cd (c)              Change directory to specified worktree.
+    ls (l)              List current worktrees.
+    init                Output shell initialization code.
+```
+
+Type `wt <command> -h` to see specific help/usage for any
+individual command:
+
+### Command `add`
+
+```
+usage: wt add [-h] [-d] [worktree]
+
+Add new worktree + branch.
+
+positional arguments:
+  worktree      new worktree + branch to add. A name is automatically created
+                if not specified.
+
+options:
+  -h, --help    show help message and exit
+  -d, --detach  add detached worktree only, i.e. without adding a new branch
+
+aliases: a
+```
+
+### Command `rm`
+
+```
+usage: wt rm [-h] [-k] [-f] [worktree]
+
+Remove worktree + branch.
+
+positional arguments:
+  worktree           worktree + branch name to remove. If not specified then
+                     fuzzy finder will prompt with a list of worktrees.
+
+options:
+  -h, --help         show help message and exit
+  -k, --keep-branch  remove worktree but keep branch
+  -f, --force        force removal of worktree + branch even if untracked or
+                     unmerged changes exist.
+
+aliases: r
+```
+
+### Command `cd`
+
+```
+usage: wt cd [-h] [worktree]
+
+Change directory to specified worktree.
+
+positional arguments:
+  worktree    Worktree name to change directory to. If not specified then
+              fuzzy finder will prompt with a list of worktrees.
+
+options:
+  -h, --help  show help message and exit
+
+aliases: c
+```
+
+### Command `ls`
+
+```
+usage: wt ls [-h]
+
+List current worktrees.
+
+options:
+  -h, --help  show help message and exit
+
+aliases: l
+```
+
+### Command `init`
+
+```
+usage: wt init [-h] [command]
+
+Output shell initialization code. Must be invoked using `source <(worktree-
+aid)` in your shell `~/.bashrc` or `~/.zshrc` initialization file to create
+the shell alias/function by which you invoke this program.
+
+positional arguments:
+  command     alternative command name, and optional default arguments,
+              default="wt"
+
+options:
+  -h, --help  show help message and exit
+```
+
+## Installation or Upgrade
+
+Python 3.10 or later is required. Install using [`uv tool`][uvtool]:
+
+```sh
+$ uv tool install worktree-aid
+
+# To upgrade:
+$ uv tool upgrade worktree-aid
+
+# To uninstall:
+$ uv tool uninstall worktree-aid
+```
+
+Or, on Arch Linux:
+
+```sh
+$ yay -S worktree-aid  # or your preferred AUR helper
+```
+
+You also need to install a fuzzy finder program such as [`fzf`][fzf] which is
+the default used by `worktree-aid`. See [fuzzy finder installation
+instructions](fuzzy-finder-installation) for possible alternatives.
+
+## Setup
+
+A user who wants to use `worktree-aid` must add the following line to their
+`~/.bashrc` (`bash` user) or `~/.zshrc` (`zsh` user). Ensure it is added
+after where your PATH is set up so that the command `worktree-aid` can be found. This
+creates the `wt` wrapper command in your interactive shell session as a tiny
+function.
+
+```sh
+source <(worktree-aid init)
+```
+
+Then log out and back in again to be able to use the new `wt` function in your
+shell.
+
+## Alternative Command Name
+
+You can use an alternative command name instead of the default `wt` if you
+prefer. To do this, simply append your desired command name as the first
+argument to the `worktree-aid init` option in your shell initialization code.
+
+E.g, to use the command name `wx` rather than the default `wt`, use the
+following in your `~/.bashrc` or `~/.zshrc` file:
+
+```sh
+source <(worktree-aid init wx)
+```
+
+Then log out/in, and then use `wx` command instead of the default `wt`.
+
+## Default Options
+
+You can also set default `worktree-aid` options by appending options in the shell
+initialization code, e.g:
+
+```sh
+source <(worktree-aid init "wt -R")
+```
+
+The above sets `-R` (for relative display of worktree directories) as default for your
+`wt` command.
+
+The following options are sensible candidates to set as default options:
+
+- `-B/--basedir`,
+- `-R/--relative`,
+- `-U/--no-user`,
+- `-F/--fuzzy`.
+
+## Worktree Base Directory
+
+The `-B/--basedir` option allows you to specify a base directory for newly added
+worktrees. It is set to a default as below but you can change this to any
+directory you like. It can be absolute or relative where relative paths are
+relative to base repository directory.
+
+- Default is `-B ../worktrees/{repo}` which is the same as the [Zed] editor uses.
+- E.g. can use `-B ../{repo}.worktrees` which is same as [VS Code] uses.
+- E.g. can use `-B ~/worktrees/{repo}` to put all worktrees in a subdirectory of your home   directory.
+
+The following place-markers can be used in the definition of the base directory:
+
+- `{repo}`: Substituted with the base name of the repository.
+- `{user}`: Substituted with the name of the user.
+- `{home}`: Substituted with the home directory of the user (also can use `~` at start of a path).
+
+Most likely if you will want to set a custom basedir then you will set `-B` as a
+[default option](#default-options).
+
+## Display as Relative Worktree Directories
+
+The `git worktree list` command displays absolute directory paths, and
+`worktree-aid` does also by default, but many users prefer them displayed as
+shorter relative paths. The Git worktree command does not provide this but you
+can enable it in `worktree-aid` by adding the `-R/--relative` option, e.g:
+
+```sh
+$ wt l
+../development 9796714 [development]
+../milestone1  bc921b8 [milestone1]
+../test        e6d965a [test]
+.              f76b8e0 [main]
+```
+
+Most likely you will want to set `-R` as a [default option](#default-options).
+
+## Fuzzy Finder Integration
+
+[`fzf`][fzf] is the default fuzzy finder used by `worktree-aid`, but you can use
+any of the popular other command line fuzzy search finders such as [`sk`][skim],
+[`tv`][television], or [`fzy`][fzy].
+
+E.g. to use [`sk`][skim], put this in your `~/.bashrc` or `~/.zshrc` file:
+
+```sh
+source <(worktree-aid init "wt -F sk")
+```
+
+You can also get fancy and add preview options etc to your fuzzy finder command line.
+Most likely you will want to set `-F` as a [default option](#default-options).
+
+## License
+
+GPL-3.0-or-later.
+
+[gitw]:  https://git-scm.com/docs/git-worktree
+[worktree-aid]: https://github.com/bulletmark/worktree-aid
+[PyPI]: https://pypi.org/project/worktree-aid
+[AUR]: https://aur.archlinux.org/packages/worktree-aid
+[uvtool]: https://docs.astral.sh/uv/guides/tools/#installing-tools
+[fzf]: https://github.com/junegunn/fzf
+[fzy]: https://github.com/jhawthorn/fzy
+[skim]: https://github.com/skim-rs/skim
+[television]: https://github.com/alexpasmantier/television
+[Zed]: https://zed.dev/
+[VS Code]: https://code.visualstudio.com/

worktree_aid-1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+worktree_aid.py,sha256=Y_6lnIcZQwII2X6z-EinbwQf9R1IGt5OwoS1QNOmtfY,15817
+worktree_aid-1.0.dist-info/METADATA,sha256=hPx3KSBViUYZJDy9HeQJiabM-m-aJ7TRu387mq9k7jo,9742
+worktree_aid-1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+worktree_aid-1.0.dist-info/entry_points.txt,sha256=KWqgwMgud29RLqut8zQc0Qt8V0GOo3FgIMEaoMRZzkg,51
+worktree_aid-1.0.dist-info/top_level.txt,sha256=Gapkg-MU1S0CSdMt3sfRe7jKB6cAJswkQSupI9qNymg,13
+worktree_aid-1.0.dist-info/RECORD,,

worktree_aid-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

worktree_aid-1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+worktree-aid = worktree_aid:main

worktree_aid-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+worktree_aid

worktree_aid.py

@@ -0,0 +1,567 @@
+"""
+Linux command line tool to conveniently add, remove, and change directories for
+git worktrees. Prompts user to select worktree using fuzzy finder if no worktree
+name is given.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import shlex
+import subprocess
+import sys
+from argparse import SUPPRESS, ArgumentParser, Namespace
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+PROG = Path(__file__).stem.replace('_', '-')
+HOME = Path.home()
+HASH_LEN = 7
+
+# Default command name (shell function) this program is installed as. Can be
+# changed using command line option.
+DEFCMD = 'wt'
+
+# Default fuzzy finder. Can be changed using command line option.
+DEFAULT_FUZZY = 'fzf'
+
+# Relative path from top level repo dir to directory for newly created
+# worktrees. Can be changed using command line option. Can use {user}, {repo},
+# and {home} as placeholders for the current user name, repo name, and home
+# directory.
+BASEDIR = '../worktrees/{repo}'
+
+# Set of worktree names that are shortcuts to the top-level worktree.
+TOPLEVEL_SHORTCUTS = {'/'}
+
+# Template for the shell code injected into user's shell session
+SHELLCODE = """
+!cmd() {
+    local d
+    d=$(!prog -_ "$@")
+    local r=$?
+
+    if [ $r -ne 0 ]; then
+        if [ $r -eq 2 ]; then
+            return 0
+        fi
+        return $r
+    fi
+
+    cd -- "$d"
+}
+"""
+
+
+def init_code(cmd: str) -> str:
+    "Return shell init code as string"
+    from string import Template
+
+    # We need to change the template delimiter because the standard
+    # delimiter "$" is too common in regular shell code .
+    class CTemplate(Template):
+        delimiter = '!'
+
+    prog = sys.argv[0]
+    arglist = cmd.split(maxsplit=1)
+    if len(arglist) > 1:
+        cmd, opts = arglist
+        prog += f' {opts}'
+
+    return CTemplate(SHELLCODE.strip()).substitute(cmd=cmd, prog=prog)
+
+
+def run(
+    cmd: Sequence[str],
+    *,
+    stdin: str | None = None,
+    capture: bool = True,
+    ignore_error: bool = False,
+) -> str:
+    "Run command and return stdout"
+    stdout = subprocess.PIPE if capture else open('/dev/tty', 'w')
+    try:
+        res = subprocess.run(cmd, stdout=stdout, text=capture, input=stdin)
+    except Exception as e:
+        sys.exit(f'error: failed to run command "{cmd[0]}": {e}')
+
+    if not ignore_error and res.returncode != 0:
+        sys.exit(res.returncode)
+
+    if capture:
+        return res.stdout.strip()
+
+    stdout.close()  # type: ignore
+    return ''
+
+
+def get_title(desc: str) -> str:
+    "Return single title line from command description"
+    res = []
+    for line in desc.splitlines():
+        line = line.strip()
+        res.append(line)
+        if line.endswith('.'):
+            return ' '.join(res)
+
+    sys.exit('Must end description with a full stop.')
+
+
+def unexpanduser(path: Path) -> Path:
+    "Return path name, with $HOME replaced by ~ (opposite of Path.expanduser())"
+    if path.parts[: len(HOME.parts)] != HOME.parts:
+        return path
+
+    return Path('~', *path.parts[len(HOME.parts) :])
+
+
+def generate_new_name(exists: Callable[[str], Any]) -> str:
+    "Generate a new worktree name"
+    from coolname import generate_slug
+
+    for _ in range(100):
+        if not exists(name := generate_slug(2)):
+            return name
+
+    sys.exit('error: failed to generate a new worktree name.')
+
+
+def print_version(args: Namespace) -> int:
+    "Print program version"
+    from importlib import metadata
+
+    try:
+        version = metadata.version(PROG)
+    except Exception:
+        version = '?'
+
+    if args._:
+        with open('/dev/tty', 'w') as tty:
+            print(version, file=tty)
+
+        return 2
+
+    print(version)
+    return 0
+
+
+def print_help(args: Namespace) -> int:
+    "Print program help message"
+    if 'parser' in args:
+        args.parser.print_help(sys.stderr)
+    else:
+        args._opt.print_help(sys.stderr)
+
+    return 2 if args._ else 0
+
+
+@dataclass
+class Tree:
+    "Data for an individual worktree"
+
+    path: Path
+    path_display: str
+    head: str = ''
+    branch: str = ''
+
+
+class Trees:
+    "Class to manage the collection of worktrees"
+
+    trees: list[Tree]
+    toplevel: Tree
+    current: Tree
+
+    @classmethod
+    def fetch(cls, args: Namespace) -> None:
+        "Get worktrees"
+        trees = []
+        tree = None
+        cwdparts = Path.cwd().parts
+        phere = pindex = -1
+        for line in run('git worktree list --porcelain'.split()).splitlines():
+            if not (line := line.strip()):
+                continue
+
+            if len(fields := line.split(maxsplit=1)) < 2:
+                continue
+
+            field, value = fields
+
+            if field == 'worktree':
+                path = Path(value)
+
+                if args.relative:
+                    path_display = os.path.relpath(path)
+                elif args.no_user:
+                    path_display = str(path)
+                else:
+                    path_display = str(unexpanduser(path))
+
+                plen = len(path.parts)
+                if path.parts == cwdparts[:plen] and plen > phere:
+                    phere = plen
+                    pindex = len(trees)
+
+                trees.append(tree := Tree(path, path_display))
+            elif tree:
+                if field == 'HEAD':
+                    tree.head = value[:HASH_LEN]
+                elif field == 'branch':
+                    tree.branch = value.split('/')[-1]
+
+        if not trees:
+            sys.exit('error: no worktrees found.')
+
+        if pindex > 0:
+            trees = [trees[pindex]] + trees[:pindex] + trees[pindex + 1 :]
+            cls.toplevel = trees[1]
+        else:
+            cls.toplevel = trees[0]
+
+        cls.current = trees[0]
+        cls.trees = trees
+
+    @classmethod
+    def get_trees(cls) -> list[str]:
+        "Fetch string list of worktrees"
+        pw = max(len(str(t.path_display)) for t in cls.trees)
+        lines = []
+        for t in cls.trees:
+            tlist = [f'{t.path_display:{pw}}']
+            if t.head:
+                tlist.append(t.head)
+            if t.branch:
+                tlist.append(f'[{t.branch}]')
+            else:
+                tlist.append('detached')
+
+            lines.append(' '.join(tlist))
+
+        return lines
+
+    @classmethod
+    def get_tree(cls, text: str) -> Tree | None:
+        "Return first tree where branch, then path name, then head matches given text"
+        for tree in cls.trees:
+            if tree.branch == text:
+                return tree
+
+        for tree in cls.trees:
+            if tree.path.name == text:
+                return tree
+
+        for tree in cls.trees:
+            if tree.head == text:
+                return tree
+
+    @classmethod
+    def create_worktree(cls, name: str, args: Namespace) -> Path:
+        "Create a new worktree and branch with the given name"
+        if not name:
+            name = generate_new_name(cls.get_tree)
+
+        try:
+            basedir = args.basedir.format(
+                user=getpass.getuser(), repo=cls.toplevel.path.name, home=str(HOME)
+            )
+        except Exception as e:
+            sys.exit(f'error: failed to format basedir: {e}')
+
+        basepath = Path(basedir).expanduser()
+        basepath = cls.toplevel.path / basepath
+        basepath.mkdir(parents=True, exist_ok=True)
+        path = basepath / name
+
+        cmd = 'git worktree add'.split()
+        if args.detach:
+            cmd.append('--detach')
+        run(cmd + [str(path)], capture=False)
+        return path
+
+    @classmethod
+    def remove_worktree(cls, name: str, args: Namespace) -> Path | None:
+        "Remove the worktree and branch with the given name"
+        if name:
+            if not (tree := cls.get_tree(name)):
+                sys.exit(f'error: no worktree found with name "{name}".')
+        else:
+            # If no name is given, remove the current worktree and branch
+            tree = cls.current
+
+        # Change to the top-level worktree directory before deleting a worktree
+        # and/or branch, in case the current directory is removed.
+        os.chdir(cls.toplevel.path)
+
+        cmd = 'git worktree remove'.split()
+        if args.force:
+            cmd.append('--force')
+
+        run(cmd + [str(tree.path)], capture=False)
+
+        path_display = os.path.relpath(tree.path) if args.relative else str(tree.path)
+        with open('/dev/tty', 'w') as tty:
+            print(f'Removed worktree "{path_display}"', file=tty)
+
+        if tree.branch and not args.keep_branch:
+            cmd = 'git branch'.split() + ['-D' if args.force else '-d']
+            run(cmd + [tree.branch], capture=False, ignore_error=True)
+
+        return cls.toplevel.path if tree == cls.current else None
+
+    @classmethod
+    def prompt(cls, args: Namespace) -> Path | None:
+        "Prompt user to select a worktree using fuzzy finder"
+        wtrees = cls.get_trees()
+        if not wtrees:
+            sys.exit('error: no worktrees to remove.')
+        line = run(shlex.split(args.fuzzy), stdin='\n'.join(wtrees)).strip()
+        if not line or line not in wtrees:
+            return None
+
+        return cls.trees[wtrees.index(line)].path
+
+
+def main() -> int:
+    "Main code"
+    # Main returns a status code:
+    # 0 = Directory written to stdout. Calling script will "cd" to that
+    #     worktree directory and return error code for that cd command result.
+    # 1 = Error/message already written to stderr via sys.exit(). Calling script
+    #     will silently quit and return that error code.
+    # 2 = Caller will silently quit and return exit code 0.
+
+    # Parse arguments
+    opt = ArgumentParser(description=__doc__, add_help=False)
+    opt.add_argument(
+        '-B',
+        '--basedir',
+        default=BASEDIR,
+        help='base directory for newly added worktrees, default="%(default)s".',
+    )
+    opt.add_argument(
+        '-R',
+        '--relative',
+        action='store_true',
+        help='display worktree paths relative instead of absolute',
+    )
+    opt.add_argument(
+        '-U',
+        '--no-user',
+        action='store_true',
+        help='do not substitute "~" for home directory',
+    )
+    opt.add_argument(
+        '-F',
+        '--fuzzy',
+        default=DEFAULT_FUZZY,
+        help='fuzzy finder program, default="%(default)s"',
+    )
+    opt.add_argument(
+        '-h', '--help', action='store_true', help='show help message and exit'
+    )
+    opt.add_argument(
+        '-v', '--version', action='store_true', help='show program version and exit'
+    )
+    opt.add_argument('-_', action='store_true', help=SUPPRESS)
+    cmd = opt.add_subparsers(title='Commands')
+
+    # Add each command ..
+    for name in globals():
+        if not name[0].islower() or not name.endswith('_'):
+            continue
+
+        cls = globals()[name]
+        name = name[:-1]
+
+        if hasattr(cls, 'doc'):
+            desc = cls.doc.strip()
+        elif cls.__doc__:
+            desc = cls.__doc__.strip()
+        else:
+            sys.exit(f'Must define a docstring for command class "{name}".')
+
+        title = get_title(desc)
+        aliases = cls.aliases if hasattr(cls, 'aliases') else []
+        cmdopt = cmd.add_parser(
+            name, description=desc, aliases=aliases, help=title, add_help=False
+        )
+        cmdopt.add_argument(
+            '-h', '--help', action='store_true', help='show help message and exit'
+        )
+
+        # Set up this commands own arguments, if it has any
+        if hasattr(cls, 'init'):
+            cls.init(cmdopt)
+
+        # Set the function to call
+        cmdopt.set_defaults(func=cls.run, parser=cmdopt)
+
+    args = opt.parse_args()
+    args._opt = opt
+
+    if args.version:
+        return print_version(args)
+
+    if args.help or 'func' not in args:
+        return print_help(args)
+
+    if out := args.func(args):
+        print(out)
+        return 0
+
+    return 2 if args._ else 0
+
+
+# COMMAND
+class add_:
+    "Add new worktree + branch."
+
+    aliases = ('a',)
+
+    @staticmethod
+    def init(parser: ArgumentParser) -> None:
+        parser.add_argument(
+            '-d',
+            '--detach',
+            action='store_true',
+            help='add detached worktree only, i.e. without adding a new branch',
+        )
+        parser.add_argument(
+            'worktree',
+            default='',
+            nargs='?',
+            help='new worktree + branch to add. A name is automatically created if not specified.',
+        )
+
+    @staticmethod
+    def run(args: Namespace) -> str | None:
+        Trees.fetch(args)
+        return str(Trees.create_worktree(args.worktree, args))
+
+
+# COMMAND
+class rm_:
+    "Remove worktree + branch."
+
+    aliases = ('r',)
+
+    @staticmethod
+    def init(parser: ArgumentParser) -> None:
+        parser.add_argument(
+            '-k',
+            '--keep-branch',
+            action='store_true',
+            help='remove worktree but keep branch',
+        )
+        parser.add_argument(
+            '-f',
+            '--force',
+            action='store_true',
+            help='force removal of worktree + branch even if '
+            'untracked or unmerged changes exist.',
+        )
+        parser.add_argument(
+            'worktree',
+            default='',
+            nargs='?',
+            help='worktree + branch name to remove. If not specified then '
+            'fuzzy finder will prompt with a list of worktrees.',
+        )
+
+    @staticmethod
+    def run(args: Namespace) -> str | None:
+        Trees.fetch(args)
+        if not (name := args.worktree):
+            if not (path := Trees.prompt(args)):
+                return None
+            name = path.name
+
+        if not (path := Trees.remove_worktree(name, args)):
+            return None
+
+        return str(path)
+
+
+# COMMAND
+class cd_:
+    "Change directory to specified worktree."
+
+    aliases = ('c',)
+
+    @staticmethod
+    def init(parser: ArgumentParser) -> None:
+        parser.add_argument(
+            'worktree',
+            default='',
+            nargs='?',
+            help='Worktree name to change directory to. If not specified then '
+            'fuzzy finder will prompt with a list of worktrees.',
+        )
+
+    @staticmethod
+    def run(args: Namespace) -> str | None:
+        Trees.fetch(args)
+        if name := args.worktree:
+            if name in TOPLEVEL_SHORTCUTS:
+                path = Trees.toplevel.path
+            elif tree := Trees.get_tree(name):
+                path = tree.path
+            else:
+                sys.exit(f'error: no worktree found with name "{name}".')
+        else:
+            path = Trees.prompt(args)
+
+        return str(path) if path else None
+
+
+# COMMAND
+class ls_:
+    "List current worktrees."
+
+    aliases = ('l',)
+
+    @staticmethod
+    def run(args: Namespace) -> str | None:
+        Trees.fetch(args)
+        trees = Trees.get_trees()
+        with open('/dev/tty', 'w') as tty:
+            for line in reversed(trees):
+                print(line, file=tty)
+
+        return None
+
+
+# COMMAND
+class init_:
+    doc = f"""
+    Output shell initialization code.
+    Must be invoked using `source <({PROG})` in your shell `~/.bashrc` or
+    `~/.zshrc` initialization file to create the shell alias/function by which
+    you invoke this program.
+    """
+
+    @staticmethod
+    def init(parser: ArgumentParser) -> None:
+        parser.add_argument(
+            'command',
+            nargs='?',
+            default=DEFCMD,
+            help='alternative command name, and optional default arguments, default="%(default)s"',
+        )
+
+    @staticmethod
+    def run(args: Namespace) -> str | None:
+        if args._:
+            sys.exit(
+                f'Must invoke using "{PROG}", not shell function, to output shell initialization code.'
+            )
+
+        return init_code(args.command)
+
+
+if __name__ == '__main__':
+    sys.exit(main())