git-workspace-bare 0.1.1 → 0.3.1

package/lib/rename-root.js

@@ -5,7 +5,7 @@ import { manifestDirectory, updateRegistry } from './registry.js'
 import repositoryPath from './repository-path.js'
 import removeEmptyParents from './remove-empty-parents.js'
 
-export default function renameRoot(from, to) {
+export default function renameRoot(from, to, { update = updateRegistry } = {}) {
   const source = repositoryPath(from)
   const destination = repositoryPath(to)
   if (from === to) throw new Error(`${to} is already the registered name`)
@@ -13,101 +13,100 @@ export default function renameRoot(from, to) {
   const moved = []
   let originalConfig
   try {
-    updateRegistry((worktrees) => {
-      if (!worktrees.includes(source)) throw new Error(`${from} is not registered`)
-      if (!exists(source)) throw new Error(`${from} is not checked out`)
-      const canonical = fs.realpathSync(source)
-      if (canonical === fs.realpathSync(manifestDirectory())) {
-        throw new Error('Cannot rename the active manifest repository')
-      }
-      const gitDirectory = path.join(canonical, '.git')
-      if (
-        fs.lstatSync(source).isSymbolicLink() ||
-        !fs.lstatSync(gitDirectory).isDirectory() ||
-        fs.realpathSync(git(source, 'rev-parse', '--show-toplevel')) !== canonical ||
-        fs.realpathSync(git(source, 'rev-parse', '--path-format=absolute', '--git-common-dir')) !==
-          gitDirectory
-      ) {
-        throw new Error('Source is not a standalone root repository')
-      }
-
-      const urls = configValues(source, 'remote.origin.url')
-      if (urls.length !== 1 || !matches(urls[0], from, to)) {
-        throw new Error(`Source origin does not match ${from} or ${to}`)
-      }
-      const pushurls = configValues(source, 'remote.origin.pushurl')
-      const entries = git(source, 'worktree', 'list', '--porcelain', '-z')
-        .split('\0\0')
-        .filter(Boolean)
-        .map((entry) => entry.split('\0'))
-      const moves = [[source, destination]]
-      for (const entry of entries.slice(1)) {
-        const directory = entry[0].slice('worktree '.length)
-        if (!exists(directory)) {
-          throw new Error(`Missing linked worktree: ${directory}; repair or prune it first`)
+    update(
+      (worktrees) => {
+        if (!worktrees.includes(source)) throw new Error(`${from} is not registered`)
+        if (!exists(source)) throw new Error(`${from} is not checked out`)
+        const canonical = fs.realpathSync(source)
+        if (canonical === fs.realpathSync(manifestDirectory())) {
+          throw new Error('Cannot rename the active manifest repository')
         }
+        const gitDirectory = path.join(canonical, '.git')
         if (
-          fs.realpathSync(git(directory, 'rev-parse', '--show-toplevel')) !==
-            fs.realpathSync(directory) ||
+          fs.lstatSync(source).isSymbolicLink() ||
+          !fs.lstatSync(gitDirectory).isDirectory() ||
+          fs.realpathSync(git(source, 'rev-parse', '--show-toplevel')) !== canonical ||
           fs.realpathSync(
-            git(directory, 'rev-parse', '--path-format=absolute', '--git-common-dir')
+            git(source, 'rev-parse', '--path-format=absolute', '--git-common-dir')
           ) !== gitDirectory
         ) {
-          throw new Error(`Linked worktree needs repair: ${directory}`)
+          throw new Error('Source is not a standalone root repository')
         }
-        // Worktree repair does not repair the separate Git links inside submodules.
-        if (
-          git(directory, 'ls-files', '--stage', '-z')
-            .split('\0')
-            .some((entry) => entry.startsWith('160000 '))
-        ) {
-          throw new Error(`Linked worktree contains submodules: ${directory}`)
-        }
-        if (!directory.startsWith(source + '@')) continue
-        if (entry.some((field) => field === 'locked' || field.startsWith('locked '))) {
-          throw new Error(`Linked worktree is locked: ${directory}`)
+
+        const urls = configValues(source, 'remote.origin.url')
+        if (urls.length !== 1 || !matches(urls[0], from, to)) {
+          throw new Error(`Source origin does not match ${from} or ${to}`)
         }
-        if (fs.lstatSync(directory).isSymbolicLink()) {
-          throw new Error(`Linked worktree is a symbolic link: ${directory}`)
+        const pushurls = configValues(source, 'remote.origin.pushurl')
+        const entries = git(source, 'worktree', 'list', '--porcelain', '-z')
+          .split('\0\0')
+          .filter(Boolean)
+          .map((entry) => entry.split('\0'))
+        const moves = [[source, destination]]
+        for (const entry of entries.slice(1)) {
+          const directory = entry[0].slice('worktree '.length)
+          if (!exists(directory)) {
+            throw new Error(`Missing linked worktree: ${directory}; repair or prune it first`)
+          }
+          if (
+            fs.realpathSync(git(directory, 'rev-parse', '--show-toplevel')) !==
+              fs.realpathSync(directory) ||
+            fs.realpathSync(
+              git(directory, 'rev-parse', '--path-format=absolute', '--git-common-dir')
+            ) !== gitDirectory
+          ) {
+            throw new Error(`Linked worktree needs repair: ${directory}`)
+          }
+          // Worktree repair does not repair the separate Git links inside submodules.
+          if (
+            git(directory, 'ls-files', '--stage', '-z')
+              .split('\0')
+              .some((entry) => entry.startsWith('160000 '))
+          ) {
+            throw new Error(`Linked worktree contains submodules: ${directory}`)
+          }
+          if (!directory.startsWith(source + '@')) continue
+          if (entry.some((field) => field === 'locked' || field.startsWith('locked '))) {
+            throw new Error(`Linked worktree is locked: ${directory}`)
+          }
+          if (fs.lstatSync(directory).isSymbolicLink()) {
+            throw new Error(`Linked worktree is a symbolic link: ${directory}`)
+          }
+          moves.push([directory, destination + directory.slice(source.length)])
         }
-        moves.push([directory, destination + directory.slice(source.length)])
-      }
-      const mapping = new Map(moves)
-      for (const directory of worktrees) {
-        if (directory.startsWith(source + '@') && !mapping.has(directory)) {
-          throw new Error(
-            `Registered worktree is missing or does not belong to ${from}: ${directory}`
-          )
+        const mapping = new Map(moves)
+        for (const directory of worktrees) {
+          if (directory.startsWith(source + '@') && !mapping.has(directory)) {
+            throw new Error(
+              `Registered worktree is missing or does not belong to ${from}: ${directory}`
+            )
+          }
+          if (directory === destination || directory.startsWith(destination + '@')) {
+            throw new Error(`${to} already has registered checkouts`)
+          }
         }
-        if (directory === destination || directory.startsWith(destination + '@')) {
-          throw new Error(`${to} already has registered checkouts`)
+        for (const [, target] of moves) {
+          if (exists(target)) throw new Error(`${target} already exists`)
+          // Resolve parents before any moves, including nested branch destinations.
+          fs.mkdirSync(path.dirname(target), { recursive: true })
         }
-      }
-      for (const [, target] of moves) {
-        if (exists(target)) throw new Error(`${target} already exists`)
-        // Resolve parents before any moves, including nested branch destinations.
-        fs.mkdirSync(path.dirname(target), { recursive: true })
-      }
 
-      originalConfig = fs.readFileSync(path.join(source, '.git', 'config'))
-      for (const [oldPath, newPath] of moves) {
-        fs.renameSync(oldPath, newPath)
-        moved.push([oldPath, newPath])
-      }
-      const linked = entries.slice(1).map((entry) => {
-        const directory = entry[0].slice('worktree '.length)
-        return mapping.get(directory) || directory
-      })
-      git(destination, 'worktree', 'repair', ...linked)
-      git(destination, 'config', 'remote.origin.url', replaceURL(urls[0], from, to))
-      if (pushurls.length) {
-        git(destination, 'config', '--unset-all', 'remote.origin.pushurl')
-        for (const url of pushurls) {
-          git(destination, 'config', '--add', 'remote.origin.pushurl', replaceURL(url, from, to))
+        originalConfig = fs.readFileSync(path.join(source, '.git', 'config'))
+        for (const [oldPath, newPath] of moves) {
+          fs.renameSync(oldPath, newPath)
+          moved.push([oldPath, newPath])
         }
-      }
-      return worktrees.map((directory) => mapping.get(directory) || directory)
-    })
+        const linked = entries.slice(1).map((entry) => {
+          const directory = entry[0].slice('worktree '.length)
+          return mapping.get(directory) || directory
+        })
+        git(destination, 'worktree', 'repair', ...linked)
+        git(destination, 'config', 'remote.origin.url', replaceURL(urls[0], from, to))
+        replacePushURLs(destination, pushurls, from, to)
+        return worktrees.map((directory) => mapping.get(directory) || directory)
+      },
+      { rename: { from, to } }
+    )
   } catch (err) {
     if (moved.length) {
       try {
@@ -126,6 +125,105 @@ export default function renameRoot(from, to) {
   )
 }
 
+// Finish a root move interrupted before Git links or origin were repaired.
+// Validate the on-disk Git pointers before moving or repairing any worktree.
+export function finishRootRename(from, to, registered) {
+  const source = repositoryPath(from)
+  const destination = repositoryPath(to)
+  if (exists(source)) throw new Error('Original root still exists; cannot finish its move')
+  if (fs.lstatSync(destination).isSymbolicLink()) throw new Error('Renamed root is a symbolic link')
+  const common = path.join(destination, '.git')
+  if (
+    !fs.lstatSync(common).isDirectory() ||
+    fs.realpathSync(git(destination, 'rev-parse', '--path-format=absolute', '--git-common-dir')) !==
+      fs.realpathSync(common) ||
+    fs.realpathSync(git(destination, 'rev-parse', '--show-toplevel')) !==
+      fs.realpathSync(destination)
+  ) {
+    throw new Error('Renamed destination is not a standalone root repository')
+  }
+  if (fs.realpathSync(destination) === fs.realpathSync(manifestDirectory())) {
+    throw new Error('Cannot rename the active manifest repository')
+  }
+  const urls = configValues(destination, 'remote.origin.url')
+  if (urls.length !== 1 || !matches(urls[0], from, to)) {
+    throw new Error('Renamed root has an unexpected origin')
+  }
+  const pushurls = configValues(destination, 'remote.origin.pushurl')
+  const entries = git(destination, 'worktree', 'list', '--porcelain', '-z')
+    .split('\0\0')
+    .filter(Boolean)
+    .slice(1)
+    .map((entry) => entry.split('\0'))
+  const moves = entries.map((entry) => {
+    const oldPath = entry[0].slice('worktree '.length)
+    const owned = oldPath.startsWith(source + '@') || oldPath.startsWith(destination + '@')
+    const target = oldPath.startsWith(source + '@')
+      ? destination + oldPath.slice(source.length)
+      : oldPath
+    if (owned && entry.some((field) => field === 'locked' || field.startsWith('locked '))) {
+      throw new Error(`Linked worktree is locked: ${oldPath}`)
+    }
+    if (oldPath !== target && exists(oldPath) && exists(target)) {
+      throw new Error(`Both worktree paths exist: ${oldPath} and ${target}`)
+    }
+    const actual = exists(target) ? target : oldPath
+    if (!exists(actual) || fs.lstatSync(actual).isSymbolicLink()) {
+      throw new Error(`Missing or symbolic linked worktree: ${actual}`)
+    }
+    const pointerFile = path.join(actual, '.git')
+    if (!fs.lstatSync(pointerFile).isFile()) throw new Error(`Invalid Git pointer: ${actual}`)
+    const pointer = /^gitdir: (.+)\r?\n?$/.exec(fs.readFileSync(pointerFile, 'utf8'))
+    if (!pointer) throw new Error(`Invalid Git pointer: ${actual}`)
+    let metadata = path.resolve(actual, pointer[1])
+    if (metadata.startsWith(path.join(source, '.git/worktrees') + path.sep)) {
+      metadata = common + metadata.slice(path.join(source, '.git').length)
+    }
+    if (path.dirname(metadata) !== path.join(common, 'worktrees')) {
+      throw new Error(`Worktree belongs to another repository: ${actual}`)
+    }
+    const backlink = fs.readFileSync(path.join(metadata, 'gitdir'), 'utf8').trim()
+    if (![path.join(oldPath, '.git'), path.join(target, '.git')].includes(backlink)) {
+      throw new Error(`Unexpected worktree backlink: ${actual}`)
+    }
+    return [actual, target]
+  })
+  for (const directory of registered.filter((name) => name.startsWith(source + '@'))) {
+    if (!moves.some(([, target]) => target === destination + directory.slice(source.length))) {
+      throw new Error(`Missing registered worktree: ${directory}`)
+    }
+  }
+  for (const [actual, target] of moves) {
+    if (actual === target) continue
+    fs.mkdirSync(path.dirname(target), { recursive: true })
+    fs.renameSync(actual, target)
+  }
+  git(destination, 'worktree', 'repair', ...moves.map(([, target]) => target))
+  git(destination, 'config', 'remote.origin.url', replaceURL(urls[0], from, to))
+  replacePushURLs(destination, pushurls, from, to)
+  for (const directory of registered.filter((name) => name.startsWith(source + '@'))) {
+    removeEmptyParents(directory, path.dirname(source))
+  }
+}
+
+// Set each push URL in place, so an interruption cannot lose the remaining URLs.
+function replacePushURLs(destination, pushurls, from, to) {
+  for (const url of pushurls) {
+    const replacement = replaceURL(url, from, to)
+    if (replacement !== url) {
+      git(
+        destination,
+        'config',
+        '--fixed-value',
+        '--replace-all',
+        'remote.origin.pushurl',
+        replacement,
+        url
+      )
+    }
+  }
+}
+
 function matches(url, from, to) {
   const match = parseURL(url)
   return match && [from.toLowerCase(), to.toLowerCase()].includes(match[2].toLowerCase())

package/lib/rename.js

@@ -1,18 +1,38 @@
 import fs from 'bare-fs'
 import path from 'bare-path'
 import { spawnSync } from 'bare-subprocess'
-import { updateRegistry } from './registry.js'
+import { manifestDirectory, updateRegistry } from './registry.js'
 import repositoryPath from './repository-path.js'
 import checkedOutBranch from './checked-out-branch.js'
 import removeEmptyParents from './remove-empty-parents.js'
 import renameRoot from './rename-root.js'
+import commitManifest from './commit-manifest.js'
+import { refreshCheckpoint } from './checkpoint.js'
+import { assertNoPendingPull } from './pull-state.js'
+import { withPostHooks } from './hook-context.js'
 
-export default function rename(from, to) {
+export default function rename(from, to, options = {}) {
+  assertNoPendingPull()
+  return withPostHooks('rename', { from, to }, options, () => {
+    renameCheckout(from, to)
+    try {
+      commitManifest(manifestDirectory(), `Rename ${from} to ${to}`)
+    } catch (err) {
+      err.message = `Renamed ${from} to ${to}, but could not commit the manifest: ${err.message}`
+      err.hint =
+        'the rename is already complete; resolve the Git error and commit only workspace.json in the manifest repository'
+      throw err
+    }
+    refreshCheckpoint()
+  })
+}
+
+export function renameCheckout(from, to, { update = updateRegistry } = {}) {
   const source = repositoryPath(from)
   const destination = repositoryPath(to)
   const [base, requested] = from.split('@')
   const [target, branch] = to.split('@')
-  if (!requested && !branch) return renameRoot(from, to)
+  if (!requested && !branch) return renameRoot(from, to, { update })
   if (!requested || !branch) {
     throw new Error('Use owner/repo on both sides, or owner/repo@branch on both sides')
   }
@@ -55,20 +75,76 @@ export default function rename(from, to) {
     throw new Error(`${destination} already exists`)
   }
 
-  updateRegistry((worktrees) => {
-    const registered = worktrees.includes(source) ? source : canonical
-    if (!worktrees.includes(registered)) {
-      throw new Error(`${from} is not registered`)
-    }
-    fs.mkdirSync(path.dirname(destination), { recursive: true })
-    git(['-C', root, 'worktree', 'move', canonical, destination])
-    if (current !== branch) {
-      git(['-C', root, 'branch', '-m', current, branch])
-      retargetUpstream(root, branch)
+  update(
+    (worktrees) => {
+      const registered = worktrees.includes(source) ? source : canonical
+      if (!worktrees.includes(registered)) {
+        throw new Error(`${from} is not registered`)
+      }
+      if (worktrees.includes(destination)) throw new Error(`${to} is already registered`)
+      fs.mkdirSync(path.dirname(destination), { recursive: true })
+      git(['-C', root, 'worktree', 'move', canonical, destination])
+      if (current !== branch) {
+        git(['-C', root, 'branch', '-m', current, branch])
+        retargetUpstream(root, branch)
+      }
+      removeEmptyParents(source, path.dirname(root))
+      return worktrees.map((worktree) => (worktree === registered ? destination : worktree))
+    },
+    { rename: { from, to } }
+  )
+}
+
+export function finishBranchRename(from, to) {
+  const [base, original] = from.split('@')
+  const [target, branch] = to.split('@')
+  if (!original || !branch || base !== target) throw new Error('Invalid interrupted branch rename')
+  const root = repositoryPath(base)
+  const destination = repositoryPath(to)
+  if (fs.lstatSync(destination).isSymbolicLink()) {
+    throw new Error('Renamed worktree is a symbolic link')
+  }
+  const common = (directory) =>
+    fs.realpathSync(
+      git(['-C', directory, 'rev-parse', '--path-format=absolute', '--git-common-dir'])
+    )
+  if (
+    fs.realpathSync(git(['-C', destination, 'rev-parse', '--show-toplevel'])) !==
+      fs.realpathSync(destination) ||
+    common(root) !== common(destination)
+  ) {
+    throw new Error('Renamed destination is not a worktree of the requested repository')
+  }
+  const current = checkedOutBranch(destination)
+  if (current === original) {
+    if (hasRef(root, `refs/heads/${branch}`)) throw new Error(`Branch ${branch} already exists`)
+    git(['-C', root, 'branch', '-m', original, branch])
+  } else if (current !== branch) {
+    throw new Error(`Renamed worktree is on an unexpected branch: ${current || 'detached HEAD'}`)
+  }
+  if (hasRef(root, `refs/heads/${original}`)) {
+    throw new Error(
+      `Original branch ${original} still exists after the rename; inspect it before retrying`
+    )
+  }
+  // Git can rename the ref before failing to rename the config section.
+  if (!hasRef(root, `refs/heads/${original}`)) {
+    const section = spawnSync('git', [
+      '-C',
+      root,
+      'config',
+      '--get-regexp',
+      `^branch\\.${original.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.`
+    ])
+    if (section.error) throw section.error
+    if (section.status === 0) {
+      git(['-C', root, 'config', '--rename-section', `branch.${original}`, `branch.${branch}`])
+    } else if (section.status !== 1) {
+      throw new Error(section.stderr.toString().trim() || 'Could not inspect branch config')
     }
-    removeEmptyParents(source, path.dirname(root))
-    return worktrees.map((worktree) => (worktree === registered ? destination : worktree))
-  })
+  }
+  retargetUpstream(root, branch)
+  removeEmptyParents(repositoryPath(from), path.dirname(root))
 }
 
 function retargetUpstream(root, branch) {

package/man/man1/git-workspace.1

@@ -0,0 +1,240 @@
+.TH GIT-WORKSPACE 1 "November 8, 2026" "git-workspace-bare" "Git Workspace Manual"
+.SH NAME
+git-workspace \- manage Git repositories and branch worktrees
+.SH SYNOPSIS
+.B git workspace init
+.I owner/repo
+.br
+.B git workspace add
+.RB [ --no-hooks ]
+.I owner/repo[@branch]
+.br
+.B git workspace remove
+.RB [ --no-hooks ]
+.I owner/repo[@branch]
+.br
+.B git workspace rename
+.RB [ --no-hooks ]
+.I from to
+.br
+.B git workspace list
+.br
+.B git workspace status
+.br
+.B git workspace pull
+.RB [ --dry-run ] " [" --no-hooks ]
+.br
+.B git workspace hook list
+.br
+.B git workspace completion bash
+.br
+.B git workspace
+.RB [ -h " | " --version ]
+.SH DESCRIPTION
+.B git workspace
+manages root repositories under
+.I ~/workspace/owner/repo
+and linked worktrees under
+.IR ~/workspace/owner/repo@branch .
+Use an at sign to separate the repository name from its branch name.
+Branches can contain slashes, for example
+.IR owner/repo@feature/jobs .
+.PP
+A Git repository containing
+.I workspace.json
+stores the portable workspace manifest.
+Repositories and worktrees have stable IDs so that renames can be applied on
+other machines without reserving old names.
+Run
+.B init
+before managing checkouts.
+.PP
+The executable can also be invoked directly as
+.BR git-workspace .
+Bare and Git must be available on
+.BR PATH .
+.SH COMMANDS
+.TP
+.BI "init " owner/repo
+Clone the manifest repository from GitHub over SSH.
+If cloning fails and the destination is absent or empty, initialize it locally
+and configure its origin URL instead.
+Creating the repository on GitHub remains manual.
+Create and commit an empty version-1 manifest when none exists, save the local
+configuration, and record the applied workspace state.
+An existing manifest is validated and preserved; its checkouts are not created.
+.TP
+.BI "add " owner/repo[@branch]
+Clone or initialize a root repository, or create a linked branch worktree.
+Adding a worktree also registers its root.
+Reuse an existing local branch, track a matching origin branch, or create a new
+branch from the root's HEAD without tracking another branch.
+An empty root needs its first commit before a worktree can be created.
+Existing destinations must belong to the requested repository and branch.
+Repeating add does not fetch, switch branches, or duplicate registrations.
+.TP
+.BI "remove " owner/repo[@branch]
+Remove the checkout and its manifest entry.
+A root must have the expected origin, no local changes or untracked files, and
+no linked worktrees.
+The active manifest repository cannot be removed.
+Worktree removal deletes its actual checked-out branch, even if unmerged;
+a detached worktree has no branch to delete.
+Dirty and locked worktrees are refused.
+Ignored files are deleted with the checkout.
+Remote project branches and repositories are not deleted.
+.TP
+.BI "rename " "from to"
+Rename a root repository or a branch worktree and retain its stable ID.
+A root rename moves its linked worktrees, repairs Git links, and updates
+matching
+origin URLs to the new owner/repository name.
+A branch worktree rename also renames its local branch.
+Running work and uncommitted files are preserved.
+The repository is not renamed or transferred on GitHub; do that separately.
+.TP
+.B list
+Print registered repository and worktree names, one per line.
+.TP
+.B status
+Show each registered checkout as clean, modified, or missing.
+.TP
+.B pull
+Fetch and fast-forward the manifest from its configured upstream, then apply
+additions, renames, and clean removals to this machine's layout.
+Without an upstream, use the current branch name on origin.
+Require a clean manifest checkout and refuse divergent manifest histories.
+Preserve dirty work in retained checkouts; refuse unsafe removals and occupied
+destinations.
+Existing project repositories are not fetched or pulled.
+Interrupted operations are recorded locally and resumed by the next pull.
+Other manifest mutations are blocked while a pull is pending.
+Pull creates no manifest commits and pushes nothing.
+.TP
+.B hook list
+List discovered post hooks with their command, name, and resolved executable
+path.
+This command works before workspace initialization and does not execute hooks.
+.TP
+.B completion bash
+Print the Bash completion script.
+Load it in an interactive shell with:
+.PP
+.RS
+.nf
+eval "$(git-workspace completion bash)"
+.fi
+.RE
+.PP
+Also load Git's Bash completion for completion of the
+.B git workspace
+form.
+.SH OPTIONS
+.TP
+.B \-\-no-hooks
+Skip post hooks for add, remove, rename, or pull.
+During pull, also discard pending hook delivery from an interrupted operation.
+This does not disable manifest commits or pushes.
+.TP
+.B \-\-dry-run
+With pull, fetch the manifest and preview layout changes and blockers without
+applying them, advancing the applied checkpoint, or executing hooks.
+.TP
+.B \-h
+Print command-line usage.
+Use it after a command for that command's options.
+.TP
+.B \-\-help
+Git handles
+.B git workspace --help
+as a request for this manual page.
+.B git-workspace --help
+prints command-line usage instead.
+.TP
+.B \-\-version
+Print the package version.
+.SH MANIFEST COMMITS AND PUSHES
+Init commits newly created manifests.
+Successful add, remove, and rename operations commit the current
+.I workspace.json
+and attempt to push the manifest branch.
+Pending manual edits to the manifest are included; unrelated staged files remain
+staged.
+No empty commit is created when the manifest is unchanged.
+.PP
+Push to the configured upstream, or to the same branch name on origin when no
+upstream is configured, and establish tracking on success.
+Only the manifest branch is pushed, including its existing local commits.
+Project branches and tags are not published.
+Pushes never force, fetch, or merge remote history.
+.PP
+A push failure warns but retains the local commit and completed checkout
+operation, allows post hooks and local applied tracking, and does not turn a
+successful command into an error.
+Repeat add for a registered checkout to retry pushing without another commit,
+or push the manifest branch manually.
+.PP
+A commit failure reports an error and retains the local changes.
+Add can be repeated after fixing the Git error.
+After remove or rename, commit the manifest manually; the filesystem operation
+is already complete.
+.SH HOOKS
+Executable files on PATH named
+.I git-workspace-hook-<command>-post-<name>
+run after add, remove, and rename, including operations performed by pull.
+Installation on PATH enables hooks without registration or manifest
+configuration.
+Hooks receive the command and post as arguments and version-1 JSON on standard
+input, including stable IDs, before/after checkout paths, and the operation
+result.
+Hooks also run for attempted operations that partially fail.
+.PP
+Hooks run sequentially and are awaited.
+Failures warn without changing the workspace command's exit status or rolling
+back its work.
+Repeated delivery is possible after an interrupted pull; hooks must be
+idempotent.
+Help, completion, and dry runs do not execute hooks.
+.PP
+The optional
+.B git-workspace-hook-tmux
+package creates detached sessions, preserves running panes across renames, and
+terminates managed sessions and their programs when checkouts are removed.
+Install it with
+.BR "npm install -g git-workspace-hook-tmux" .
+.SH FILES
+.TP
+.I ~/.config/git-workspace/config.json
+Local configuration identifying the absolute manifest repository path.
+.TP
+.I <manifest-repository>/workspace.json
+Version-1 manifest containing repository names, branch worktrees, and stable
+IDs.
+.TP
+.I <manifest-repository>/.git/refs/git-workspace/applied
+Local Git ref recording the last verified applied manifest commit.
+.TP
+.I <manifest-repository>/.git/workspace-pull.json
+Local progress journal used to resume an interrupted pull.
+.SH EXAMPLES
+.nf
+git workspace init me/workspace
+git workspace add holepunchto/brittle
+git workspace add holepunchto/brittle@feature/jobs
+git workspace rename holepunchto/brittle@feature/jobs holepunchto/brittle@fixes
+git workspace pull --dry-run
+git workspace pull
+git workspace remove holepunchto/brittle@fixes
+git workspace hook list
+.fi
+.SH EXIT STATUS
+Exit 0 on success and 1 on command failure, including blockers found by pull.
+Push failures and post-hook failures are warnings and preserve the command's
+original exit status.
+.SH SEE ALSO
+.BR git (1),
+.BR git-worktree (1)
+.PP
+Project documentation:
+.UR https://github.com/nicolasfont/git-workspace-bare
+.UE