git-workspace-bare 0.1.0

package/.lunterc.json

@@ -0,0 +1,5 @@
+{
+  "rules": {
+    "require-await": "off"
+  }
+}

package/.prettierrc

@@ -0,0 +1 @@
+prettier-config-holepunch

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,252 @@
+# git-workspace-bare
+
+Manage Git worktrees as development workspaces.
+
+The CLI can clone GitHub repositories, create branch worktrees, list registered checkouts, and unregister them.
+
+## Local setup
+
+The CLI runs on [Bare](https://github.com/holepunchto/bare). Install Bare using npm:
+
+```sh
+npm install -g bare
+```
+
+Then run from the repository directory:
+
+```sh
+npm install
+npm link
+```
+
+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.
+
+## Usage
+
+```sh
+git workspace -h
+git workspace --version
+git workspace init nicolasfont/workspace
+git workspace add holepunchto/brittle
+git workspace list
+git workspace rename holepunchto/brittle@jobs holepunchto/brittle@fixes
+git workspace remove holepunchto/brittle
+```
+
+- `--help` (or `-h`) shows the available options.
+- `--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.
+
+Running `git workspace` without arguments exits successfully without printing anything.
+
+### Initialize a manifest repository
+
+Initialize your manifest repository:
+
+```sh
+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:
+
+```json
+["holepunchto/brittle", "holepunchto/brittle@feature/jobs"]
+```
+
+On every machine, those names resolve under `~/workspace`.
+
+If the manifest repository has no `workspace.json`, initialization writes an empty array. Old local registry files are not read or migrated.
+
+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.
+
+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.
+
+### Add a repository
+
+With Git on your `PATH` and SSH access to GitHub configured:
+
+```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.
+
+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.
+
+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.
+
+Path-based `add` is no longer supported. No sessions are started.
+
+### Add a branch worktree
+
+```sh
+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`:
+
+- 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.
+
+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.
+
+### Rename a root repository
+
+```sh
+git workspace rename holepunchto/git-workspace holepunchto/git-workspace-bare
+```
+
+Moves the root checkout and its linked `owner/repo@branch` directories to the new repository
+name, repairs Git's worktree links, and updates their manifest entries. Branch names, commits,
+and uncommitted files are preserved. Linked worktrees outside this naming layout stay in place
+and their Git links are repaired too.
+
+The local `origin` URL is updated to the new name, preserving SSH or HTTPS format. Explicit
+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 repository separately in GitHub **Settings → General → Repository name**, or run:
+
+```sh
+gh repo rename git-workspace-bare --repo github.com/holepunchto/git-workspace
+```
+
+That separate command changes the GitHub repository's name without pushing commits. It requires
+an authenticated [GitHub CLI](https://cli.github.com/manual/gh_repo_rename) and repository admin
+permissions. You can do the GitHub rename before or after the local rename; the new origin URL
+will only work once the GitHub repository has the new name.
+
+Both arguments must use `owner/repo`. The owner can change too: the root and linked worktrees
+move under the new owner's workspace directory, and origin URLs follow the new `owner/repo`.
+Transfer ownership on GitHub separately; the local command does not perform that transfer.
+The source must be a registered standalone root checkout with the expected GitHub origin.
+Existing destination paths or manifest entries, missing or invalid linked worktrees, linked
+worktrees containing submodules, locked
+worktrees that would move, and symbolic-link checkouts are refused. The active manifest
+repository itself cannot be renamed. If a local move, Git repair, or manifest write fails, the
+command attempts to restore the original paths and origin configuration and reports any
+failure to restore them.
+
+### Rename a branch worktree
+
+```sh
+git workspace rename holepunchto/brittle@jobs holepunchto/brittle@fixes
+```
+
+Renames a branch worktree and the branch it holds together, so the directory name and the
+checked-out branch stay in sync. It moves `~/workspace/holepunchto/brittle@jobs` to
+`~/workspace/holepunchto/brittle@fixes`, renames the local branch with `git branch -m`, and
+updates the manifest entry. Uncommitted work moves with the directory; the worktree does not
+need to be clean.
+
+Both arguments are full `owner/repo@branch` names, and the `owner/repo` part must match: a
+worktree cannot be renamed into a different repository.
+
+The branch actually checked out does not have to match the `@branch` in the source name. If you
+switched branches inside a worktree with ordinary Git, rename it to the branch it now holds to
+line the directory back up:
+
+```sh
+git workspace rename holepunchto/brittle@jobs holepunchto/brittle@wandered
+```
+
+That moves the directory only. Renaming never touches a branch other than the one the worktree
+has checked out, so a branch left behind by `git switch -c` survives.
+
+If the branch has an upstream, it is retargeted to the matching branch on the same remote, so
+renaming `jobs` to `fixes` leaves it tracking `origin/fixes` rather than `origin/jobs`. That
+remote branch may not exist yet; push it before pulling. Branches without an upstream stay
+without one, and remote branches are never renamed or deleted.
+
+Renaming is refused if the destination directory exists, if the new branch name is already taken
+by another branch, if the source is not registered or not checked out, or if the worktree is on a
+detached HEAD. Nested branch names use nested directories, as with `add`, and empty parent
+directories left behind are removed.
+
+### List repositories
+
+```sh
+git workspace list
+```
+
+Prints registered repositories as `owner/repo` and linked worktrees as `owner/repo@branch`, one per line sorted alphabetically, regardless of the current directory:
+
+```text
+holepunchto/brittle
+holepunchto/brittle@jobs
+```
+
+An empty manifest produces no output. Missing or invalid manifest data reports an error.
+
+Repositories remain listed even if their directories no longer exist. Listing does not modify the registry.
+
+### Check workspace status
+
+```sh
+git workspace status
+```
+
+Checks up to four checkouts concurrently and shows results in alphabetical order, followed by `clean`, `modified`, or `missing`. Modified includes staged changes, unstaged changes, and untracked files; ignored files do not count. Missing means the checkout path no longer exists.
+
+An empty registry produces no output. Existing paths that are not valid Git worktree roots report an error. Status does not fetch, modify the registry, or refresh Git's index on disk. It does not report whether branches are ahead of or behind their remotes.
+
+### Remove a repository or worktree
+
+```sh
+git workspace remove holepunchto/brittle
+git workspace remove holepunchto/brittle@jobs
+```
+
+Without `@branch`, deletes the root checkout, including its local Git history and branches, and removes its registry entry. The destination must be a standalone root repository with the expected GitHub origin. The active manifest repository cannot be removed. Removal refuses local changes, untracked files, symbolic-link destinations, or any linked worktrees (including stale worktree records). Remove linked worktrees first. Ignored files are deleted with the checkout, and remote repositories are untouched. Local commits are not checked for whether they have been pushed.
+
+With `@branch`, verifies the linked worktree belongs to the root repository, removes the worktree directory, deletes the branch it actually had checked out with `git branch -D`, and unregisters it. The checked-out branch does not have to match the `@branch` in the name: a worktree you switched to another branch is still removed, and that branch is the one deleted. A worktree left on a detached HEAD is removed without deleting any branch. Branch deletion skips Git's merged-status check, including for squash-merged PRs or unmerged local commits. Worktree removal still refuses dirty or locked worktrees, and remote branches are untouched. A worktree previously unregistered by an older version can also be removed this way.
+
+After successful worktree and branch removal, empty branch-parent directories are removed up to, but not including, the owner directory. Parents containing sibling worktrees or other files remain.
+
+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.
+
+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.
+
+### 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:
+
+```text
+error: cannot remove holepunchto/brittle: linked worktrees exist
+hint: remove the linked worktrees first
+```
+
+## Development
+
+Run the Brittle integration tests on Bare (Git must be installed):
+
+```sh
+npm test
+```
+
+Tests use isolated temporary workspaces and local Git repositories, disable network protocols, and clean up afterward. They do not access your real workspace or Git configuration.
+
+Format files with Prettier and the Holepunch config:
+
+```sh
+npm run format
+```
+
+Lint files with Lunte:
+
+```sh
+npm run lint
+```
+
+The `require-await` rule is disabled, so async functions may omit `await`.

package/bin/git-workspace.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env bare
+
+import { arg, command, flag, summary } from 'paparam'
+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 reportError from '../lib/report-error.js'
+import pkg from '../package.json' with { type: 'json' }
+
+const cmd = command(
+  'git-workspace',
+  summary('Manage Git worktrees as development workspaces.'),
+  flag('--version', 'Show the version'),
+  command(
+    'init',
+    summary('Initialize a GitHub repository for the workspace manifest'),
+    arg('<repository>', 'Manifest repository in owner/repo form'),
+    ({ args }) => {
+      try {
+        init(args.repository)
+      } catch (err) {
+        reportError(err)
+      }
+    }
+  ),
+  command(
+    'add',
+    summary('Clone a repository or create a branch worktree'),
+    arg('<repository>', 'owner/repo or owner/repo@branch'),
+    ({ args }) => {
+      try {
+        add(args.repository)
+      } catch (err) {
+        reportError(err)
+      }
+    }
+  ),
+  command(
+    'remove',
+    summary('Remove a repository or linked worktree'),
+    arg('<repository>', 'owner/repo or owner/repo@branch'),
+    ({ args }) => {
+      try {
+        remove(args.repository)
+      } catch (err) {
+        reportError(err)
+      }
+    }
+  ),
+  command(
+    'rename',
+    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 }) => {
+      try {
+        rename(args.from, args.to)
+      } catch (err) {
+        reportError(err)
+      }
+    }
+  ),
+  command('list', summary('List registered repositories and worktrees'), () => {
+    try {
+      for (const repository of list()) console.log(repository)
+    } catch (err) {
+      reportError(err)
+    }
+  }),
+  command('status', summary('Show clean, modified, or missing checkouts'), async () => {
+    try {
+      const entries = await status()
+      const width = entries.reduce((max, entry) => Math.max(max, entry.repository.length), 0)
+      for (const { repository, state } of entries) {
+        console.log(`${repository.padEnd(width)}  ${state}`)
+      }
+    } catch (err) {
+      reportError(err)
+    }
+  }),
+  ({ flags }) => {
+    if (flags.version) {
+      console.log(pkg.version)
+    }
+  }
+)
+
+try {
+  const parsed = cmd.parse()
+  if (parsed) await parsed.running
+} catch (err) {
+  reportError(err)
+}

package/lib/add.js

@@ -0,0 +1,105 @@
+import fs from 'bare-fs'
+import path from 'bare-path'
+import { spawnSync } from 'bare-subprocess'
+import { readRegistry, updateRegistry } from './registry.js'
+import repositoryPath from './repository-path.js'
+
+export default function add(repository) {
+  const directory = repositoryPath(repository)
+  readRegistry()
+  const [base, branch] = repository.split('@')
+  if (branch) {
+    git(['check-ref-format', '--branch', branch])
+    add(base)
+    const root = repositoryPath(base)
+    if (!exists(directory)) {
+      const args = ['-C', root, 'worktree', 'add']
+      if (hasRef(root, `refs/heads/${branch}`)) {
+        git([...args, directory, branch], { stdio: 'inherit' })
+      } else if (hasRef(root, `refs/remotes/origin/${branch}`)) {
+        git([...args, '--track', '-b', branch, directory, `refs/remotes/origin/${branch}`], {
+          stdio: 'inherit'
+        })
+      } else {
+        git([...args, '--no-track', '-b', branch, directory, 'HEAD'], { stdio: 'inherit' })
+      }
+    }
+
+    const worktree = fs.realpathSync(directory)
+    if (fs.realpathSync(git(['-C', directory, 'rev-parse', '--show-toplevel'])) !== worktree) {
+      throw new Error('Destination is not a Git worktree root')
+    }
+    const common = (cwd) =>
+      fs.realpathSync(git(['-C', cwd, 'rev-parse', '--path-format=absolute', '--git-common-dir']))
+    if (
+      common(directory) !== common(root) ||
+      git(['-C', directory, 'symbolic-ref', 'HEAD']) !== `refs/heads/${branch}`
+    ) {
+      throw new Error('Destination is not a worktree of the requested repository and branch')
+    }
+    register(repository, directory, worktree)
+    return
+  }
+
+  if (!exists(directory)) {
+    fs.mkdirSync(path.dirname(directory), { recursive: true })
+    git(['clone', `git@github.com:${repository}.git`, directory], { stdio: 'inherit' })
+  }
+
+  const worktree = fs.realpathSync(directory)
+  const root = git(['-C', directory, 'rev-parse', '--show-toplevel'])
+  if (fs.realpathSync(root) !== worktree) throw new Error('Destination is not a Git worktree root')
+
+  const origin = git(['-C', directory, 'config', '--get', 'remote.origin.url'])
+  const match =
+    /^(?:git@github\.com:|ssh:\/\/git@github\.com\/|https:\/\/github\.com\/)([^/]+\/[^/]+?)\/?$/i.exec(
+      origin
+    )
+  if (!match || match[1].replace(/\.git$/i, '').toLowerCase() !== repository.toLowerCase()) {
+    throw new Error(`Destination origin does not match ${repository}`)
+  }
+
+  register(repository, directory, worktree)
+}
+
+function exists(directory) {
+  try {
+    fs.lstatSync(directory)
+    return true
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+    return false
+  }
+}
+
+function hasRef(directory, ref) {
+  const result = spawnSync('git', ['-C', directory, 'show-ref', '--verify', '--quiet', ref])
+  if (result.error) throw result.error
+  if (result.status === 1) return false
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.toString().trim() || 'Could not inspect Git ref')
+  }
+  return true
+}
+
+function register(repository, directory, worktree) {
+  try {
+    updateRegistry((worktrees) => {
+      if (!worktrees.includes(worktree)) worktrees.push(worktree)
+      return worktrees
+    })
+  } catch (err) {
+    throw new Error(
+      `Could not register ${directory}: ${err.message}. Retry git workspace add ${repository} after fixing the registry.`
+    )
+  }
+}
+
+function git(args, options) {
+  const result = spawnSync('git', args, options)
+  if (result.error) throw result.error
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.toString().trim() || 'Git command failed')
+  }
+  return result.stdout?.toString().replace(/\r?\n$/, '')
+}

package/lib/checked-out-branch.js

@@ -0,0 +1,12 @@
+import { spawnSync } from 'bare-subprocess'
+
+export default function checkedOutBranch(directory) {
+  const result = spawnSync('git', ['-C', directory, 'symbolic-ref', '--quiet', 'HEAD'])
+  if (result.error) throw result.error
+  if (result.status === 1) return null
+  if (result.status !== 0) {
+    throw new Error(result.stderr?.toString().trim() || 'Could not inspect Git HEAD')
+  }
+  const ref = result.stdout?.toString().replace(/\r?\n$/, '')
+  return ref?.startsWith('refs/heads/') ? ref.slice('refs/heads/'.length) : null
+}