dotswitch 1.0.0 → 1.1.1

package/README.md

@@ -4,7 +4,10 @@
 
 [![CI](https://github.com/natterstefan/dotswitch/actions/workflows/ci.yml/badge.svg)](https://github.com/natterstefan/dotswitch/actions/workflows/ci.yml)
 
-Quickly switch between `.env` files. Copies `.env.<environment>` to `.env.local` (or a custom target) and tracks the active environment via a header comment. Works with Next.js, Vite, Remix, and any project that uses `.env` files.
+Quickly switch between `.env` files. Copies
+`.env.<environment>` to `.env.local` (or a custom target) and
+tracks the active environment via a header comment. Works with
+Next.js, Vite, Remix, and any project that uses `.env` files.
 
 ## Install
 
@@ -121,7 +124,9 @@ All commands support:
 
 ## Configuration
 
-Create a `.dotswitchrc.json` in your project root to customize behavior. Everything is optional — dotswitch works out of the box without a config file.
+Create a `.dotswitchrc.json` in your project root to customize
+behavior. Everything is optional — dotswitch works out of the
+box without a config file.
 
 ```json
 {
@@ -143,7 +148,9 @@ Create a `.dotswitchrc.json` in your project root to customize behavior. Everyth
 
 ### Custom target file
 
-By default dotswitch writes to `.env.local`, but some frameworks use `.env` directly. Set the `target` field to change this:
+By default dotswitch writes to `.env.local`, but some
+frameworks use `.env` directly. Set the `target` field to
+change this:
 
 ```json
 {
@@ -175,7 +182,8 @@ Automatically switch environments when you check out a branch.
 dotswitch hook install
 ```
 
-Now `git checkout staging/feat-login` will automatically run `dotswitch use staging`.
+Now `git checkout staging/feat-login` will automatically run
+`dotswitch use staging`.
 
 ### Patterns
 
@@ -203,6 +211,29 @@ dotswitch ls --path "./packages/*"
 
 Each directory is processed independently with labeled output.
 
+## Git worktree support
+
+dotswitch works transparently in
+[git worktrees](https://git-scm.com/docs/git-worktree). When
+you run any command from a worktree, it automatically resolves
+back to the main repo where your `.env.*` files and
+`.dotswitchrc.json` live.
+
+```bash
+# From a worktree, all commands operate on the main repo
+cd /path/to/my-worktree
+dotswitch ls          # lists envs from the main repo
+dotswitch use staging # switches in the main repo
+dotswitch hook install # installs hook in the shared .git/hooks
+```
+
+Explicit `--path` arguments are rebased automatically, so
+monorepo globs also work from worktrees:
+
+```bash
+dotswitch use staging --path "./apps/*"
+```
+
 ## How it works
 
 When you run `dotswitch use staging`, it:
@@ -211,7 +242,8 @@ When you run `dotswitch use staging`, it:
 2. Copies `.env.staging` to `.env.local`
 3. Prepends a `# dotswitch:staging` header to track the active environment
 
-The header comment is how `dotswitch ls` and `dotswitch current` know which environment is active.
+The header comment is how `dotswitch ls` and
+`dotswitch current` know which environment is active.
 
 ## Programmatic API
 
@@ -226,6 +258,7 @@ import {
   loadConfig,
   parseEnvContent,
   diffEnvMaps,
+  resolveProjectRoot,
 } from "dotswitch";
 
 const files = listEnvFiles(process.cwd());
@@ -233,6 +266,14 @@ const active = getActiveEnv(process.cwd());
 switchEnv(process.cwd(), "staging", { backup: true });
 ```
 
+In worktree-aware scripts, resolve the project root first:
+
+```ts
+const projectRoot = resolveProjectRoot(process.cwd());
+const files = listEnvFiles(projectRoot);
+switchEnv(projectRoot, "staging", { backup: true });
+```
+
 ## Requirements
 
 - Node.js >= 20

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { Command } from "commander";
 import fs from "node:fs";
 import path from "node:path";
+import { Command } from "commander";
 import pc from "picocolors";
 import select from "@inquirer/select";
+import { execFileSync } from "node:child_process";
 
 //#region src/lib/constants.ts
 const ENV_LOCAL = ".env.local";
@@ -54,7 +55,7 @@ const logger = {
 		console.log(pc.cyan(message));
 	},
 	warn(message) {
-		console.log(pc.yellow(`⚠ ${message}`));
+		console.error(pc.yellow(`⚠ ${message}`));
 	},
 	error(message) {
 		console.error(pc.red(`✗ ${message}`));
@@ -421,6 +422,66 @@ function diffCommand(env1, env2, options) {
 	}
 }
 
+//#endregion
+//#region src/lib/git.ts
+function git(dir, ...args) {
+	try {
+		return execFileSync("git", [
+			"-C",
+			dir,
+			...args
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		}).trim();
+	} catch (error) {
+		const stderr = error instanceof Error && "stderr" in error ? String(error.stderr).trim() : "";
+		if (stderr) logger.warn(`git ${args.join(" ")}: ${stderr}`);
+		return null;
+	}
+}
+/**
+* Resolve the common (shared) git directory for a project.
+* - Regular repos: returns <dir>/.git
+* - Worktrees: returns the main repo's .git directory
+* - Non-git directories: returns null
+*/
+function resolveCommonGitDir(dir) {
+	const gitPath = path.join(dir, ".git");
+	try {
+		if (fs.statSync(gitPath).isDirectory()) return gitPath;
+	} catch {
+		return null;
+	}
+	const result = git(dir, "rev-parse", "--git-common-dir");
+	if (!result) return null;
+	return path.isAbsolute(result) ? result : path.resolve(dir, result);
+}
+/**
+* Resolve the project root directory.
+* In a worktree, this returns the main repo's root (parent of its .git dir).
+* Otherwise returns the given directory as-is.
+*/
+function resolveProjectRoot(dir) {
+	const gitPath = path.join(dir, ".git");
+	let stats;
+	try {
+		stats = fs.statSync(gitPath);
+	} catch {
+		return dir;
+	}
+	if (stats.isDirectory()) return dir;
+	if (stats.isFile()) {
+		const commonGitDir = resolveCommonGitDir(dir);
+		if (commonGitDir) return path.dirname(commonGitDir);
+	}
+	return dir;
+}
+
 //#endregion
 //#region src/lib/hooks.ts
 const HOOK_FILENAME = "post-checkout";
@@ -436,8 +497,8 @@ fi
 ${HOOK_MARKER_END}`;
 }
 function getHooksDir(dir) {
-	const gitDir = path.join(dir, ".git");
-	if (!fs.existsSync(gitDir)) return null;
+	const gitDir = resolveCommonGitDir(dir);
+	if (!gitDir) return null;
 	return path.join(gitDir, "hooks");
 }
 function installHook(dir) {
@@ -537,48 +598,79 @@ function hookBranchCommand(branch, options) {
 //#endregion
 //#region src/cli.ts
 const pkg = createRequire(import.meta.url)("../package.json");
+/**
+* Check whether a directory contains any `.env.*` source files
+* (i.e. files that dotswitch would operate on, excluding standard non-source files).
+*/
+function hasEnvFiles(dir) {
+	try {
+		return fs.readdirSync(dir).some((name) => name.startsWith(".env.") && !EXCLUDED_ENV_FILES.has(name));
+	} catch {
+		return false;
+	}
+}
+/**
+* Resolve the effective path for a command.
+* - No --path given: if in a worktree with local env files, operate locally;
+*   otherwise resolve to the main repo root.
+* - Explicit --path: rebase it relative to the main repo when in a worktree,
+*   so glob patterns like "./apps/*" expand against the main repo.
+*/
+function resolveCommandPath(explicitPath) {
+	const cwd = process.cwd();
+	const projectRoot = resolveProjectRoot(cwd);
+	if (!explicitPath) {
+		if (projectRoot !== cwd && hasEnvFiles(cwd)) return cwd;
+		return projectRoot;
+	}
+	if (projectRoot === cwd) return explicitPath;
+	const absolute = path.resolve(explicitPath);
+	const relative = path.relative(cwd, absolute);
+	return path.resolve(projectRoot, relative);
+}
 const program = new Command();
 program.name("dotswitch").description("Quickly switch between .env files").version(pkg.version);
-program.command("use [env]").description("Switch to a .env.<env> file (interactive if no env given)").option("-f, --force", "skip confirmation if already active", false).option("--no-backup", "skip .env.local backup").option("-n, --dry-run", "show what would happen without making changes", false).option("-p, --path <dir>", "project directory", process.cwd()).option("--hook-branch <branch>", "internal: auto-switch by branch name").action(async (env, opts) => {
+program.command("use [env]").description("Switch to a .env.<env> file (interactive if no env given)").option("-f, --force", "skip confirmation if already active", false).option("--no-backup", "skip .env.local backup").option("-n, --dry-run", "show what would happen without making changes", false).option("-p, --path <dir>", "project directory").option("--hook-branch <branch>", "internal: auto-switch by branch name").action(async (env, opts) => {
+	const projectPath = resolveCommandPath(opts.path);
 	if (opts.hookBranch) {
-		hookBranchCommand(opts.hookBranch, { path: opts.path });
+		hookBranchCommand(opts.hookBranch, { path: projectPath });
 		return;
 	}
 	await useCommand(env, {
 		force: opts.force,
 		backup: opts.backup,
 		dryRun: opts.dryRun,
-		path: opts.path
+		path: projectPath
 	});
 });
-program.command("ls").description("List available .env.* files").option("-p, --path <dir>", "project directory", process.cwd()).option("--json", "output as JSON", false).action((opts) => {
+program.command("ls").description("List available .env.* files").option("-p, --path <dir>", "project directory").option("--json", "output as JSON", false).action((opts) => {
 	lsCommand({
-		path: opts.path,
+		path: resolveCommandPath(opts.path),
 		json: opts.json
 	});
 });
-program.command("current").description("Show the currently active environment").option("-p, --path <dir>", "project directory", process.cwd()).option("--json", "output as JSON", false).action((opts) => {
+program.command("current").description("Show the currently active environment").option("-p, --path <dir>", "project directory").option("--json", "output as JSON", false).action((opts) => {
 	currentCommand({
-		path: opts.path,
+		path: resolveCommandPath(opts.path),
 		json: opts.json
 	});
 });
-program.command("restore").description("Restore .env.local from the backup file").option("-p, --path <dir>", "project directory", process.cwd()).action((opts) => {
-	restoreCommand({ path: opts.path });
+program.command("restore").description("Restore .env.local from the backup file").option("-p, --path <dir>", "project directory").action((opts) => {
+	restoreCommand({ path: resolveCommandPath(opts.path) });
 });
-program.command("diff <env1> [env2]").description("Compare keys between two env files (defaults: .env.local vs env1)").option("-p, --path <dir>", "project directory", process.cwd()).option("--show-values", "show actual values in the diff", false).option("--json", "output as JSON", false).action((env1, env2, opts) => {
+program.command("diff <env1> [env2]").description("Compare keys between two env files (defaults: .env.local vs env1)").option("-p, --path <dir>", "project directory").option("--show-values", "show actual values in the diff", false).option("--json", "output as JSON", false).action((env1, env2, opts) => {
 	diffCommand(env1, env2, {
-		path: opts.path,
+		path: resolveCommandPath(opts.path),
 		showValues: opts.showValues,
 		json: opts.json
 	});
 });
 const hookCmd = program.command("hook").description("Manage git post-checkout hook for auto-switching");
-hookCmd.command("install").description("Install the post-checkout git hook").option("-p, --path <dir>", "project directory", process.cwd()).action((opts) => {
-	hookInstallCommand({ path: opts.path });
+hookCmd.command("install").description("Install the post-checkout git hook").option("-p, --path <dir>", "project directory").action((opts) => {
+	hookInstallCommand({ path: resolveCommandPath(opts.path) });
 });
-hookCmd.command("remove").description("Remove the post-checkout git hook").option("-p, --path <dir>", "project directory", process.cwd()).action((opts) => {
-	hookRemoveCommand({ path: opts.path });
+hookCmd.command("remove").description("Remove the post-checkout git hook").option("-p, --path <dir>", "project directory").action((opts) => {
+	hookRemoveCommand({ path: resolveCommandPath(opts.path) });
 });
 program.parse();
 

package/dist/index.cjs

@@ -32,6 +32,7 @@ let node_path = require("node:path");
 node_path = __toESM(node_path);
 let picocolors = require("picocolors");
 picocolors = __toESM(picocolors);
+let node_child_process = require("node:child_process");
 
 //#region src/lib/constants.ts
 const TRACKER_PREFIX = "# dotswitch:";
@@ -80,7 +81,7 @@ const logger = {
 		console.log(picocolors.default.cyan(message));
 	},
 	warn(message) {
-		console.log(picocolors.default.yellow(`⚠ ${message}`));
+		console.error(picocolors.default.yellow(`⚠ ${message}`));
 	},
 	error(message) {
 		console.error(picocolors.default.red(`✗ ${message}`));
@@ -229,6 +230,66 @@ function diffEnvMaps(from, to) {
 	};
 }
 
+//#endregion
+//#region src/lib/git.ts
+function git(dir, ...args) {
+	try {
+		return (0, node_child_process.execFileSync)("git", [
+			"-C",
+			dir,
+			...args
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		}).trim();
+	} catch (error) {
+		const stderr = error instanceof Error && "stderr" in error ? String(error.stderr).trim() : "";
+		if (stderr) logger.warn(`git ${args.join(" ")}: ${stderr}`);
+		return null;
+	}
+}
+/**
+* Resolve the common (shared) git directory for a project.
+* - Regular repos: returns <dir>/.git
+* - Worktrees: returns the main repo's .git directory
+* - Non-git directories: returns null
+*/
+function resolveCommonGitDir(dir) {
+	const gitPath = node_path.default.join(dir, ".git");
+	try {
+		if (node_fs.default.statSync(gitPath).isDirectory()) return gitPath;
+	} catch {
+		return null;
+	}
+	const result = git(dir, "rev-parse", "--git-common-dir");
+	if (!result) return null;
+	return node_path.default.isAbsolute(result) ? result : node_path.default.resolve(dir, result);
+}
+/**
+* Resolve the project root directory.
+* In a worktree, this returns the main repo's root (parent of its .git dir).
+* Otherwise returns the given directory as-is.
+*/
+function resolveProjectRoot(dir) {
+	const gitPath = node_path.default.join(dir, ".git");
+	let stats;
+	try {
+		stats = node_fs.default.statSync(gitPath);
+	} catch {
+		return dir;
+	}
+	if (stats.isDirectory()) return dir;
+	if (stats.isFile()) {
+		const commonGitDir = resolveCommonGitDir(dir);
+		if (commonGitDir) return node_path.default.dirname(commonGitDir);
+	}
+	return dir;
+}
+
 //#endregion
 exports.addTrackerHeader = addTrackerHeader;
 exports.backupEnvLocal = backupEnvLocal;
@@ -242,5 +303,7 @@ exports.loadConfig = loadConfig;
 exports.parseEnvContent = parseEnvContent;
 exports.parseTrackerHeader = parseTrackerHeader;
 exports.removeTrackerHeader = removeTrackerHeader;
+exports.resolveCommonGitDir = resolveCommonGitDir;
+exports.resolveProjectRoot = resolveProjectRoot;
 exports.restoreEnvLocal = restoreEnvLocal;
 exports.switchEnv = switchEnv;

package/dist/index.d.cts

@@ -66,4 +66,19 @@ interface EnvDiff {
 */
 declare function diffEnvMaps(from: Map<string, string>, to: Map<string, string>): EnvDiff;
 //#endregion
-export { type CommonOptions, type DotswitchConfig, type EnvDiff, type EnvFile, type UseOptions, addTrackerHeader, backupEnvLocal, createTrackerHeader, diffEnvMaps, getActiveEnv, getBackupFile, getTargetFile, listEnvFiles, loadConfig, parseEnvContent, parseTrackerHeader, removeTrackerHeader, restoreEnvLocal, switchEnv };
+//#region src/lib/git.d.ts
+/**
+* Resolve the common (shared) git directory for a project.
+* - Regular repos: returns <dir>/.git
+* - Worktrees: returns the main repo's .git directory
+* - Non-git directories: returns null
+*/
+declare function resolveCommonGitDir(dir: string): string | null;
+/**
+* Resolve the project root directory.
+* In a worktree, this returns the main repo's root (parent of its .git dir).
+* Otherwise returns the given directory as-is.
+*/
+declare function resolveProjectRoot(dir: string): string;
+//#endregion
+export { type CommonOptions, type DotswitchConfig, type EnvDiff, type EnvFile, type UseOptions, addTrackerHeader, backupEnvLocal, createTrackerHeader, diffEnvMaps, getActiveEnv, getBackupFile, getTargetFile, listEnvFiles, loadConfig, parseEnvContent, parseTrackerHeader, removeTrackerHeader, resolveCommonGitDir, resolveProjectRoot, restoreEnvLocal, switchEnv };

package/dist/index.d.mts

@@ -66,4 +66,19 @@ interface EnvDiff {
 */
 declare function diffEnvMaps(from: Map<string, string>, to: Map<string, string>): EnvDiff;
 //#endregion
-export { type CommonOptions, type DotswitchConfig, type EnvDiff, type EnvFile, type UseOptions, addTrackerHeader, backupEnvLocal, createTrackerHeader, diffEnvMaps, getActiveEnv, getBackupFile, getTargetFile, listEnvFiles, loadConfig, parseEnvContent, parseTrackerHeader, removeTrackerHeader, restoreEnvLocal, switchEnv };
+//#region src/lib/git.d.ts
+/**
+* Resolve the common (shared) git directory for a project.
+* - Regular repos: returns <dir>/.git
+* - Worktrees: returns the main repo's .git directory
+* - Non-git directories: returns null
+*/
+declare function resolveCommonGitDir(dir: string): string | null;
+/**
+* Resolve the project root directory.
+* In a worktree, this returns the main repo's root (parent of its .git dir).
+* Otherwise returns the given directory as-is.
+*/
+declare function resolveProjectRoot(dir: string): string;
+//#endregion
+export { type CommonOptions, type DotswitchConfig, type EnvDiff, type EnvFile, type UseOptions, addTrackerHeader, backupEnvLocal, createTrackerHeader, diffEnvMaps, getActiveEnv, getBackupFile, getTargetFile, listEnvFiles, loadConfig, parseEnvContent, parseTrackerHeader, removeTrackerHeader, resolveCommonGitDir, resolveProjectRoot, restoreEnvLocal, switchEnv };

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
+import { execFileSync } from "node:child_process";
 
 //#region src/lib/constants.ts
 const TRACKER_PREFIX = "# dotswitch:";
@@ -49,7 +50,7 @@ const logger = {
 		console.log(pc.cyan(message));
 	},
 	warn(message) {
-		console.log(pc.yellow(`⚠ ${message}`));
+		console.error(pc.yellow(`⚠ ${message}`));
 	},
 	error(message) {
 		console.error(pc.red(`✗ ${message}`));
@@ -199,4 +200,64 @@ function diffEnvMaps(from, to) {
 }
 
 //#endregion
-export { addTrackerHeader, backupEnvLocal, createTrackerHeader, diffEnvMaps, getActiveEnv, getBackupFile, getTargetFile, listEnvFiles, loadConfig, parseEnvContent, parseTrackerHeader, removeTrackerHeader, restoreEnvLocal, switchEnv };
+//#region src/lib/git.ts
+function git(dir, ...args) {
+	try {
+		return execFileSync("git", [
+			"-C",
+			dir,
+			...args
+		], {
+			encoding: "utf-8",
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		}).trim();
+	} catch (error) {
+		const stderr = error instanceof Error && "stderr" in error ? String(error.stderr).trim() : "";
+		if (stderr) logger.warn(`git ${args.join(" ")}: ${stderr}`);
+		return null;
+	}
+}
+/**
+* Resolve the common (shared) git directory for a project.
+* - Regular repos: returns <dir>/.git
+* - Worktrees: returns the main repo's .git directory
+* - Non-git directories: returns null
+*/
+function resolveCommonGitDir(dir) {
+	const gitPath = path.join(dir, ".git");
+	try {
+		if (fs.statSync(gitPath).isDirectory()) return gitPath;
+	} catch {
+		return null;
+	}
+	const result = git(dir, "rev-parse", "--git-common-dir");
+	if (!result) return null;
+	return path.isAbsolute(result) ? result : path.resolve(dir, result);
+}
+/**
+* Resolve the project root directory.
+* In a worktree, this returns the main repo's root (parent of its .git dir).
+* Otherwise returns the given directory as-is.
+*/
+function resolveProjectRoot(dir) {
+	const gitPath = path.join(dir, ".git");
+	let stats;
+	try {
+		stats = fs.statSync(gitPath);
+	} catch {
+		return dir;
+	}
+	if (stats.isDirectory()) return dir;
+	if (stats.isFile()) {
+		const commonGitDir = resolveCommonGitDir(dir);
+		if (commonGitDir) return path.dirname(commonGitDir);
+	}
+	return dir;
+}
+
+//#endregion
+export { addTrackerHeader, backupEnvLocal, createTrackerHeader, diffEnvMaps, getActiveEnv, getBackupFile, getTargetFile, listEnvFiles, loadConfig, parseEnvContent, parseTrackerHeader, removeTrackerHeader, resolveCommonGitDir, resolveProjectRoot, restoreEnvLocal, switchEnv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotswitch",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Quickly switch between .env files",
   "type": "module",
   "bin": {