git-workspace-bare 0.3.0 → 0.4.0

package/README.md

@@ -4,6 +4,27 @@ Manage Git worktrees as development workspaces.
 
 The CLI can clone GitHub repositories or initialize them locally, create branch worktrees, list registered checkouts, and unregister them.
 
+## Contents
+
+- [Installation](#installation)
+  - [Manual page](#manual-page)
+  - [Bash completion](#bash-completion)
+- [Usage](#usage)
+  - [Initialize a manifest repository](#initialize-a-manifest-repository)
+  - [Synchronize from the manifest](#synchronize-from-the-manifest)
+  - [Add a repository](#add-a-repository)
+  - [Add a branch worktree](#add-a-branch-worktree)
+  - [Rename commits](#rename-commits)
+  - [Rename a root repository](#rename-a-root-repository)
+  - [Rename a branch worktree](#rename-a-branch-worktree)
+  - [List repositories](#list-repositories)
+  - [Check workspace status](#check-workspace-status)
+  - [Remove a repository or worktree](#remove-a-repository-or-worktree)
+  - [Command hooks](#command-hooks)
+    - [Available hooks](#available-hooks)
+  - [Errors](#errors)
+- [Development](#development)
+
 ## Installation
 
 The CLI runs on [Bare](https://github.com/holepunchto/bare). Install both globally using npm:
@@ -14,6 +35,33 @@ 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):
@@ -51,7 +99,7 @@ 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.
@@ -412,9 +460,8 @@ Successful removal is silent. Existing checkouts can also be removed if previous
 ### Command hooks
 
 Executables on `PATH` named `git-workspace-hook-<command>-post-<name>` run after
-`add`, `remove`, and `rename`, including those operations performed by `pull`. For example,
-a separate tmux package could expose `git-workspace-hook-add-post-tmux` and
-`git-workspace-hook-remove-post-tmux`. Installing the executables on `PATH` enables them;
+`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
@@ -433,6 +480,20 @@ See [Writing command hooks](docs/hooks.md) for the full protocol, npm packaging
 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/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

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "git-workspace-bare",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Manage Git worktrees as development workspaces",
   "type": "module",
   "bin": {
     "git-workspace": "./bin/git-workspace.js"
   },
+  "man": [
+    "./man/man1/git-workspace.1"
+  ],
   "scripts": {
     "test": "bare test/lifecycle.js",
     "format": "prettier . --write",