git-worktree-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 avi747av
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# git-worktree-utils
+
+A safe git worktree management CLI with automatic environment file syncing.
+
+## Features
+
+- **Safety checks** - Blocks operations with uncommitted changes or unpushed commits
+- **Branch protection** - Warns if a branch is already checked out elsewhere
+- **Main repo protection** - Prevents accidental operations on the main repository
+- **Automatic .env copying** - Copies all `.env*` files when creating new worktrees
+- **Environment syncing** - Sync `.env` files across worktrees with one command
+- **Fuzzy search** - Find worktrees by partial name match
+
+## Installation
+
+```bash
+npm install -g git-worktree-utils
+```
+
+## Usage
+
+### Unified CLI
+
+```bash
+wt <command> [options]
+```
+
+### Individual Commands
+
+```bash
+wt-add [options]
+wt-list
+wt-find [options]
+wt-rename [options]
+wt-remove [options]
+wt-sync-env [options]
+```
+
+## Commands
+
+### `wt add` - Create a new worktree
+
+Creates a new git worktree and automatically copies all `.env*` files from project directories.
+
+```bash
+wt add --dirName=my-feature --branchName=feature/my-feature
+wt add --dirName=bugfix-123  # uses dirName as branch name
+```
+
+**Options:**
+- `--dirName=<name>` - Directory name for the worktree (required)
+- `--branchName=<name>` - Branch name (defaults to dirName)
+
+### `wt list` (alias: `wt ls`)
+
+Lists all git worktrees.
+
+```bash
+wt list
+```
+
+### `wt find` (alias: `wt search`)
+
+Search worktrees by partial name match (case-insensitive).
+
+```bash
+wt find --search=feature
+wt find --search=FS-1234
+```
+
+### `wt rename` (alias: `wt mv`)
+
+Rename a worktree directory with safety checks.
+
+```bash
+wt rename --oldDirName=old-name --newDirName=new-name
+```
+
+**Safety checks:**
+- Blocks if uncommitted changes exist
+- Blocks if unpushed commits exist
+- Prevents renaming the main repository
+
+### `wt remove` (alias: `wt rm`)
+
+Remove a worktree with safety checks.
+
+```bash
+wt remove --dirName=old-feature
+```
+
+**Safety checks:**
+- Blocks if uncommitted changes exist
+- Blocks if unpushed commits exist
+- Prevents removing the main repository
+
+### `wt sync-env` (alias: `wt sync`)
+
+Sync `.env*` files from current worktree to other worktrees.
+
+```bash
+wt sync-env --to=other-worktree  # sync to specific worktree
+wt sync-env --all                 # sync to ALL other worktrees
+```
+
+## How .env Copying Works
+
+When creating a worktree or syncing, the tool:
+
+1. Finds all directories containing `package.json` or `project.json` (excluding `node_modules`)
+2. Copies all `.env*` files (`.env`, `.env.local`, `.env.development`, etc.) to the same relative path in the target worktree
+
+This is especially useful for monorepos where environment files are scattered across multiple projects.
+
+## Examples
+
+### Typical Workflow
+
+```bash
+# Create a new feature worktree
+wt add --dirName=my-feature --branchName=feature/awesome
+
+# ... work on the feature, add new .env variables ...
+
+# Sync your .env changes to all other worktrees
+wt sync-env --all
+
+# Find a specific worktree
+wt find --search=awesome
+
+# Clean up when done
+wt remove --dirName=my-feature
+```
+
+### Use with npm scripts
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "wt:add": "wt add",
+    "wt:list": "wt list",
+    "wt:sync": "wt sync-env --all"
+  }
+}
+```
+
+## License
+
+MIT
+
+## Author
+
+Avi Weiss

package/dist/add.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import { p as parseArgs, e as exitWithError, i as isBranchCheckedOut, g as getMainRepoRoot, c as copyEnvFiles } from "./utils-D1mQhe1g.js";
+const args = parseArgs(process.argv.slice(2));
+const dirName = args["dirName"];
+const branchName = args["branchName"];
+if (!dirName) {
+  exitWithError("Missing --dirName=...");
+}
+const branch = branchName || dirName;
+const { checkedOut, location } = isBranchCheckedOut(branch);
+if (checkedOut) {
+  console.error(`Branch '${branch}' is already checked out at:`);
+  console.error(location);
+  process.exit(1);
+}
+const targetPath = `../${dirName}`;
+try {
+  console.log(`Creating worktree at ${targetPath} for branch ${branch}...`);
+  execSync(`git worktree add ${targetPath} ${branch}`, { stdio: "inherit" });
+} catch {
+  exitWithError("Failed to create worktree");
+}
+console.log("\nCopying .env files...");
+const mainRoot = getMainRepoRoot();
+const count = copyEnvFiles(mainRoot, `../${dirName}`);
+console.log(`Done copying ${count} .env file(s)`);

package/dist/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+const args = process.argv.slice(2);
+const command = args[0];
+const commands = {
+  add: "add.js",
+  list: "list.js",
+  ls: "list.js",
+  find: "find.js",
+  search: "find.js",
+  rename: "rename.js",
+  mv: "rename.js",
+  remove: "remove.js",
+  rm: "remove.js",
+  "sync-env": "sync-env.js",
+  sync: "sync-env.js"
+};
+function showHelp() {
+  console.log(`
+git-worktree-utils - Safe git worktree management CLI
+
+Usage: wt <command> [options]
+
+Commands:
+  add         Create a new worktree (with .env file copying)
+  list, ls    List all worktrees
+  find        Search worktrees by name
+  rename, mv  Rename a worktree directory
+  remove, rm  Remove a worktree (with safety checks)
+  sync-env    Sync .env files to other worktrees
+
+Options for 'add':
+  --dirName=<name>      Directory name for the worktree (required)
+  --branchName=<name>   Branch name (defaults to dirName)
+
+Options for 'find':
+  --search=<term>       Search term (case-insensitive)
+
+Options for 'rename':
+  --oldDirName=<name>   Current directory name (required)
+  --newDirName=<name>   New directory name (required)
+
+Options for 'remove':
+  --dirName=<name>      Directory name to remove (required)
+
+Options for 'sync-env':
+  --to=<dirName>        Sync to specific worktree
+  --all                 Sync to all other worktrees
+
+Safety Features:
+  - Blocks operations on main repository
+  - Blocks remove/rename with uncommitted changes
+  - Blocks remove/rename with unpushed commits
+  - Checks if branch is already checked out elsewhere
+  - Automatically copies .env files when creating worktrees
+
+Examples:
+  wt add --dirName=my-feature --branchName=feature/my-feature
+  wt add --dirName=bugfix-123
+  wt find --search=feature
+  wt sync-env --all
+  wt remove --dirName=old-feature
+`);
+}
+if (!command || command === "help" || command === "--help" || command === "-h") {
+  showHelp();
+  process.exit(0);
+}
+const scriptFile = commands[command];
+if (!scriptFile) {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "wt help" for usage information');
+  process.exit(1);
+}
+const __dirname$1 = dirname(fileURLToPath(import.meta.url));
+const scriptPath = resolve(__dirname$1, scriptFile);
+const forwardArgs = args.slice(1).join(" ");
+try {
+  execSync(`node "${scriptPath}" ${forwardArgs}`, { stdio: "inherit" });
+} catch (error) {
+  process.exit(error.status || 1);
+}

package/dist/find.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import { p as parseArgs } from "./utils-D1mQhe1g.js";
+const args = parseArgs(process.argv.slice(2));
+const search = args["search"];
+const list = execSync("git worktree list", { encoding: "utf-8" }).trim();
+if (!search) {
+  console.log(list);
+  process.exit(0);
+}
+const lines = list.split("\n");
+const matches = lines.filter((line) => line.toLowerCase().includes(search.toLowerCase()));
+if (matches.length === 0) {
+  console.error(`No worktree found matching: ${search}`);
+  process.exit(1);
+}
+console.log(matches.join("\n"));

package/dist/list.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+const output = execSync("git worktree list", { encoding: "utf-8" });
+console.log(output.trim());

package/dist/remove.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import { existsSync, renameSync, rmSync } from "fs";
+import { join } from "path";
+import { p as parseArgs, e as exitWithError, a as isMainRepository, h as hasUncommittedChanges, b as hasUnpushedCommits } from "./utils-D1mQhe1g.js";
+const args = parseArgs(process.argv.slice(2));
+const dirName = args["dirName"];
+if (!dirName) {
+  exitWithError("Missing --dirName=...");
+}
+const path = join("..", dirName);
+if (!existsSync(path)) {
+  exitWithError(`Worktree not found: ${path}`);
+}
+if (isMainRepository(path)) {
+  exitWithError("Cannot remove: that path is the main repository");
+}
+if (hasUncommittedChanges(path)) {
+  exitWithError("Cannot remove: uncommitted changes in worktree");
+}
+if (hasUnpushedCommits(path)) {
+  exitWithError("Cannot remove: unpushed commits in worktree");
+}
+const tmpDir = `/tmp/worktree_${process.pid}`;
+renameSync(path, tmpDir);
+setImmediate(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+execSync("git worktree prune", { stdio: "inherit" });
+console.log(`Removed worktree: ${dirName}`);

package/dist/rename.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { execSync } from "child_process";
+import { existsSync, renameSync } from "fs";
+import { join } from "path";
+import { p as parseArgs, e as exitWithError, a as isMainRepository, h as hasUncommittedChanges, b as hasUnpushedCommits } from "./utils-D1mQhe1g.js";
+const args = parseArgs(process.argv.slice(2));
+const oldDirName = args["oldDirName"];
+const newDirName = args["newDirName"];
+if (!oldDirName) {
+  exitWithError("Missing --oldDirName=...");
+}
+if (!newDirName) {
+  exitWithError("Missing --newDirName=...");
+}
+const pathOld = join("..", oldDirName);
+const pathNew = join("..", newDirName);
+if (!existsSync(pathOld)) {
+  exitWithError(`Worktree not found: ${pathOld}`);
+}
+if (existsSync(pathNew)) {
+  exitWithError(`Destination already exists: ${pathNew}`);
+}
+if (isMainRepository(pathOld)) {
+  exitWithError("Cannot rename: that path is the main repository");
+}
+if (hasUncommittedChanges(pathOld)) {
+  exitWithError("Cannot rename: uncommitted changes in worktree");
+}
+if (hasUnpushedCommits(pathOld)) {
+  exitWithError("Cannot rename: unpushed commits in worktree");
+}
+renameSync(pathOld, pathNew);
+const absPathNew = execSync(`cd "${pathNew}" && pwd`, { encoding: "utf-8" }).trim();
+execSync(`git worktree repair "${absPathNew}"`, { stdio: "inherit" });
+console.log(`Renamed worktree from ${oldDirName} to ${newDirName}`);

package/dist/sync-env.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { p as parseArgs, d as getCurrentWorktreeRoot, e as exitWithError, f as getWorktreeListPaths, c as copyEnvFiles } from "./utils-D1mQhe1g.js";
+import { existsSync } from "fs";
+import { join } from "path";
+const args = parseArgs(process.argv.slice(2));
+const to = args["to"];
+const all = args["all"];
+if (!to && !all) {
+  console.log("Usage:");
+  console.log("  npm run worktree:sync-env -- --to=<dirName>   # sync to specific worktree");
+  console.log("  npm run worktree:sync-env -- --all            # sync to all other worktrees");
+  process.exit(1);
+}
+const currentRoot = getCurrentWorktreeRoot();
+let targets = [];
+if (to) {
+  const targetPath = join("..", to);
+  if (!existsSync(targetPath)) {
+    exitWithError(`Worktree not found: ${targetPath}`);
+  }
+  const absPath = require("path").resolve(targetPath);
+  targets = [absPath];
+} else if (all) {
+  targets = getWorktreeListPaths().filter((p) => p !== currentRoot);
+}
+if (targets.length === 0) {
+  console.log("No target worktrees found");
+  process.exit(0);
+}
+console.log("Syncing .env files from current worktree...\n");
+let totalCount = 0;
+for (const target of targets) {
+  console.log(`To: ${target}`);
+  const count = copyEnvFiles(currentRoot, target);
+  totalCount += count;
+  console.log("");
+}
+console.log(`Done syncing ${totalCount} .env file(s) to ${targets.length} worktree(s)`);