git-workspace-bare 0.1.1 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 Manage Git worktrees as development workspaces.
 
-The CLI can clone GitHub repositories, create branch worktrees, list registered checkouts, and unregister them.
+The CLI can clone GitHub repositories or initialize them locally, create branch worktrees, list registered checkouts, and unregister them.
 
 ## Installation
 
@@ -14,6 +14,57 @@ npm install -g bare git-workspace-bare
 
 This makes the `git-workspace` command available in your shell. Git also discovers it on your `PATH`, so you can run it as `git workspace`. Bare must be on your `PATH`; Node.js and npm are used for package installation and development tooling.
 
+For optional integrations such as tmux session management, see [available hooks](#available-hooks).
+
+### Manual page
+
+The package includes a `git-workspace(1)` manual covering commands, options,
+manifest synchronization, and hooks:
+
+```sh
+git workspace --help
+git help workspace
+man git-workspace
+```
+
+Global installation (or `npm link` during development) registers the page with npm
+versions that support man-page linking. If your system cannot find it, add this line
+to your shell startup file to include the packaged manual in its search path:
+
+```sh
+export MANPATH="$(npm root -g)/git-workspace-bare/man:${MANPATH:-}"
+```
+
+The trailing empty entry preserves your system's default manual paths. This also
+works with npm 12, which no longer registers man pages automatically.
+
+If a shell wrapper intercepts `git workspace --help` and shows CLI usage instead,
+use `git help workspace` or `man git-workspace` to open the manual directly.
+
+### Bash completion
+
+Add this line to `~/.bashrc` (or the startup file your interactive Bash shell loads):
+
+```bash
+eval "$(git-workspace completion bash)"
+```
+
+For `git workspace` completion, also enable [Git's Bash completion](https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Bash).
+The workspace script extends it; existing Git completions are preserved. The direct
+`git-workspace` command has completion even without Git's completion script. Open a new shell
+or run that line in your current shell to enable it. Bash 3.2 and newer are supported.
+
+Tab completes commands, flags, and registered repository/worktree names for `remove` and
+the source of `rename`. For `add`, it suggests registered roots; after `owner/repo@`, it
+suggests local branches and already-fetched origin branches. New repository and branch names
+can still be typed freely. Completed repository names have no trailing space, so you can
+press Enter or append `@` and complete a branch. For a branch rename's destination, it fills the `owner/repo@`
+prefix so you can type the new branch name.
+
+Suggestions use local data only, without fetching or changing the workspace. Missing or
+invalid workspace data silently produces no repository suggestions; commands and flags
+remain available before `init`. Currently only Bash is supported.
+
 ## Usage
 
 ```sh
@@ -22,11 +73,12 @@ git workspace --version
 git workspace init nicolasfont/workspace
 git workspace add holepunchto/brittle
 git workspace list
+git workspace pull --dry-run
 git workspace rename holepunchto/brittle@jobs holepunchto/brittle@fixes
 git workspace remove holepunchto/brittle
 ```
 
-- `--help` (or `-h`) shows the available options.
+- `-h` shows the available options; `git workspace --help` opens the manual page.
 - `--version` prints the package version.
 
 You can also invoke the executable directly, for example `git-workspace list`. Use `git workspace -h` or `git-workspace --help` for CLI help; Git handles `git workspace --help` as a manual-page request.
@@ -43,35 +95,176 @@ git workspace init nicolasfont/workspace
 
 This tries to clone the repository over SSH into `~/workspace/nicolasfont/workspace`. If cloning fails and the destination is absent or empty, it initializes a local Git repository there and sets `origin` to the GitHub SSH URL. The clone failure is reported because a missing repository, authentication failure, and network failure can look similar. Existing nonempty destinations are never overwritten.
 
-Creating the repository on GitHub, committing, and pushing remain manual. Initialization saves `~/.config/git-workspace/config.json` with a `manifestRepository` field containing the absolute checkout path. The local repository uses `workspace.json` as the manifest, storing portable repository names rather than machine-specific absolute paths:
+Creating the repository on GitHub remains manual. Manifest commits are pushed automatically when the remote is available. Initialization saves `~/.config/git-workspace/config.json` with a `manifestRepository` field containing the absolute checkout path. The local repository uses `workspace.json` as the manifest, storing portable repository names rather than machine-specific absolute paths:
 
 ```json
-["holepunchto/brittle", "holepunchto/brittle@feature/jobs"]
+{
+  "version": 1,
+  "repositories": [
+    {
+      "id": "8257b322-695c-4c97-a816-c6c2c6198e40",
+      "name": "holepunchto/brittle",
+      "worktrees": [
+        {
+          "id": "37326a40-98e7-461b-9dd3-fc6a57f0b856",
+          "branch": "feature/jobs"
+        }
+      ]
+    }
+  ]
+}
+```
+
+On every machine, those names resolve under `~/workspace`. `list` still displays
+`owner/repo` and `owner/repo@branch`; IDs are stored in the manifest, not used in CLI arguments.
+
+Each repository and linked worktree gets a UUID when first registered. Renaming a repository
+(including changing its owner) preserves its ID and all its worktree IDs. Renaming a branch
+worktree preserves its ID. Removing an entry deletes it from the current manifest; reusing
+that name later creates a new ID. Old identities remain in Git history, so names are not
+reserved forever. Treat IDs as permanent identifiers when editing the manifest manually.
+
+IDs must be unique across the entire manifest, and repository names and worktree names must
+not be duplicated. Worktrees belong to their root repository. Invalid entries and unsupported
+manifest versions are rejected before changing checkouts. The manifest records desired state;
+reading it does not apply changes. A local applied-commit checkpoint records verified state;
+`git workspace pull` synchronizes the local layout, and `--dry-run` previews changes first.
+
+If the manifest repository has no `workspace.json`, initialization writes an empty version-1 manifest and commits it with the message `Initialize workspace manifest`. Only `workspace.json` is included; unrelated staged changes remain staged. Git identity, hooks, and signing settings apply as usual. The new manifest commit is then pushed. Old local registry files are not read or migrated.
+
+If the commit fails, `init` reports the Git error and leaves the new manifest on disk. Resolve the error, commit only `workspace.json` in the manifest repository, then rerun `init`.
+
+If a version-1 `workspace.json` already exists, it is validated and preserved without creating a commit, even if it has uncommitted edits. Initialization does not clone or remove the repositories listed in the manifest. Repeating `init` with the same manifest repository preserves local edits and does not pull. A different manifest origin is refused.
+
+Run `init` before using `add`, `remove`, `list`, `status`, or `pull`. All commands locate `workspace.json` through that config file; there is no legacy registry fallback or separate activation marker. `init` commits newly created manifests, and successful `add`, `remove`, and `rename` commands commit the current manifest and attempt to push it.
+
+Automatic pushes target the manifest branch's configured upstream, or the same branch name
+on `origin` when no upstream is configured. A successful push establishes tracking. Only
+that manifest branch is pushed, including its existing local commits; project branches and
+tags are not published. Pushes never force, fetch, or merge remote history.
+
+A push failure warns without undoing the checkout operation or local commit, changing the
+command's success status, or preventing local applied tracking and post hooks. This allows
+commands to work offline or before the manifest repository exists on GitHub. Once connected,
+repeat `add` for an already registered checkout to retry the push without another commit,
+or push from the manifest repository yourself (for a new upstream, `git push -u origin HEAD`).
+For a non-fast-forward rejection, resolve the divergent manifest history before retrying.
+
+Only the version-1 object format is supported. Old array manifests are rejected without being
+rewritten. Keep IDs when editing entries; replacing an ID means replacing that entry's identity.
+
+After successful `init`, `add`, `remove`, and `rename` commands, the CLI automatically
+verifies the committed manifest against this machine's checkouts and records the applied
+commit locally. This internal bookkeeping supports future synchronization; it does not
+create commits or push anything. Dirty files and local commits in your repositories are allowed.
+If verification finds a mismatch, the completed operation is preserved and a warning explains
+why local tracking could not advance. Tracking is checked again on the next successful command
+that initializes or changes the workspace. `list` and `status` do not change it.
+
+### Synchronize from the manifest
+
+```sh
+git workspace pull --dry-run
+git workspace pull
 ```
 
-On every machine, those names resolve under `~/workspace`.
+Fetches the manifest branch from its configured upstream. If the local branch has no upstream,
+it uses the same branch name on `origin`. The manifest repository must be on a branch with a
+clean working tree and index. Divergent histories are refused; local commits ahead of the
+remote are retained; pull itself does not push them.
 
-If the manifest repository has no `workspace.json`, initialization writes an empty array. Old local registry files are not read or migrated.
+The preview compares the latest manifest with this machine's last verified applied state.
+Matching IDs identify renames, even across owners. A root rename includes its worktrees;
+branch renames are listed separately only when the branch name changes. Removed children
+are listed before their parents, and parents are added before children. Reusing a name with
+a new ID means removing the old entry and adding the replacement.
 
-If `workspace.json` already exists, it is validated and preserved. Initialization does not clone or remove the repositories listed in the manifest. Repeating `init` with the same manifest repository preserves local edits and does not pull. A different manifest origin is refused.
+For example:
 
-Run `init` before using `add`, `remove`, `list`, or `status`. All commands locate `workspace.json` through that config file; there is no legacy registry fallback or separate activation marker. Updates remain uncommitted changes in the manifest checkout: automatic commits, pushes, and a `git workspace pull` command will come in later commits. For now, the manifest checkout can be committed and pushed with ordinary Git commands.
+```text
+Manifest: origin/main
+Would fast-forward the manifest
+rename owner/repo -> other/new
+rename other/new@jobs -> other/new@fixes
+add other/new@feature/new
+Dry run: no manifest checkout or workspace changes applied
+```
+
+The planner reports missing or mismatched checkouts, occupied destinations, existing branch
+targets, locked worktrees, and dirty checkouts that would be removed. Dirty work is allowed
+in retained or renamed checkouts. Blockers are printed with `blocked:` and exit status 1;
+the preview still shows the requested changes. These checks describe local conditions now;
+they cannot guarantee a future clone or filesystem operation will succeed.
+
+On a new machine without an applied baseline, the preview plans additions and reports
+matching existing checkouts as `adopt`. It does not infer old removals or renames from history
+before that machine's first verified baseline. Unexpected local layout changes after a
+baseline are reported for manual resolution.
+
+Without `--dry-run`, pull checks for blockers before fast-forwarding the manifest and
+applying the layout changes. It moves renamed checkouts, updates renamed roots' origin URLs,
+removes clean retired checkouts, and clones or creates additions. GitHub renames and transfers
+remain manual. Clean removals can delete local commits, just like `git workspace remove`;
+preview the plan before applying removals. Existing managed repositories are never fetched
+or pulled. Pull creates no manifest commits and pushes nothing. Unlike a direct `add`, pull
+requires new repositories to clone successfully; it never substitutes an empty local repository
+for an unavailable remote.
+
+If an operation fails, completed changes remain in place. Resolve the reported error and
+rerun `git workspace pull` to resume the saved target. The next pull fetches any newer remote
+changes. Progress is stored locally in `.git/workspace-pull.json`, with the target commit
+pinned at `refs/git-workspace/pull-target`. Other commands that modify the manifest are
+blocked while a pull is pending. Local applied tracking advances only after the complete
+layout has been verified; progress is then cleared. Do not edit or delete the progress file
+to retry. A dry run during recovery checks the remaining changes without applying them;
+a partially moved rename may need a real pull to repair its Git links before those checks
+can finish.
+
+A dry run fetches objects and updates Git's fetch metadata and remote-tracking refs in the
+manifest repository. It never checks out the fetched manifest, applies layout changes,
+advances local applied tracking, creates commits, or pushes.
 
 ### Add a repository
 
-With Git on your `PATH` and SSH access to GitHub configured:
+With Git on your `PATH`:
 
 ```sh
 git workspace add holepunchto/brittle
 ```
 
-The required `owner/repo` identifies a GitHub repository. If `~/workspace/holepunchto/brittle` does not exist, the command clones `git@github.com:holepunchto/brittle.git` there, then registers the checkout. The default workspace directory is `~/workspace`, regardless of your current directory.
+The required `owner/repo` identifies a GitHub repository, including one you have not created
+on GitHub yet. If `~/workspace/holepunchto/brittle` is absent or an empty directory, the command
+tries to clone `git@github.com:holepunchto/brittle.git` there. The default workspace directory
+is `~/workspace`, regardless of your current directory.
+
+If cloning fails and the destination is still absent or empty, `add` initializes an empty local
+Git repository and configures that URL as `origin`. This works offline and when the remote
+does not exist or is inaccessible, with no flag or confirmation required. The clone diagnostic
+is preserved, followed by a notice explaining that a local repository was initialized. The
+checkout is registered and committed to the manifest normally, and add hooks run normally.
+No GitHub repository is created and no project commits are pushed. The workspace manifest commit is pushed separately.
+
+The local repository follows Git's `init.defaultBranch` setting and has no initial commit.
+Create your first commit when ready. Later remote synchronization is explicit: repeating `add`
+reuses the local checkout, even once you are online. If the remote already has history, reconcile
+that history with any commits you made locally before pushing.
 
-If the destination already exists, it must be a Git worktree root whose `origin` points to the requested GitHub repository. SSH and HTTPS origins are accepted. Repeating the command does not pull, switch branches, or add duplicate entries. Existing repositories elsewhere are not moved.
+Default SSH clone attempts use a five-second connection timeout, one connection attempt, and
+noninteractive authentication, using keys already available to SSH. The timeout covers the
+[SSH connection and initial handshake](https://man.openbsd.org/ssh_config#ConnectTimeout),
+not the entire clone or system DNS resolution. Custom `GIT_SSH`, `GIT_SSH_COMMAND`,
+`core.sshCommand`, and non-OpenSSH variants keep their own transport settings; URL rewrites
+to other transports also retain their own connection behavior.
 
-Registered names are stored in the initialized manifest. Cloning shows Git's progress; registering an existing checkout is silent. A failed clone or destination validation leaves the registry unchanged. If registration fails after cloning, the checkout remains on disk; fix the registry issue and rerun the same command.
+A failed clone that leaves files behind is preserved and reported as an error. Initialization
+never overwrites a nonempty destination or follows a destination symlink. Git invocation,
+interruption, and local filesystem failures remain errors.
 
-Path-based `add` is no longer supported. No sessions are started.
+If the destination already contains files, it must be a Git worktree root whose `origin` points to the requested GitHub repository. SSH and HTTPS origins are accepted. Repeating the command does not pull, switch branches, or add duplicate entries. Existing repositories elsewhere are not moved.
+
+Registered names are stored in the initialized manifest. A successful `add` commits the current `workspace.json` with the message `Add owner/repo` or `Add owner/repo@branch`. Adding a branch and its root together makes one commit. If the manifest matches the last commit, no commit is created. The commit includes any pending edits to `workspace.json`, including manual edits; unrelated staged files remain staged. The manifest branch is then pushed; repeating add retries the push even if no new commit is needed. Cloning shows Git's progress; registering an existing checkout is silent. A destination validation failure leaves the registry unchanged. If registration fails after cloning or local initialization, the checkout remains on disk; fix the registry issue and rerun the same command. If committing fails, the checkouts and manifest are retained; resolve the reported Git error and rerun the same `add` command to retry the commit.
+
+Path-based `add` is no longer supported. Session management can be provided by a command hook.
 
 ### Add a branch worktree
 
@@ -79,17 +272,39 @@ Path-based `add` is no longer supported. No sessions are started.
 git workspace add holepunchto/brittle@jobs
 ```
 
-First ensures `~/workspace/holepunchto/brittle` exists and is registered, cloning it if necessary. Then creates and registers `~/workspace/holepunchto/brittle@jobs`:
+First ensures `~/workspace/holepunchto/brittle` exists and is registered, cloning it or initializing
+it locally if necessary. Then creates and registers `~/workspace/holepunchto/brittle@jobs`:
 
 - Uses the local `jobs` branch if it exists.
 - Otherwise creates `jobs` tracking `origin/jobs`, if that remote-tracking branch exists locally.
 - Otherwise creates `jobs` from the root checkout's current `HEAD`, without an upstream.
 
+An empty root needs its first commit before a branch worktree can be created. If the root was
+just initialized locally, it stays registered and the command explains how to make the first
+commit and retry. It does not fabricate a commit to create the worktree.
+
 Existing repositories are not fetched automatically. The root checkout's branch and local edits remain unchanged. If the destination already exists, it must belong to the same Git repository and be on the requested branch; it is reused without switching branches. Git refuses creation when the branch is checked out elsewhere.
 
 Branch names containing `/` use nested directories. For example, `git workspace add holepunchto/brittle@feature/jobs` creates branch `feature/jobs` at `~/workspace/holepunchto/brittle@feature/jobs`. Use the same name for `remove`; `list` preserves the slashes. Invalid branch names are rejected before cloning or registration.
 
-If worktree creation fails, the root repository remains registered. If registration fails after creation, the worktree remains on disk; fix the registry issue and retry the same command.
+If worktree creation fails, the root repository remains registered and its manifest change remains uncommitted. If registration fails after creation, the worktree remains on disk; fix the registry issue and retry the same command.
+
+### Rename commits
+
+After a successful root or branch rename, the current `workspace.json` is committed with the
+message `Rename <from> to <to>`. A root rename and all its linked worktree entries are included
+in one commit. Pending manifest edits are included; unrelated staged files remain staged.
+No commit is created if the manifest matches the last commit. The manifest branch is then pushed.
+
+If committing fails, the renamed checkouts, origin configuration, and updated manifest are
+retained. Resolve the Git error and commit only `workspace.json` in the manifest repository,
+for example:
+
+```sh
+git commit --only -m "Rename holepunchto/brittle@jobs to holepunchto/brittle@fixes" -- workspace.json
+```
+
+The rename is already complete, so do not rerun it using the old name to retry the commit.
 
 ### Rename a root repository
 
@@ -106,7 +321,7 @@ The local `origin` URL is updated to the new name, preserving SSH or HTTPS forma
 origin push URLs pointing to the old repository are updated too; URLs pointing elsewhere and
 other remotes are left alone. An origin already pointing to the new name is also accepted.
 
-This is entirely local: it does not rename anything on GitHub, fetch, commit, or push. Rename
+The checkout rename does not rename anything on GitHub, fetch, or push project commits. Its workspace manifest commit is pushed. Rename
 the repository separately in GitHub **Settings → General → Repository name**, or run:
 
 ```sh
@@ -207,10 +422,57 @@ After successful worktree and branch removal, empty branch-parent directories ar
 
 If branch deletion fails after the directory is removed, the branch and existing registry entry remain. Resolve the branch issue and retry the same command to finish removal.
 
-Supply the same `owner/repo` or `owner/repo@branch` used by `add`. Paths resolve under `~/workspace`, regardless of the current directory. If a registered directory is already missing, branch deletion is still attempted; an already missing branch is accepted. No GitHub connection is needed, and sessions are not managed.
+Supply the same `owner/repo` or `owner/repo@branch` used by `add`. Paths resolve under `~/workspace`, regardless of the current directory. If a registered directory is already missing, branch deletion is still attempted; an already missing branch is accepted. No GitHub connection is needed. Session cleanup can be provided by a command hook.
+
+A successful `remove` commits the current `workspace.json` with the message `Remove owner/repo` or `Remove owner/repo@branch`. Like `add`, it includes pending manifest edits, preserves unrelated staged files, skips commits when the manifest matches the last commit, and pushes the manifest branch.
+
+If committing fails, the checkout and registration are already removed. Resolve the reported Git error and commit only `workspace.json` in the manifest repository, for example:
+
+```sh
+git commit --only -m "Remove holepunchto/brittle" -- workspace.json
+```
+
+Rerunning `remove` is not the commit recovery step: a missing, unregistered checkout still reports an error.
 
 Successful removal is silent. Existing checkouts can also be removed if previously unregistered. A missing, unregistered repository reports an error. Path-based `remove` is not supported.
 
+### Command hooks
+
+Executables on `PATH` named `git-workspace-hook-<command>-post-<name>` run after
+`add`, `remove`, and `rename`, including those operations performed by `pull`.
+Installing the executables on `PATH` enables them;
+there is no hook directory, registration command, or hook configuration in the manifest.
+
+```sh
+git workspace hook list
+git workspace add owner/repo --no-hooks
+git workspace pull --no-hooks
+```
+
+`hook list` shows available hooks and their resolved paths, even before workspace initialization.
+Hooks receive the command and `post` as arguments and versioned JSON on stdin, including
+stable IDs, checkout paths before and after the operation, and its outcome. Hooks run in order
+and are awaited. Failures warn without rolling back the command or changing its exit status.
+Dry runs, help, and completion never execute hooks.
+
+See [Writing command hooks](docs/hooks.md) for the full protocol, npm packaging example,
+partial failures, and pull recovery semantics. Hooks must tolerate repeated delivery after
+an interrupted pull. There are no pre hooks, fetch hooks, or prune hooks in this version.
+
+#### Available hooks
+
+[git-workspace-hook-tmux](https://github.com/nicolasfont/git-workspace-hook-tmux) creates
+detached tmux sessions when checkouts are added, preserves running panes across renames,
+and closes managed sessions when checkouts are removed. Requires tmux on `PATH`.
+
+```sh
+npm install -g git-workspace-hook-tmux
+```
+
+Installation enables its add, remove, and rename hooks automatically. Sessions are never
+attached or switched automatically. Removing a checkout terminates its managed session
+and all programs running in its panes.
+
 ### Errors
 
 Failures print an `error:` message to stderr and exit with status 1. The label is red when stderr is a terminal; redirected output stays plain. When available, a separate `hint:` explains the next step:

package/bin/git-workspace.js

@@ -1,13 +1,17 @@
 #!/usr/bin/env bare
 
 import { arg, command, flag, summary } from 'paparam'
+import fs from 'bare-fs'
 import add from '../lib/add.js'
 import init from '../lib/init.js'
 import remove from '../lib/remove.js'
 import rename from '../lib/rename.js'
 import list from '../lib/list.js'
 import status from '../lib/status.js'
+import pull, { formatPlan } from '../lib/pull.js'
+import completion from '../lib/completion.js'
 import reportError from '../lib/report-error.js'
+import { discoverHooks } from '../lib/hooks.js'
 import pkg from '../package.json' with { type: 'json' }
 
 const cmd = command(
@@ -28,11 +32,12 @@ const cmd = command(
   ),
   command(
     'add',
-    summary('Clone a repository or create a branch worktree'),
+    summary('Clone or initialize a repository, or create a branch worktree'),
     arg('<repository>', 'owner/repo or owner/repo@branch'),
-    ({ args }) => {
+    flag('--no-hooks', 'Skip command hooks'),
+    ({ args, flags }) => {
       try {
-        add(args.repository)
+        add(args.repository, { noHooks: flags.hooks === false })
       } catch (err) {
         reportError(err)
       }
@@ -42,9 +47,10 @@ const cmd = command(
     'remove',
     summary('Remove a repository or linked worktree'),
     arg('<repository>', 'owner/repo or owner/repo@branch'),
-    ({ args }) => {
+    flag('--no-hooks', 'Skip command hooks'),
+    ({ args, flags }) => {
       try {
-        remove(args.repository)
+        remove(args.repository, { noHooks: flags.hooks === false })
       } catch (err) {
         reportError(err)
       }
@@ -55,9 +61,10 @@ const cmd = command(
     summary('Rename a root repository or a branch worktree'),
     arg('<from>', 'owner/repo or owner/repo@branch to rename'),
     arg('<to>', 'New owner/repo or owner/repo@branch'),
-    ({ args }) => {
+    flag('--no-hooks', 'Skip command hooks'),
+    ({ args, flags }) => {
       try {
-        rename(args.from, args.to)
+        rename(args.from, args.to, { noHooks: flags.hooks === false })
       } catch (err) {
         reportError(err)
       }
@@ -70,6 +77,30 @@ const cmd = command(
       reportError(err)
     }
   }),
+  command(
+    'pull',
+    summary('Apply changes from the latest workspace manifest'),
+    flag('--dry-run', 'Fetch the manifest and preview changes without applying them'),
+    flag('--no-hooks', 'Skip command hooks, including pending hooks from an interrupted pull'),
+    ({ flags }) => {
+      try {
+        const plan = pull({ dryRun: flags.dryRun, noHooks: flags.hooks === false })
+        console.log(formatPlan(plan))
+        if (plan.blockers.length) Bare.exitCode = 1
+      } catch (err) {
+        reportError(err)
+      }
+    }
+  ),
+  command(
+    'hook',
+    summary('Inspect command hooks discovered on PATH'),
+    command('list', summary('List available post hooks and their executable paths'), () => {
+      for (const hook of discoverHooks()) {
+        console.log(`${hook.command}/post\t${hook.name}\t${hook.path}`)
+      }
+    })
+  ),
   command('status', summary('Show clean, modified, or missing checkouts'), async () => {
     try {
       const entries = await status()
@@ -81,6 +112,23 @@ const cmd = command(
       reportError(err)
     }
   }),
+  command(
+    'completion',
+    summary('Print a shell completion script'),
+    arg('<shell>', 'Shell to generate completion for (bash)'),
+    ({ args }) => {
+      try {
+        if (args.shell !== 'bash') throw new Error('Supported completion shell: bash')
+        console.log(
+          fs
+            .readFileSync(new URL('../completions/git-workspace.bash', import.meta.url), 'utf8')
+            .trimEnd()
+        )
+      } catch (err) {
+        reportError(err)
+      }
+    }
+  ),
   ({ flags }) => {
     if (flags.version) {
       console.log(pkg.version)
@@ -89,8 +137,14 @@ const cmd = command(
 )
 
 try {
-  const parsed = cmd.parse()
-  if (parsed) await parsed.running
+  if (Bare.argv[2] === '--complete') {
+    // Internal completion protocol; flags in these words are input, never actions.
+    const candidates = completion(Bare.argv.slice(3), cmd.helpJSON())
+    if (candidates.length) console.log(candidates.join('\n'))
+  } else {
+    const parsed = cmd.parse()
+    if (parsed) await parsed.running
+  }
 } catch (err) {
   reportError(err)
 }

package/completions/git-workspace.bash

@@ -0,0 +1,26 @@
+# For `git workspace`, load Git's Bash completion as well as this script.
+# The direct `git-workspace` form also works without Git's completion script.
+
+_git_workspace ()
+{
+    local first=$(( ${__git_cmd_idx:-0} + 1 )) candidate
+    COMPREPLY=()
+    while IFS= read -r candidate; do
+        case "$candidate" in
+            *@) ;;
+            *@*) candidate="$candidate " ;;
+            */*) ;; # Keep repository names open for an @branch suffix.
+            *) candidate="$candidate " ;;
+        esac
+        COMPREPLY[${#COMPREPLY[@]}]="$candidate"
+    done < <(command git-workspace --complete "${words[@]:first:cword-first}" "$cur" 2>/dev/null)
+}
+
+_git_workspace_direct ()
+{
+    local words=("${COMP_WORDS[@]}") cword=$COMP_CWORD
+    local cur="${COMP_WORDS[COMP_CWORD]}" __git_cmd_idx=0
+    _git_workspace
+}
+
+complete -o nospace -F _git_workspace_direct git-workspace