aligndev 0.29.0 → 0.30.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,103 +0,0 @@
1
- import { execFileSync } from "node:child_process";
2
- import { existsSync, lstatSync, realpathSync } from "node:fs";
3
- import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
- import { errorMessage, isNodeError } from "../errors.js";
5
- export function readRepository(ctx) {
6
- const commonDir = repositoryIdentity(ctx);
7
- if (git(ctx, "rev-parse", "--is-inside-work-tree").trim() !== "true" ||
8
- basename(commonDir) !== ".git") {
9
- throw new Error("A supported non-bare Git worktree with a main .git directory is required.");
10
- }
11
- const mainWorktree = realpathSync(dirname(commonDir));
12
- const worktrees = readWorktrees(ctx, mainWorktree);
13
- if (!worktrees.some((tree) => tree.main)) {
14
- throw new Error("Cannot identify the main Git worktree.");
15
- }
16
- return { mainWorktree, commonDir, worktrees };
17
- }
18
- function repositoryIdentity(ctx) {
19
- return realpathSync(git(ctx, "rev-parse", "--path-format=absolute", "--git-common-dir").trim());
20
- }
21
- export function isProjectTrackedDirectory(ctx, path, identity) {
22
- const root = realpathSync(git(ctx, "rev-parse", "--show-toplevel").trim());
23
- const logicalPath = join(realpathSync(dirname(path)), basename(path));
24
- if (isInside(root, logicalPath) &&
25
- hasTrackedFiles({ ...ctx, cwd: root }, relative(root, logicalPath)))
26
- return true;
27
- const resolved = realpathSync(path);
28
- const source = { ...ctx, cwd: resolved };
29
- if (optionalRepositoryIdentity(source) !== identity)
30
- return false;
31
- const sourceRoot = git(source, "rev-parse", "--show-toplevel").trim();
32
- return hasTrackedFiles({ ...ctx, cwd: sourceRoot }, relative(sourceRoot, resolved));
33
- }
34
- function hasTrackedFiles(ctx, path) {
35
- return (git(ctx, "--literal-pathspecs", "ls-files", "-z", "--", path === "" ? "." : path).length > 0);
36
- }
37
- function optionalRepositoryIdentity(ctx) {
38
- try {
39
- return repositoryIdentity(ctx);
40
- }
41
- catch (error) {
42
- if (errorMessage(error).includes("not a git repository") ||
43
- (isNodeError(error) && error.code === "ENOENT"))
44
- return;
45
- throw error;
46
- }
47
- }
48
- export function readWorktrees(ctx, mainWorktree) {
49
- return git(ctx, "worktree", "list", "--porcelain", "-z")
50
- .split("\0\0")
51
- .filter((record) => record.length > 0)
52
- .map((record) => parseWorktree(record, mainWorktree));
53
- }
54
- function parseWorktree(record, mainWorktree) {
55
- const fields = record.split("\0");
56
- const pathField = fields.find((field) => field.startsWith("worktree "));
57
- if (pathField === undefined)
58
- throw new Error("Git returned a worktree record without a path.");
59
- const path = canonicalPath(pathField.slice("worktree ".length));
60
- const branchField = fields.find((field) => field.startsWith("branch "));
61
- return {
62
- path,
63
- branch: branchField === undefined ? null : branchField.slice("branch refs/heads/".length),
64
- main: path === mainWorktree,
65
- exists: existsSync(path),
66
- locked: fields.some((field) => field === "locked" || field.startsWith("locked ")),
67
- prunable: fields.some((field) => field === "prunable" || field.startsWith("prunable ")),
68
- };
69
- }
70
- export function canonicalPath(path) {
71
- try {
72
- return realpathSync(path);
73
- }
74
- catch (error) {
75
- if (!isNodeError(error) || (error.code !== "ENOENT" && error.code !== "ENOTDIR"))
76
- throw error;
77
- const parent = dirname(path);
78
- return parent === path ? resolve(path) : resolve(canonicalPath(parent), basename(path));
79
- }
80
- }
81
- export function pathExists(path) {
82
- try {
83
- lstatSync(path);
84
- return true;
85
- }
86
- catch (error) {
87
- if (isNodeError(error) && error.code === "ENOENT")
88
- return false;
89
- throw error;
90
- }
91
- }
92
- export function isInside(parent, path) {
93
- const child = relative(parent, path);
94
- return child === "" || (!isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`));
95
- }
96
- export function git(ctx, ...args) {
97
- return execFileSync("git", args, {
98
- cwd: ctx.cwd,
99
- env: ctx.env,
100
- encoding: "utf8",
101
- stdio: ["ignore", "pipe", "pipe"],
102
- });
103
- }
@@ -1,8 +0,0 @@
1
- import { type Repository } from "./git.js";
2
- import type { WorktreeContext } from "./worktree-cli.js";
3
- export interface RemoveReport {
4
- mainWorktree: string;
5
- path: string;
6
- removed: true;
7
- }
8
- export declare function removeWorktree(ctx: WorktreeContext, repo: Repository, input: string): RemoveReport;
@@ -1,62 +0,0 @@
1
- import { realpathSync } from "node:fs";
2
- import { join, resolve } from "node:path";
3
- import { isNodeError } from "../errors.js";
4
- import { readProjectReport } from "../project/layout.js";
5
- import { canonicalPath, git, isInside, pathExists } from "./git.js";
6
- export function removeWorktree(ctx, repo, input) {
7
- const path = canonicalPath(resolve(ctx.cwd, input));
8
- const target = repo.worktrees.find((tree) => tree.path === path);
9
- if (target === undefined)
10
- throw new Error(`Not an exact registered worktree root of this repository: ${path}`);
11
- if (target.main)
12
- throw new Error(`Cannot remove the main worktree: ${path}`);
13
- if (target.locked)
14
- throw new Error(`Cannot remove locked worktree: ${path}`);
15
- if (!target.exists)
16
- throw new Error(`Worktree is missing: ${path}. Inspect Git's registration manually.`);
17
- const nested = repo.worktrees.find((tree) => tree.path !== path && isInside(path, tree.path));
18
- if (nested !== undefined)
19
- throw new Error(`Cannot remove ${path}: it contains another registered worktree root: ${nested.path}.`);
20
- if (git({ ...ctx, cwd: path }, "status", "--porcelain", "-z", "--untracked-files=all").length > 0) {
21
- throw new Error(`Cannot remove dirty worktree: ${path}. Preserve staged, modified and untracked files first.`);
22
- }
23
- protectSharedDirectories(ctx, repo, path);
24
- git({ ...ctx, cwd: repo.mainWorktree }, "worktree", "remove", "--", path);
25
- return { mainWorktree: repo.mainWorktree, path, removed: true };
26
- }
27
- function protectSharedDirectories(ctx, repo, target) {
28
- for (const tree of repo.worktrees.filter((candidate) => candidate.exists)) {
29
- const report = readProjectReport(ctx.alignfirstCommand, tree.path, ctx.env);
30
- if ("error" in report)
31
- throw new Error(`Cannot read shared-directory protection report for ${tree.path}: ${report.error}`);
32
- const protectedPaths = [];
33
- if (report.companion !== null)
34
- protectedPaths.push(canonicalPath(report.companion.dir));
35
- for (const name of [".plans", "_aligndev"]) {
36
- const location = report.locations[name];
37
- if (location.exists)
38
- protectExistingTarget(protectedPaths, location.path);
39
- }
40
- if (tree.path !== target) {
41
- for (const name of [".local", ".plans"]) {
42
- const source = join(tree.path, name);
43
- if (pathExists(source))
44
- protectExistingTarget(protectedPaths, source);
45
- }
46
- }
47
- for (const path of protectedPaths) {
48
- if (isInside(target, path)) {
49
- throw new Error(`Cannot remove ${target}: it contains protected shared directory ${path} referenced by ${tree.path}.`);
50
- }
51
- }
52
- }
53
- }
54
- function protectExistingTarget(paths, path) {
55
- try {
56
- paths.push(realpathSync(path));
57
- }
58
- catch (error) {
59
- if (!isNodeError(error) || (error.code !== "ENOENT" && error.code !== "ENOTDIR"))
60
- throw error;
61
- }
62
- }
@@ -1,18 +0,0 @@
1
- import { type Repository, type Worktree } from "./git.js";
2
- import type { WorktreeContext } from "./worktree-cli.js";
3
- export interface DirectoryPreparation {
4
- directories: Record<".local" | ".plans", DirectoryReport>;
5
- warnings: string[];
6
- }
7
- export interface DirectoryReport {
8
- path: string;
9
- mode: "directory" | "symlink" | "tracked" | "companion" | "absent";
10
- target: string | null;
11
- }
12
- export interface WorktreeReport extends DirectoryPreparation {
13
- mainWorktree: string;
14
- worktree: Worktree;
15
- }
16
- export declare function setupWorktree(ctx: WorktreeContext, repo: Repository, input?: string): WorktreeReport;
17
- export declare function prepareDirectories(ctx: WorktreeContext, repo: Repository, destination: string, commit: string, includeIndex?: boolean): DirectoryPreparation;
18
- export declare function finishSetup(ctx: WorktreeContext, repo: Repository, destination: string, prepared: DirectoryPreparation, expectedBranch?: string): WorktreeReport;
@@ -1,192 +0,0 @@
1
- import { appendFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, statSync, symlinkSync, } from "node:fs";
2
- import { dirname, join, resolve } from "node:path";
3
- import { errorMessage } from "../errors.js";
4
- import { readReport, validateEffectivePlans } from "../project/plans.js";
5
- import { canonicalPath, git, isProjectTrackedDirectory, pathExists, readRepository, } from "./git.js";
6
- export function setupWorktree(ctx, repo, input) {
7
- const worktree = selectWorktree(ctx, repo, input);
8
- let prepared;
9
- try {
10
- if (worktree.main)
11
- return reportMain(ctx, repo, worktree);
12
- prepared = prepareDirectories(ctx, repo, worktree.path, "HEAD", true);
13
- }
14
- catch (error) {
15
- throw setupFailure(ctx, worktree.path, "directory preparation", error);
16
- }
17
- return finishSetup(ctx, repo, worktree.path, prepared);
18
- }
19
- function selectWorktree(ctx, repo, input) {
20
- const path = canonicalPath(input === undefined ? git(ctx, "rev-parse", "--show-toplevel").trim() : resolve(ctx.cwd, input));
21
- const worktree = repo.worktrees.find((tree) => tree.path === path);
22
- if (worktree === undefined || !worktree.exists || !pathExists(path)) {
23
- throw new Error(`Setup requires an existing registered worktree root of this repository: ${path}`);
24
- }
25
- const targetCtx = { ...ctx, cwd: path };
26
- const targetRepo = readRepository(targetCtx);
27
- if (targetRepo.commonDir !== repo.commonDir ||
28
- canonicalPath(git(targetCtx, "rev-parse", "--show-toplevel").trim()) !== path) {
29
- throw new Error(`Setup requires an exact registered worktree root: ${path}`);
30
- }
31
- return worktree;
32
- }
33
- function reportMain(ctx, repo, worktree) {
34
- const sourceCtx = { ...ctx, cwd: repo.mainWorktree };
35
- const report = readReport(sourceCtx);
36
- validateEffectivePlans(sourceCtx);
37
- const plans = report.locations[".plans"];
38
- return {
39
- mainWorktree: repo.mainWorktree,
40
- worktree,
41
- directories: {
42
- ".local": describeDirectory(join(repo.mainWorktree, ".local")),
43
- ".plans": plans.in === "companion"
44
- ? { path: plans.path, mode: "companion", target: null }
45
- : describeDirectory(plans.path),
46
- },
47
- warnings: [],
48
- };
49
- }
50
- function describeDirectory(path) {
51
- if (!pathExists(path))
52
- return { path, mode: "absent", target: null };
53
- if (!statSync(path).isDirectory())
54
- throw new Error(`Source is not a usable directory: ${path}`);
55
- return lstatSync(path).isSymbolicLink()
56
- ? { path, mode: "symlink", target: realpathSync(path) }
57
- : { path, mode: "directory", target: null };
58
- }
59
- export function prepareDirectories(ctx, repo, destination, commit, includeIndex = false) {
60
- const sourceCtx = { ...ctx, cwd: repo.mainWorktree };
61
- const report = readReport(sourceCtx);
62
- const plansTarget = validateEffectivePlans(sourceCtx);
63
- const targetCtx = includeIndex ? { ...ctx, cwd: destination } : sourceCtx;
64
- const warnings = [];
65
- const local = planLocal(sourceCtx, targetCtx, repo, destination, commit, includeIndex, warnings);
66
- const plans = report.locations[".plans"];
67
- if (plans.in === "companion") {
68
- return {
69
- directories: {
70
- ".local": local,
71
- ".plans": { path: plans.path, mode: "companion", target: null },
72
- },
73
- warnings,
74
- };
75
- }
76
- if (targetTracks(targetCtx, commit, ".plans", includeIndex)) {
77
- throw new Error(`Target commit${includeIndex ? " or index" : ""} tracks .plans. See the \`work-files-setup\` topic of \`${ctx.forms.aligndev} guide\` for authorized preparation.`);
78
- }
79
- return {
80
- directories: {
81
- ".local": local,
82
- ".plans": { path: join(destination, ".plans"), mode: "symlink", target: plansTarget },
83
- },
84
- warnings,
85
- };
86
- }
87
- function planLocal(sourceCtx, targetCtx, repo, destination, commit, includeIndex, warnings) {
88
- const path = join(destination, ".local");
89
- if (targetTracks(targetCtx, commit, ".local", includeIndex)) {
90
- warnings.push("Target branch tracks .local; it remains branch-local and is not shared.");
91
- return { path, mode: "tracked", target: null };
92
- }
93
- const source = join(repo.mainWorktree, ".local");
94
- if (!pathExists(source))
95
- return { path, mode: "absent", target: null };
96
- if (!statSync(source).isDirectory())
97
- throw new Error(`Source is not a usable directory: ${source}`);
98
- const target = realpathSync(source);
99
- if (isProjectTrackedDirectory(sourceCtx, source, repo.commonDir)) {
100
- warnings.push("Main-worktree .local belongs to tracked content on another branch; leaving .local absent.");
101
- return { path, mode: "absent", target: null };
102
- }
103
- return { path, mode: "symlink", target };
104
- }
105
- function targetTracks(ctx, commit, path, includeIndex) {
106
- return (git(ctx, "--literal-pathspecs", "ls-tree", "-r", "--name-only", "-z", commit, "--", path)
107
- .length > 0 ||
108
- (includeIndex && git(ctx, "--literal-pathspecs", "ls-files", "-z", "--", path).length > 0));
109
- }
110
- export function finishSetup(ctx, repo, destination, prepared, expectedBranch) {
111
- let step = "directory conflict checks";
112
- try {
113
- const targetCtx = { ...ctx, cwd: destination };
114
- checkDestinations(prepared.directories);
115
- step = "directory links and local Git exclusions";
116
- applyDirectories(targetCtx, repo, prepared.directories);
117
- step = "effective work-files verification";
118
- validateEffectivePlans(targetCtx);
119
- const worktree = readRepository(targetCtx).worktrees.find((tree) => tree.path === destination);
120
- if (worktree === undefined ||
121
- (expectedBranch !== undefined && worktree.branch !== expectedBranch)) {
122
- throw new Error("Worktree does not have the requested branch in Git's registry.");
123
- }
124
- return { mainWorktree: repo.mainWorktree, worktree, ...prepared };
125
- }
126
- catch (error) {
127
- throw setupFailure(ctx, destination, step, error, expectedBranch);
128
- }
129
- }
130
- function checkDestinations(directories) {
131
- for (const directory of Object.values(directories)) {
132
- if (directory.mode !== "symlink")
133
- continue;
134
- if (directory.target === null)
135
- throw new Error("Missing symlink target.");
136
- if (!pathExists(directory.path))
137
- continue;
138
- if (lstatSync(directory.path).isSymbolicLink()) {
139
- try {
140
- if (realpathSync(directory.path) === directory.target)
141
- continue;
142
- }
143
- catch {
144
- // Broken and cyclic links are conflicts, not missing destinations.
145
- }
146
- }
147
- throw new Error(`Conflicting shared directory destination: ${directory.path}. Existing content was preserved.`);
148
- }
149
- }
150
- function applyDirectories(ctx, repo, directories) {
151
- const links = Object.entries(directories).filter(([, directory]) => directory.mode === "symlink");
152
- if (links.length === 0)
153
- return;
154
- for (const [name, directory] of links) {
155
- if (!pathExists(directory.path))
156
- symlinkSync(join(repo.mainWorktree, name), directory.path, "dir");
157
- }
158
- ensureExclusions(ctx, repo, links.map(([name]) => name));
159
- for (const [name, directory] of links) {
160
- try {
161
- git(ctx, "check-ignore", "-q", "--", name);
162
- }
163
- catch {
164
- throw new Error(`Generated link ${directory.path} is not ignored. Inspect conflicting tracked ignore rules; they were not edited.`);
165
- }
166
- if (realpathSync(directory.path) !== directory.target)
167
- throw new Error(`Link target changed: ${directory.path}`);
168
- }
169
- }
170
- function ensureExclusions(ctx, repo, names) {
171
- const exclude = git({ ...ctx, cwd: repo.mainWorktree }, "rev-parse", "--path-format=absolute", "--git-path", "info/exclude").trim();
172
- let content = pathExists(exclude) ? readFileSync(exclude, "utf8") : "";
173
- for (const name of names) {
174
- const pattern = `/${name}`;
175
- if (content.split(/\r?\n/u).includes(pattern))
176
- continue;
177
- mkdirSync(dirname(exclude), { recursive: true });
178
- const addition = `${content.endsWith("\n") || content === "" ? "" : "\n"}${pattern}\n`;
179
- appendFileSync(exclude, addition);
180
- content += addition;
181
- }
182
- }
183
- function setupFailure(ctx, destination, step, error, branch) {
184
- const quoted = `'${destination.replaceAll("'", "'\\''")}'`;
185
- return new Error(`Worktree setup failed during ${step}: ${errorMessage(error)}\n` +
186
- `Retained worktree ${destination}${branch === undefined ? " and its Git state" : ` and branch ${branch}`}. ` +
187
- `Inspect and repair the failed step manually, then retry with \`${ctx.forms.aligndev} worktree setup ${quoted}\`.` +
188
- (branch === undefined
189
- ? ""
190
- : ` Or remove it with \`${ctx.forms.aligndev} worktree remove ${quoted}\` after preserving any work.`) +
191
- " No rollback was attempted.");
192
- }
@@ -1,10 +0,0 @@
1
- import type { CommandForms } from "../command-form.js";
2
- import type { Output } from "../output.js";
3
- import { type GitContext } from "./git.js";
4
- export interface WorktreeContext extends GitContext {
5
- stdout: Output;
6
- stderr: Output;
7
- forms: CommandForms;
8
- alignfirstCommand: string[];
9
- }
10
- export declare function runWorktree(tokens: string[], ctx: WorktreeContext): number;
@@ -1,140 +0,0 @@
1
- import { parseArgs } from "node:util";
2
- import { addWorktree } from "./add.js";
3
- import { readRepository } from "./git.js";
4
- import { removeWorktree } from "./remove.js";
5
- import { setupWorktree } from "./setup.js";
6
- export function runWorktree(tokens, ctx) {
7
- const command = parseWorktreeArgs(tokens, ctx.forms.aligndev);
8
- if (command.kind === "help") {
9
- ctx.stdout.write(renderHelp(ctx.forms.aligndev));
10
- return 0;
11
- }
12
- const repo = readRepository(ctx);
13
- if (command.kind === "list") {
14
- const report = { mainWorktree: repo.mainWorktree, worktrees: repo.worktrees };
15
- ctx.stdout.write(command.json ? json(report) : renderList(repo.worktrees));
16
- return 0;
17
- }
18
- if (command.kind === "remove") {
19
- const report = removeWorktree(ctx, repo, command.path);
20
- ctx.stdout.write(command.json ? json(report) : `Removed ${report.path}; branch preserved.\n`);
21
- return 0;
22
- }
23
- const report = command.kind === "setup"
24
- ? setupWorktree(ctx, repo, command.path)
25
- : addWorktree(ctx, repo, command.options);
26
- for (const warning of report.warnings)
27
- ctx.stderr.write(`Warning: ${warning}\n`);
28
- ctx.stdout.write(command.json ? json(report) : renderReady(report));
29
- return 0;
30
- }
31
- function parseWorktreeArgs(tokens, aligndev) {
32
- const [command, ...rest] = tokens;
33
- if (command === undefined || command === "--help" || command === "-h") {
34
- if (tokens.length > 1)
35
- throw new Error("Unexpected worktree help arguments.");
36
- return { kind: "help" };
37
- }
38
- if (command !== "add" && command !== "setup" && command !== "list" && command !== "remove") {
39
- throw new Error(`Unknown worktree command: ${command}`);
40
- }
41
- const { values, positionals } = parseArgs({
42
- args: rest,
43
- strict: true,
44
- allowPositionals: true,
45
- options: {
46
- json: { type: "boolean", default: false },
47
- help: { type: "boolean", short: "h", default: false },
48
- ...(command === "add" ? { b: { type: "string" } } : {}),
49
- },
50
- });
51
- if (values.help)
52
- return { kind: "help" };
53
- const newBranch = typeof values.b === "string" ? values.b : undefined;
54
- const count = positionals.length;
55
- const expected = command === "list" ? 0 : command === "remove" ? 1 : 2;
56
- const validCount = command === "setup"
57
- ? count <= 1
58
- : command === "add" && newBranch !== undefined
59
- ? count === 1 || count === 2
60
- : count === expected;
61
- if (!validCount) {
62
- throw new Error(`Invalid arguments. Run \`${aligndev} worktree ${command} --help\`.`);
63
- }
64
- if (command === "list")
65
- return { kind: "list", json: values.json };
66
- if (command === "setup")
67
- return { kind: "setup", path: positionals[0], json: values.json };
68
- const path = positionals[0];
69
- if (path === undefined)
70
- throw new Error("A worktree path is required.");
71
- if (command === "remove")
72
- return { kind: "remove", path, json: values.json };
73
- const branch = newBranch ?? positionals[1];
74
- if (branch === undefined)
75
- throw new Error("A branch is required.");
76
- return {
77
- kind: "add",
78
- json: values.json,
79
- options: {
80
- path,
81
- branch,
82
- newBranch: newBranch !== undefined,
83
- start: newBranch === undefined ? undefined : positionals[1],
84
- },
85
- };
86
- }
87
- function json(report) {
88
- return `${JSON.stringify(report, undefined, 2)}\n`;
89
- }
90
- function renderList(worktrees) {
91
- return worktrees
92
- .map((tree) => `${tree.path} [${tree.branch ?? "detached"}]${tree.main ? " main" : ""}${tree.exists ? "" : " missing"}${tree.locked ? " locked" : ""}${tree.prunable ? " prunable" : ""}\n`)
93
- .join("");
94
- }
95
- function renderReady(report) {
96
- return [
97
- `Worktree ready: ${report.worktree.path} [${report.worktree.branch ?? "detached"}]`,
98
- ...Object.entries(report.directories).map(([name, directory]) => `${name}: ${directory.mode} ${directory.path}${directory.target === null ? "" : ` -> ${directory.target}`}`),
99
- "Readiness covers Git and work files only; follow the project's install/build/test procedure.",
100
- "",
101
- ].join("\n");
102
- }
103
- function renderHelp(command) {
104
- return `Usage:
105
- ${command} worktree add <path> <branch> [--json]
106
- ${command} worktree add <path> -b <branch> [<start-point>] [--json]
107
- ${command} worktree setup [<path>] [--json]
108
- ${command} worktree list [--json]
109
- ${command} worktree remove <path> [--json]
110
- ${command} worktree <command> --help
111
-
112
- Paths resolve from the caller, including linked worktrees and subdirectories.
113
- Existing branches are reused; an unambiguous fetched remote branch may create its tracking branch.
114
- -b creates a new branch from <start-point>, or the invoking worktree's HEAD. No fetch or base refresh.
115
- The destination must be new and outside all registered worktrees. Occupied branches must be reused
116
- at their listed path. Bare and nonstandard Git layouts are unsupported.
117
-
118
- Add and setup share usable untracked main-worktree .plans and optional .local through symlinks, with local
119
- Git exclusions. Companion plans are used directly. Tracked .local stays branch-local with a warning.
120
- Missing or project-tracked effective plans require separately authorized preparation: see the
121
- work-files-setup topic of ${command} guide.
122
- Neither command registers a companion, migrates files, installs, builds or starts application processes.
123
- Readiness covers Git and work files only; follow repository preparation and shutdown separately.
124
- Setup without a path discovers the current Git worktree root, including from a nested directory.
125
- An explicit path must be an exact existing registered root of this repository; main and detached
126
- worktrees are supported. Setup preserves branches, the index, unrelated files and Git registration.
127
- Equivalent shared links are reused. Conflicts are preserved; repair them and retry idempotent setup.
128
- Late failures retain partial preparation and report a quoted setup retry command.
129
- External tools may use this post-creation hook inside their worktree:
130
- ${command} worktree setup
131
- There is no lightweight teardown hook; the external owner manages deletion and project shutdown.
132
-
133
- List reads only Git's registry, including detached, missing, locked and prunable worktrees.
134
- Remove accepts an exact linked root, refuses main/locked/dirty/protected shared targets, and uses
135
- ordinary Git removal. It preserves branches, shared targets and companion registration; no force,
136
- pruning, process teardown or recursive fallback. Stop project activity separately before removal.
137
-
138
- --json prints one document on success; warnings and errors go to stderr. Failures exit 1.
139
- `;
140
- }