@junheep/gwt 0.2.2 → 0.3.0

package/README.md

@@ -82,7 +82,6 @@ Repositories without a remote use their canonical path.
 {
   "projects": {
     "github.com/owner/repository": {
-      "worktreeDirectory": ".worktrees",
       "copyFiles": [
         "apps/server/.env",
         "apps/web/.env"
@@ -114,7 +113,6 @@ The project file contains the configuration fields directly:
 ```json
 {
   "base": "origin/main",
-  "worktreeDirectory": ".worktrees",
   "copyFiles": [
     "apps/server/.env",
     "apps/web/.env"
@@ -133,12 +131,16 @@ The two files are not merged. Run `gwt config show` to see whether user and
 repository configuration is available, the location of each existing config
 file, the active source, and its resolved value.
 
-All fields are optional. Without either config, worktrees are created beneath
-`.worktrees`, use the primary worktree's current commit as their base, and run
-no setup actions.
+All fields are optional. Without either config, worktrees are created outside
+the repository beneath `~/.gwt/worktrees`. Set `GWT_HOME` to an absolute path
+to use a different gwt home directory. A repository normally uses a directory
+named after it. If another repository already uses that name, gwt adds a short
+hash derived from the canonical path. Worktrees use the primary worktree's
+current commit as their base and run no setup actions.
 
 - `base`: Git revision used when `--base` is omitted.
-- `worktreeDirectory`: Repository-relative directory for managed worktrees.
+- `worktreeDirectory`: Optional repository-relative directory for managed
+  worktrees. Setting it opts out of the external default.
 - `copyFiles`: Ignored local files copied from the primary worktree without
   overwriting an existing destination.
 - `ports`: Environment variable names assigned stable ports in the range
@@ -146,8 +148,17 @@ no setup actions.
 - `postCreate`: Executable run after files and ports are prepared.
 - `preRemove`: Executable run before removal.
 
-The worktree directory is added to `.git/info/exclude`; tracked project files
-are not modified.
+An explicitly configured repository-relative worktree directory is added to
+`.git/info/exclude`; tracked project files are not modified.
+
+For example, an existing configuration can retain the previous in-repository
+layout explicitly:
+
+```json
+{
+  "worktreeDirectory": ".worktrees"
+}
+```
 
 ## Hooks
 
@@ -192,8 +203,8 @@ Approval is invalidated when `.gwt.json` or either hook changes.
 gwt new [branch] [--base <ref>] [--no-hooks]
 gwt setup [id|branch|path] [--no-hooks]
 gwt list
-gwt switch [id|branch|path]
-gwt info [id|branch|path]
+gwt switch [primary|id|branch|path]
+gwt info [primary|id|branch|path]
 gwt remove [id|branch|path] [--keep-branch|--discard] [--yes] [--no-hooks]
 gwt trust [--revoke]
 gwt config create [--project]
@@ -216,7 +227,9 @@ Setup failures retain the worktree and record the failure. Retry with
 Run `gwt switch` without a target to open the interactive picker. Use the
 arrow keys, `j`/`k`, or Ctrl-n/Ctrl-p to move; press `/` to filter by branch,
 ID, or path. Enter switches to the selected worktree. Escape leaves filter
-mode or cancels the picker.
+mode or cancels the picker. `primary` is a reserved ID for the repository's
+primary worktree, so `gwt switch primary` returns to it from any linked
+worktree.
 
 `gwt remove` refuses dirty worktrees and first tries to delete the branch with
 `git branch -d`. If Git rejects safe deletion, an interactive terminal asks

package/bin/gwt.mjs

@@ -19,7 +19,7 @@ import {
 } from "node:fs"
 import { createServer } from "node:net"
 import { homedir } from "node:os"
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { emitKeypressEvents } from "node:readline"
 import { createInterface } from "node:readline/promises"
 
@@ -28,7 +28,7 @@ const PORT_MIN = 20_000
 const PORT_MAX = 39_999
 const PICKER_ESCAPE_CODE_TIMEOUT_MS = 50
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
-const DEFAULT_CONFIG = { worktreeDirectory: ".worktrees", copyFiles: [], ports: [] }
+const DEFAULT_CONFIG = { copyFiles: [], ports: [] }
 const SKILL_DIRECTORIES = { claude: ".claude", codex: ".agents" }
 const SKILL_USAGE = `Usage: gwt skill install <${Object.keys(SKILL_DIRECTORIES).join("|")}> [--project] [--dry-run] [--yes]`
 
@@ -136,9 +136,12 @@ function validateConfig(parsed, label) {
     throw new CliError("base must be a non-empty string")
   }
 
-  const worktreeDirectory = validateRelativePath(parsed.worktreeDirectory ?? ".worktrees", "worktreeDirectory")
-  if (worktreeDirectory.split(/[\\/]+/).some((part) => !/^[A-Za-z0-9._-]+$/.test(part))) {
-    throw new CliError("worktreeDirectory can only contain letters, digits, '.', '_', '-', and path separators")
+  let worktreeDirectory
+  if (parsed.worktreeDirectory !== undefined) {
+    worktreeDirectory = validateRelativePath(parsed.worktreeDirectory, "worktreeDirectory")
+    if (worktreeDirectory.split(/[\\/]+/).some((part) => !/^[A-Za-z0-9._-]+$/.test(part))) {
+      throw new CliError("worktreeDirectory can only contain letters, digits, '.', '_', '-', and path separators")
+    }
   }
   if (!Array.isArray(parsed.copyFiles ?? [])) throw new CliError("copyFiles must be an array")
   const copyFiles = (parsed.copyFiles ?? []).map((path, index) => validateRelativePath(path, `copyFiles[${index}]`))
@@ -156,18 +159,61 @@ function validateConfig(parsed, label) {
     if (parsed[hook] !== undefined) validateRelativePath(parsed[hook], hook)
   }
 
-  return {
+  const config = {
     ...parsed,
-    worktreeDirectory,
     copyFiles,
     ports,
   }
+  if (worktreeDirectory !== undefined) config.worktreeDirectory = worktreeDirectory
+  return config
 }
 
 function configHome() {
   return process.env.XDG_CONFIG_HOME || join(homedir(), ".config")
 }
 
+function gwtHome() {
+  const path = process.env.GWT_HOME || join(homedir(), ".gwt")
+  if (!isAbsolute(path)) throw new CliError("GWT_HOME must be an absolute path")
+  return path
+}
+
+function repositoryUsesDirectory(repository, directory) {
+  const resolvedDirectory = pathExists(directory) ? canonical(directory) : resolve(directory)
+  return repository.worktrees.some((worktree) => {
+    if (!pathExists(worktree.path)) return false
+    const worktreePath = canonical(worktree.path)
+    return worktreePath !== repository.primaryPath && dirname(worktreePath) === resolvedDirectory
+  })
+}
+
+function directoryIsEmpty(path) {
+  try {
+    return statSync(path).isDirectory() && readdirSync(path).length === 0
+  } catch {
+    return false
+  }
+}
+
+function defaultWorktreeDirectory(repository) {
+  const root = join(gwtHome(), "worktrees")
+  const name = basename(repository.primaryPath)
+  const namedDirectory = join(root, name)
+  const digest = createHash("sha256").update(repository.primaryPath).digest("hex").slice(0, 8)
+  const disambiguatedDirectory = join(root, `${name}-${digest}`)
+
+  if (repositoryUsesDirectory(repository, disambiguatedDirectory)) return disambiguatedDirectory
+  if (repositoryUsesDirectory(repository, namedDirectory)) return namedDirectory
+  if (!pathExists(namedDirectory) || directoryIsEmpty(namedDirectory)) return namedDirectory
+  return disambiguatedDirectory
+}
+
+function resolveWorktreeDirectory(repository, config) {
+  return config.worktreeDirectory
+    ? resolve(repository.primaryPath, config.worktreeDirectory)
+    : defaultWorktreeDirectory(repository)
+}
+
 function userConfigPath() {
   return join(configHome(), "gwt", "config.json")
 }
@@ -311,6 +357,8 @@ function resolveWorktree(repository, selector, options = {}) {
     return current
   }
 
+  if (selector === "primary") return repository.primary
+
   const metadata = loadMetadata(repository)
   const idMatch = metadata.find((item) => item.id === selector)
   if (idMatch) {
@@ -330,9 +378,10 @@ function resolveWorktree(repository, selector, options = {}) {
 }
 
 function generateId(repository, config) {
+  const directory = resolveWorktreeDirectory(repository, config)
   for (let attempt = 0; attempt < 100; attempt += 1) {
     const id = randomBytes(4).toString("hex")
-    const target = join(repository.primaryPath, config.worktreeDirectory, id)
+    const target = join(directory, id)
     if (!existsSync(metadataPath(repository, id)) && !pathExists(target)) return id
   }
   throw new CliError("Could not generate a unique worktree ID")
@@ -632,24 +681,27 @@ async function commandNew(args) {
   const base = requestedBase
     ? gitOutput(["rev-parse", "--verify", `${requestedBase}^{commit}`], repository.primaryPath)
     : gitOutput(["rev-parse", "HEAD"], repository.primaryPath)
-  const target = join(repository.primaryPath, configDocument.value.worktreeDirectory, id)
-  ensureLocalExclude(repository, configDocument.value.worktreeDirectory)
+  const target = join(resolveWorktreeDirectory(repository, configDocument.value), id)
+  if (configDocument.value.worktreeDirectory) {
+    ensureLocalExclude(repository, configDocument.value.worktreeDirectory)
+  }
 
   git(["worktree", "add", "-b", branch, target, base], repository.primaryPath, { stdio: "inherit" })
+  const targetPath = canonical(target)
   const refreshed = discoverRepository(repository.primaryPath)
-  const worktree = refreshed.worktrees.find((item) => resolve(item.path) === resolve(target))
+  const worktree = refreshed.worktrees.find((item) => resolve(item.path) === targetPath)
 
   try {
     const metadata = await setupWorktree(refreshed, configDocument, worktree, {
       id,
       noHooks: options["no-hooks"],
     })
-    console.log(`Worktree ${metadata.id} is ready at ${target}`)
+    console.log(`Worktree ${metadata.id} is ready at ${targetPath}`)
     console.log(`Branch: ${branch}`)
     for (const [name, port] of Object.entries(metadata.ports)) console.log(`${name}: ${port}`)
-    writeCdDirective(target)
+    writeCdDirective(targetPath)
   } catch (error) {
-    console.error(`Setup failed; worktree retained at ${target}`)
+    console.error(`Setup failed; worktree retained at ${targetPath}`)
     console.error(`Retry: gwt setup ${id}`)
     console.error(`Remove: gwt remove ${id}`)
     throw error
@@ -806,7 +858,7 @@ async function chooseWorktree(repository) {
 }
 
 async function commandSwitch(args) {
-  if (args.length > 1) throw new CliError("Usage: gwt switch [id|branch|path]")
+  if (args.length > 1) throw new CliError("Usage: gwt switch [primary|id|branch|path]")
   const repository = discoverRepository()
   const worktree = args[0] ? resolveWorktree(repository, args[0]) : await chooseWorktree(repository)
   writeCdDirective(canonical(worktree.path))
@@ -911,7 +963,7 @@ function commandList(args) {
 }
 
 function commandInfo(args) {
-  if (args.length > 1) throw new CliError("Usage: gwt info [id|branch|path]")
+  if (args.length > 1) throw new CliError("Usage: gwt info [primary|id|branch|path]")
   const repository = discoverRepository()
   const worktree = resolveWorktree(repository, args[0])
   const metadata = metadataForWorktree(repository, worktree)
@@ -1024,7 +1076,7 @@ function commandTrust(args) {
 }
 
 function configScaffold() {
-  return { worktreeDirectory: ".worktrees", copyFiles: [], ports: [] }
+  return { copyFiles: [], ports: [] }
 }
 
 function commandConfigCreate(args) {
@@ -1079,6 +1131,7 @@ function commandConfigShow(args) {
   console.log(`Repository config: ${repositoryConfigured ? "configured" : "not created"}`)
   if (repositoryConfigured) console.log(`  File: ${projectPath}`)
   console.log(`Active config: ${activeLabel}`)
+  console.log(`Worktree directory: ${resolveWorktreeDirectory(repository, active.value)}`)
   console.log(JSON.stringify(active.value, null, 2))
 }
 
@@ -1332,7 +1385,7 @@ function commandComplete(args) {
 
   if (args[0] === "worktrees") {
     const repository = discoverRepository()
-    const values = []
+    const values = ["primary"]
     for (const worktree of repository.worktrees) {
       const metadata = metadataForWorktree(repository, worktree)
       if (metadata?.id) values.push(metadata.id)
@@ -1411,10 +1464,13 @@ Options:
 
 Behavior:
   The worktree receives an immutable 8-character ID. gwt creates it below the
-  configured worktreeDirectory, copies configured local files, assigns stable
+  resolved worktree directory, copies configured local files, assigns stable
   ports, and runs postCreate. A setup failure keeps the worktree so setup can
   be retried. With shell integration installed, the current shell moves into
-  the new worktree after setup succeeds.
+  the new worktree after setup succeeds. Without worktreeDirectory, the default
+  is $GWT_HOME/worktrees or ~/.gwt/worktrees when GWT_HOME is not set. A short
+  repository hash is added to the directory name only when needed to avoid a
+  name collision.
 
 Examples:
   gwt new feature/auth
@@ -1457,36 +1513,40 @@ Example:
     switch: `Switch the current shell to another worktree.
 
 Usage:
-  gwt switch [id|branch|path]
+  gwt switch [primary|id|branch|path]
 
 Arguments:
-  id|branch|path  Worktree to switch to. Opens the picker when omitted.
+  selector        Worktree to switch to. Opens the picker when omitted.
 
 Options:
   -h, --help      Show help for this command.
 
 Behavior:
-  The picker supports arrow keys, j/k, Ctrl-n/Ctrl-p, and '/' filtering. Shell
-  integration must be installed for gwt to change the parent shell's directory;
-  otherwise the selected path is only printed.
+  'primary' is the reserved ID for the primary worktree. Other worktrees can be
+  selected by ID, exact branch name, or path. The picker supports arrow keys,
+  j/k, Ctrl-n/Ctrl-p, and '/' filtering. Shell integration must be installed for
+  gwt to change the parent shell's directory; otherwise the path is only printed.
 
 Examples:
   gwt switch
+  gwt switch primary
   gwt switch feature/auth
   gwt switch a1b2c3d4`,
     info: `Show a worktree's identity, Git state, setup status, and assigned ports.
 
 Usage:
-  gwt info [id|branch|path]
+  gwt info [primary|id|branch|path]
 
 Arguments:
-  id|branch|path  Worktree to inspect. Defaults to the current worktree.
+  selector        'primary', an ID, an exact branch name, or a path. Defaults
+                  to the current worktree.
 
 Options:
   -h, --help      Show help for this command.
 
 Examples:
   gwt info
+  gwt info primary
   gwt info feature/auth`,
     remove: `Safely remove a linked worktree and, by default, its branch.
 
@@ -1579,8 +1639,8 @@ Options:
   -h, --help      Show help for this command.
 
 The output distinguishes a missing user config file from an existing file that
-does not configure the current project. Repository configuration takes
-precedence over user configuration.
+does not configure the current project. It also shows the resolved worktree
+directory. Repository configuration takes precedence over user configuration.
 
 Example:
   gwt config show`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junheep/gwt",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Lightweight native Git worktree workflows",
   "license": "MIT",
   "author": "Junhee Park",