oh-my-space 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # oh-my-space
 
-`oh-my-space` provides the `oms` CLI for managing external source repositories declared in `sources.yaml`. Each registered repo lives as a bare clone under `sources/<alias>/.bare/` and the baseline branch (and any additional ones you ask for) checks out as a Git worktree at `sources/<alias>/<branch>/`.
+`oh-my-space` provides the `oms` CLI for managing external source repositories declared in `oms.yaml`. Each registered repo lives as a bare clone under `oms/<alias>/.bare/` and the baseline branch (and any additional ones you ask for) checks out as a Git worktree at `oms/<alias>/<branch>/`.
 
 Package name: `oh-my-space`
 
@@ -32,7 +32,7 @@ bun install -g oh-my-space
 
 ## Quick start
 
-Create a `sources.yaml` in your project root:
+Create an `oms.yaml` in your project root:
 
 ```yaml
 repos:
@@ -46,7 +46,7 @@ repos:
 Sync and explore:
 
 ```bash
-oms doctor                         # validate sources.yaml + bare/worktree state
+oms doctor                         # validate oms.yaml + bare/worktree state
 oms sync --list                    # list registered source repos
 oms sync <alias>...                # bare-clone + create the baseline worktree
 oms sync --all                     # sync every registered source repo
@@ -57,14 +57,14 @@ oms worktree remove <alias> <br>   # remove a single worktree
 oms unsync <alias>...              # remove ALL worktrees + the bare clone
 ```
 
-`oms sync` adds `sources/` to your workspace `.gitignore` on first run; the bare clone and worktrees stay out of your project history.
+`oms sync` adds `oms/` to your workspace `.gitignore` on first run; the bare clone and worktrees stay out of your project history.
 
 ## Layout
 
 For an alias `api` with the baseline branch `main` and an extra `feature/foo` worktree:
 
 ```
-sources/
+oms/
 └── api/
     ├── .bare/             # git clone --bare result
     ├── .git               # 'gitdir: ./.bare' placeholder
@@ -77,13 +77,13 @@ Slash-containing branch names are kept nested as directories.
 
 ## Managing source repositories
 
-`sources.yaml` declares each source repo with `alias`, `url`, and optional `branch` (the baseline). Additional worktrees are created on demand with `oms worktree add` and are *not* persisted in `sources.yaml` — they're treated as per-machine working space.
+`oms.yaml` declares each source repo with `alias`, `url`, and optional `branch` (the baseline). Additional worktrees are created on demand with `oms worktree add` and are *not* persisted in `oms.yaml` — they're treated as per-machine working space.
 
 | Command | Runs in | Does | Notes |
 | --- | --- | --- | --- |
-| `oms doctor` | project root or child path | Checks `sources.yaml`, git availability, `.gitignore`, and each alias's bare clone + `remote.origin.fetch`. | Returns exit 2 if any warning is raised. |
-| `oms sync <alias>` / `--all` | workspace root | Bare-clones missing repos, fetches origin, creates the baseline worktree. | Adds `sources/` to `.gitignore` if absent. |
-| `oms unsync <alias>` / `--all` | workspace root | Removes every worktree, the bare clone, and the `.git` placeholder for the alias. | Keeps the `sources.yaml` entry. Use `--force` to discard uncommitted changes. |
+| `oms doctor` | project root or child path | Checks `oms.yaml`, git availability, `.gitignore`, and each alias's bare clone + `remote.origin.fetch`. | Returns exit 2 if any warning is raised. |
+| `oms sync <alias>` / `--all` | workspace root | Bare-clones missing repos, fetches origin, creates the baseline worktree. | Adds `oms/` to `.gitignore` if absent. |
+| `oms unsync <alias>` / `--all` | workspace root | Removes every worktree, the bare clone, and the `.git` placeholder for the alias. | Keeps the `oms.yaml` entry. Use `--force` to discard uncommitted changes. |
 | `oms fetch ...` | workspace root | `git fetch origin --prune` on each bare clone. | Worktrees are not touched. |
 | `oms pull ...` | workspace root | `git pull --ff-only` on the baseline worktree of each selected alias. | Requires the worktree to be on its branch with upstream set (the default after `oms sync`). |
 | `oms push <alias>...` | workspace root | `git push` on the baseline worktree of each explicitly listed alias. | No `--all`, no force, no automatic upstream setup. |
@@ -91,7 +91,7 @@ Slash-containing branch names are kept nested as directories.
 | `oms worktree list [alias]` | anywhere under root | Lists every worktree for the alias (or all aliases). | |
 | `oms worktree remove <alias> <branch>` | workspace root | `git worktree remove <branch>` plus parent-directory cleanup for slash branches. | `--force` discards uncommitted changes. |
 
-## `sources.yaml` format
+## `oms.yaml` format
 
 ```yaml
 repos:
@@ -109,28 +109,14 @@ Rules:
 - `url` is required.
 - `branch` is optional; when omitted the bare clone's default branch is used as the baseline worktree.
 
-## Migrating from 0.2.x
+JSON schema: [`oms.schema.json`](./oms.schema.json) (also reachable at `https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json` for YAML LSPs).
 
-0.2.x stored each alias as a Git submodule. 0.3.0 replaces that with a bare clone + worktrees. The data model is breaking — `oms sync` refuses to run while `.gitmodules` still registers a `sources/<alias>` path. Convert your workspace manually:
+## Migrating between versions
 
-```bash
-# 1. For each alias in sources.yaml, deinit and remove the submodule.
-git submodule deinit -f sources/<alias>
-git rm -f sources/<alias>
-rm -rf .git/modules/<alias>
-
-# 2. Drop the now-empty .gitmodules if nothing else uses it.
-[ -s .gitmodules ] || rm -f .gitmodules
-
-# 3. Add sources/ to .gitignore (oms sync will also do this).
-grep -qxF 'sources/' .gitignore 2>/dev/null || echo 'sources/' >> .gitignore
+자세한 마이그레이션 절차는 [`docs/migrations/`](./docs/migrations/) 에 버전별로 정리되어 있습니다.
 
-# 4. Re-sync with the new model.
-oms sync --all
-
-# 5. Commit the result.
-git add . && git commit -m "chore: migrate to oh-my-space 0.3.0 (bare + worktree)"
-```
+- [0.3.x → 0.4.0](./docs/migrations/0.3.x-to-0.4.0.md) — `sources.yaml`/`sources/` 가 `oms.yaml`/`oms/` 로 rename
+- [0.2.x → 0.3.0](./docs/migrations/0.2.x-to-0.3.0.md) — submodule 에서 bare clone + worktree 로 데이터 모델 전환
 
 ## License
 

package/dist/oms.js

@@ -10,57 +10,65 @@ const ALIAS_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const ALLOWED_TOP_KEYS = new Set(["repos"]);
 const ALLOWED_ITEM_KEYS = new Set(["alias", "url", "branch"]);
 const FETCH_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
-const GITIGNORE_ENTRY = "sources/";
+const MANIFEST_FILENAME = "oms.yaml";
+const DATA_DIRNAME = "oms";
+const GITIGNORE_ENTRY = `${DATA_DIRNAME}/`;
+const LEGACY_MANIFEST = "sources.yaml";
+const LEGACY_DATA_DIRNAME = "sources";
+const LEGACY_MIGRATION_DOC = "docs/migrations/0.3.x-to-0.4.0.md";
+const SUBMODULE_MIGRATION_DOC = "docs/migrations/0.2.x-to-0.3.0.md";
+const MIN_GIT_MAJOR = 2;
+const MIN_GIT_MINOR = 40;
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const useColor = process.stdout.isTTY;
 const dim = (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s);
 function validateSources(data) {
     if (!data || typeof data !== "object" || Array.isArray(data)) {
-        throw new Error("sources.yaml: root must be a mapping");
+        throw new Error(`${MANIFEST_FILENAME}: root must be a mapping`);
     }
     const obj = data;
     for (const key of Object.keys(obj)) {
         if (!ALLOWED_TOP_KEYS.has(key)) {
-            throw new Error(`sources.yaml: unknown top-level key "${key}"`);
+            throw new Error(`${MANIFEST_FILENAME}: unknown top-level key "${key}"`);
         }
     }
     const { repos } = obj;
     if (!Array.isArray(repos)) {
-        throw new Error('sources.yaml: "repos" must be an array');
+        throw new Error(`${MANIFEST_FILENAME}: "repos" must be an array`);
     }
     if (repos.length === 0) {
-        throw new Error('sources.yaml: "repos" must have at least one item');
+        throw new Error(`${MANIFEST_FILENAME}: "repos" must have at least one item`);
     }
     const validated = [];
     const seen = new Set();
     repos.forEach((item, idx) => {
         const where = `repos[${idx}]`;
         if (!item || typeof item !== "object" || Array.isArray(item)) {
-            throw new Error(`sources.yaml: ${where} must be a mapping`);
+            throw new Error(`${MANIFEST_FILENAME}: ${where} must be a mapping`);
         }
         const r = item;
         for (const key of Object.keys(r)) {
             if (!ALLOWED_ITEM_KEYS.has(key)) {
-                throw new Error(`sources.yaml: ${where} has unknown key "${key}"`);
+                throw new Error(`${MANIFEST_FILENAME}: ${where} has unknown key "${key}"`);
             }
         }
         if (typeof r.alias !== "string" || r.alias.length === 0) {
-            throw new Error(`sources.yaml: ${where} missing required "alias"`);
+            throw new Error(`${MANIFEST_FILENAME}: ${where} missing required "alias"`);
         }
         if (!ALIAS_PATTERN.test(r.alias)) {
-            throw new Error(`sources.yaml: ${where}.alias "${r.alias}" must match ${ALIAS_PATTERN}`);
+            throw new Error(`${MANIFEST_FILENAME}: ${where}.alias "${r.alias}" must match ${ALIAS_PATTERN}`);
         }
         if (seen.has(r.alias)) {
-            throw new Error(`sources.yaml: duplicate alias "${r.alias}"`);
+            throw new Error(`${MANIFEST_FILENAME}: duplicate alias "${r.alias}"`);
         }
         seen.add(r.alias);
         if (typeof r.url !== "string" || r.url.length === 0) {
-            throw new Error(`sources.yaml: ${where} missing required "url"`);
+            throw new Error(`${MANIFEST_FILENAME}: ${where} missing required "url"`);
         }
         let branch;
         if (r.branch !== undefined) {
             if (typeof r.branch !== "string" || r.branch.length === 0) {
-                throw new Error(`sources.yaml: ${where}.branch must be a non-empty string`);
+                throw new Error(`${MANIFEST_FILENAME}: ${where}.branch must be a non-empty string`);
             }
             branch = r.branch;
         }
@@ -109,14 +117,27 @@ function runGit(cwd, args, inheritOutput = false) {
         stdout: inheritOutput ? "" : (result.stdout ?? ""),
     };
 }
-/** Run git from sources/<alias>/ with safe.bareRepository=all, so the .git placeholder routes to .bare. */
+/** Run git from oms/<alias>/ with safe.bareRepository=all, so the .git placeholder routes to .bare. */
 function runBareGit(repoRoot, alias, args, inheritOutput = false) {
     return runGit(aliasDir(repoRoot, alias), ["-c", "safe.bareRepository=all", ...args], inheritOutput);
 }
+function parseGitVersion(s) {
+    const m = s.match(/git version (\d+)\.(\d+)/);
+    if (!m)
+        return null;
+    return { major: Number.parseInt(m[1], 10), minor: Number.parseInt(m[2], 10) };
+}
+function isGitVersionSupported(v) {
+    if (v.major > MIN_GIT_MAJOR)
+        return true;
+    if (v.major < MIN_GIT_MAJOR)
+        return false;
+    return v.minor >= MIN_GIT_MINOR;
+}
 function findWorkspaceRoot(options = {}) {
     let current = resolve(options.cwd ?? process.cwd());
     while (true) {
-        if (existsSync(join(current, "sources.yaml")))
+        if (existsSync(join(current, MANIFEST_FILENAME)))
             return current;
         const parent = dirname(current);
         if (parent === current)
@@ -125,7 +146,7 @@ function findWorkspaceRoot(options = {}) {
     }
 }
 function aliasDir(repoRoot, alias) {
-    return join(repoRoot, "sources", alias);
+    return join(repoRoot, DATA_DIRNAME, alias);
 }
 function bareDir(repoRoot, alias) {
     return join(aliasDir(repoRoot, alias), ".bare");
@@ -152,19 +173,68 @@ function isRegisteredSubmodule(repoRoot, sourcePath) {
         .split("\n")
         .some((line) => line.trim().split(/\s+/)[1] === sourcePath);
 }
-/** Returns true when .gitmodules registers any sources/<alias> entry for the loaded repos. */
+/** Returns true when .gitmodules registers any sources/<alias> or oms/<alias> entry for the loaded repos. */
 function hasLegacySubmoduleLayout(repoRoot, repos) {
     if (!existsSync(join(repoRoot, ".gitmodules")))
         return false;
-    return repos.some((repo) => isRegisteredSubmodule(repoRoot, `sources/${repo.alias}`));
+    return repos.some((repo) => isRegisteredSubmodule(repoRoot, `${LEGACY_DATA_DIRNAME}/${repo.alias}`)
+        || isRegisteredSubmodule(repoRoot, `${DATA_DIRNAME}/${repo.alias}`));
 }
 function abortOnLegacy(repoRoot, repos) {
     if (!hasLegacySubmoduleLayout(repoRoot, repos))
         return false;
-    log.error('detected legacy submodule layout (.gitmodules registers sources/<alias>). oh-my-space 0.3.0 uses bare clone + worktrees.\n' +
-        '  See README "Migrating from 0.2.x" for the manual steps. Aborting to avoid destructive change.');
+    log.error('detected legacy submodule layout (.gitmodules registers an alias path). oh-my-space 0.3.0+ uses bare clone + worktrees.\n' +
+        `  See ${SUBMODULE_MIGRATION_DOC} for the manual steps. Aborting to avoid destructive change.`);
     return true;
 }
+/** Inspect a single directory for 0.3.x rename artifacts. */
+function detectLegacyRenameArtifactsAt(dir) {
+    const manifest = existsSync(join(dir, LEGACY_MANIFEST));
+    const data = existsSync(join(dir, LEGACY_DATA_DIRNAME));
+    if (!manifest && !data)
+        return null;
+    return { manifest, data };
+}
+function emitLegacyRenameMessage(dir, found) {
+    const artifacts = [
+        found.manifest ? `'${LEGACY_MANIFEST}'` : null,
+        found.data ? `'${LEGACY_DATA_DIRNAME}/'` : null,
+    ]
+        .filter((s) => s !== null)
+        .join(" and ");
+    log.error(`detected legacy ${artifacts} at ${dir}.\n` +
+        `  oh-my-space 0.4.0 renamed the manifest to ${MANIFEST_FILENAME} and the data directory to ${DATA_DIRNAME}/.\n` +
+        `  See ${LEGACY_MIGRATION_DOC} for the manual steps. Aborting to avoid destructive change.`);
+}
+/** Block when the active oms.yaml workspace still has legacy artifacts at its root. */
+function abortOnLegacyRenameAt(repoRoot) {
+    const found = detectLegacyRenameArtifactsAt(repoRoot);
+    if (!found)
+        return false;
+    emitLegacyRenameMessage(repoRoot, found);
+    return true;
+}
+/**
+ * When oms.yaml could not be found, walk upward looking for a 0.3.x manifest (sources.yaml).
+ * Only the manifest is trusted as a positive signal — a stray sources/ directory by itself
+ * could belong to an unrelated tool. Returns true if a hint was emitted.
+ */
+function emitLegacyRenameHintWalkUp(options = {}) {
+    let current = resolve(options.cwd ?? process.cwd());
+    while (true) {
+        if (existsSync(join(current, LEGACY_MANIFEST))) {
+            emitLegacyRenameMessage(current, {
+                manifest: true,
+                data: existsSync(join(current, LEGACY_DATA_DIRNAME)),
+            });
+            return true;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
 function ensureGitignore(repoRoot) {
     const path = join(repoRoot, ".gitignore");
     let content = "";
@@ -195,7 +265,7 @@ function setupBareRepo(repo, repoRoot) {
         return false;
     }
     // Write the placeholder before any further runBareGit calls, otherwise git ascends
-    // out of sources/<alias>/ looking for a repo and touches the wrong .git.
+    // out of oms/<alias>/ looking for a repo and touches the wrong .git.
     writeFileSync(gitPlaceholderPath(repoRoot, alias), "gitdir: ./.bare\n");
     const config = runBareGit(repoRoot, alias, [
         "config",
@@ -250,7 +320,7 @@ function listExistingWorktrees(repoRoot, alias) {
         if (!path || bare)
             continue;
         const rel = relative(aliasPath, path);
-        // Skip worktrees outside sources/<alias>/ (shouldn't happen, but be safe)
+        // Skip worktrees outside oms/<alias>/ (shouldn't happen, but be safe)
         if (rel.startsWith(".."))
             continue;
         entries.push({ branch, path, relativePath: rel });
@@ -280,7 +350,7 @@ function cleanupEmptyParents(repoRoot, alias, branch) {
 function addWorktree(repo, repoRoot, branch) {
     const wtPath = worktreePath(repoRoot, repo.alias, branch);
     if (existsSync(wtPath)) {
-        log.warn(`${repo.alias}: sources/${repo.alias}/${branch} already exists; skipping.`);
+        log.warn(`${repo.alias}: ${DATA_DIRNAME}/${repo.alias}/${branch} already exists; skipping.`);
         return true;
     }
     log.step(`${repo.alias}: git worktree add --track -B ${branch} ${branch} origin/${branch}`);
@@ -316,7 +386,7 @@ function syncRepo(repo, repoRoot) {
         if (existsSync(aliasPath)) {
             const stray = readdirSync(aliasPath).filter((e) => e !== ".git");
             if (stray.length > 0) {
-                log.error(`${alias}: sources/${alias}/ already exists but is not a bare clone. Move or remove it manually, then retry.`);
+                log.error(`${alias}: ${DATA_DIRNAME}/${alias}/ already exists but is not a bare clone. Move or remove it manually, then retry.`);
                 return "failed";
             }
         }
@@ -350,7 +420,7 @@ function syncRepo(repo, repoRoot) {
         }
         const branch = repo.branch ?? detectDefaultBranch(repoRoot, alias);
         if (!branch) {
-            log.error(`${alias}: could not determine default branch from bare clone. Set "branch:" in sources.yaml.`);
+            log.error(`${alias}: could not determine default branch from bare clone. Set "branch:" in ${MANIFEST_FILENAME}.`);
             return "failed";
         }
         if (!addWorktree(repo, repoRoot, branch))
@@ -389,7 +459,7 @@ function unsyncRepo(repo, repoRoot, force) {
         for (const wt of worktrees) {
             const status = runGit(wt.path, ["status", "--porcelain"]);
             if (status.success && status.stdout.trim().length > 0) {
-                log.error(`${repo.alias}: worktree at sources/${repo.alias}/${wt.relativePath} has uncommitted changes. Commit, stash, or pass --force.`);
+                log.error(`${repo.alias}: worktree at ${DATA_DIRNAME}/${repo.alias}/${wt.relativePath} has uncommitted changes. Commit, stash, or pass --force.`);
                 return "failed";
             }
         }
@@ -513,12 +583,12 @@ function exitFromResults(results) {
 function loadRepos(options = {}) {
     const repoRoot = findWorkspaceRoot(options);
     if (!repoRoot) {
-        log.error("Could not find sources.yaml in the current directory or its parents. Create a sources.yaml in this project, then retry.");
+        log.error(`Could not find ${MANIFEST_FILENAME} in the current directory or its parents. Create a ${MANIFEST_FILENAME} in this project, then retry.`);
         return null;
     }
     try {
-        const sourcesPath = join(repoRoot, "sources.yaml");
-        return { repos: validateSources(parseYaml(readFileSync(sourcesPath, "utf8"))), repoRoot };
+        const manifestPath = join(repoRoot, MANIFEST_FILENAME);
+        return { repos: validateSources(parseYaml(readFileSync(manifestPath, "utf8"))), repoRoot };
     }
     catch (e) {
         log.error(e instanceof Error ? e.message : String(e));
@@ -550,9 +620,13 @@ async function selectRepos(repos, aliases, options, actionLabel) {
 }
 async function runSync(aliases, options) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (options.list) {
         printList(repos);
         return 0;
@@ -570,9 +644,13 @@ async function runSync(aliases, options) {
 }
 async function runManage(command, aliases, options) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const picked = await selectRepos(repos, aliases, options, command);
@@ -586,9 +664,13 @@ async function runManage(command, aliases, options) {
 }
 async function runUnsync(aliases, options) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const picked = await selectRepos(repos, aliases, options, "unsync");
@@ -613,9 +695,13 @@ async function runUnsync(aliases, options) {
 }
 async function runWorktreeAdd(alias, branch) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const repo = repos.find((r) => r.alias === alias);
@@ -628,7 +714,7 @@ async function runWorktreeAdd(alias, branch) {
         return 1;
     }
     if (existsSync(worktreePath(repoRoot, alias, branch))) {
-        log.error(`${alias}: worktree for ${branch} already exists at sources/${alias}/${branch}.`);
+        log.error(`${alias}: worktree for ${branch} already exists at ${DATA_DIRNAME}/${alias}/${branch}.`);
         return 1;
     }
     log.step(`${alias}: git fetch origin --prune (refresh before add)`);
@@ -640,9 +726,13 @@ async function runWorktreeAdd(alias, branch) {
 }
 async function runWorktreeList(alias) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const targets = alias ? repos.filter((r) => r.alias === alias) : repos;
@@ -665,7 +755,7 @@ async function runWorktreeList(alias) {
             rows.push({
                 alias: repo.alias,
                 branch: wt.branch,
-                path: `sources/${repo.alias}/${wt.relativePath}`,
+                path: `${DATA_DIRNAME}/${repo.alias}/${wt.relativePath}`,
             });
         }
     }
@@ -679,9 +769,13 @@ async function runWorktreeList(alias) {
 }
 async function runWorktreeRemove(alias, branch, options) {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     if (abortOnLegacy(repoRoot, repos))
         return 1;
     const repo = repos.find((r) => r.alias === alias);
@@ -708,25 +802,36 @@ async function runWorktreeRemove(alias, branch, options) {
 }
 async function runDoctor() {
     const loaded = loadRepos();
-    if (!loaded)
+    if (!loaded) {
+        emitLegacyRenameHintWalkUp();
         return 1;
+    }
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacyRenameAt(repoRoot))
+        return 1;
     log.success(`Workspace root: ${repoRoot}`);
-    log.success(`sources.yaml: ${repos.length} repo(s) configured`);
+    log.success(`${MANIFEST_FILENAME}: ${repos.length} repo(s) configured`);
     const git = spawnSync("git", ["--version"], {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "pipe"],
     });
-    if (git.status === 0) {
-        log.success(`git: ${git.stdout.trim()}`);
-    }
-    else {
+    if (git.status !== 0) {
         log.error("git: not found");
         return 1;
     }
+    log.success(`git: ${git.stdout.trim()}`);
     let warnings = 0;
+    const parsed = parseGitVersion(git.stdout);
+    if (!parsed) {
+        log.warn(`git: could not parse version from "${git.stdout.trim()}"; oms expects git >=${MIN_GIT_MAJOR}.${MIN_GIT_MINOR}.`);
+        warnings++;
+    }
+    else if (!isGitVersionSupported(parsed)) {
+        log.warn(`git ${parsed.major}.${parsed.minor} is older than the recommended ${MIN_GIT_MAJOR}.${MIN_GIT_MINOR}. oms uses "git worktree add --track -B" which may fail on older releases — upgrade git.`);
+        warnings++;
+    }
     if (hasLegacySubmoduleLayout(repoRoot, repos)) {
-        log.warn('detected legacy submodule layout (.gitmodules registers sources/<alias>). See README "Migrating from 0.2.x".');
+        log.warn(`detected legacy submodule layout (.gitmodules registers an alias path). See ${SUBMODULE_MIGRATION_DOC}.`);
         warnings++;
     }
     const gi = join(repoRoot, ".gitignore");
@@ -746,14 +851,14 @@ async function runDoctor() {
         }
         const refspec = runBareGit(repoRoot, repo.alias, ["config", "--get", "remote.origin.fetch"]);
         if (!refspec.success || refspec.stdout.trim().length === 0) {
-            log.warn(`${repo.alias}: bare clone is missing remote.origin.fetch. Run: git -C sources/${repo.alias}/.bare -c safe.bareRepository=all config remote.origin.fetch '${FETCH_REFSPEC}'`);
+            log.warn(`${repo.alias}: bare clone is missing remote.origin.fetch. Run: git -C ${DATA_DIRNAME}/${repo.alias}/.bare -c safe.bareRepository=all config remote.origin.fetch '${FETCH_REFSPEC}'`);
             warnings++;
         }
         else {
             log.success(`${repo.alias}: bare clone OK (refspec: ${refspec.stdout.trim()})`);
         }
         if (!existsSync(gitPlaceholderPath(repoRoot, repo.alias))) {
-            log.warn(`${repo.alias}: missing .git placeholder at sources/${repo.alias}/.git. Recreate with: echo 'gitdir: ./.bare' > sources/${repo.alias}/.git`);
+            log.warn(`${repo.alias}: missing .git placeholder at ${DATA_DIRNAME}/${repo.alias}/.git. Recreate with: echo 'gitdir: ./.bare' > ${DATA_DIRNAME}/${repo.alias}/.git`);
             warnings++;
         }
     }
@@ -791,19 +896,19 @@ const commandNames = new Set([
 const program = new Command();
 program
     .name("oms")
-    .description("Manage source repositories listed in sources.yaml as bare clones + worktrees under sources/<alias>/.")
+    .description(`Manage source repositories listed in ${MANIFEST_FILENAME} as bare clones + worktrees under ${DATA_DIRNAME}/<alias>/.`)
     .version(readPackageVersion())
     .addHelpText("after", exitHelp);
 program
     .command("doctor")
-    .description("Check sources.yaml, git availability, bare-clone state, and .gitignore for each registered alias.")
+    .description(`Check ${MANIFEST_FILENAME}, git availability, bare-clone state, and .gitignore for each registered alias.`)
     .addHelpText("after", exitHelp)
     .action(async () => {
     await exitWith(runDoctor());
 });
 program
     .command("sync")
-    .description("Bare-clone each registered repo into sources/<alias>/.bare and create the baseline worktree at sources/<alias>/<branch>/.")
+    .description(`Bare-clone each registered repo into ${DATA_DIRNAME}/<alias>/.bare and create the baseline worktree at ${DATA_DIRNAME}/<alias>/<branch>/.`)
     .argument("[aliases...]", "repo aliases to sync (omit for interactive multi-select)")
     .option("--all", "sync every registered source repo")
     .option("--list", "print registered repos")
@@ -839,7 +944,7 @@ program
 });
 program
     .command("unsync")
-    .description("Remove all worktrees and the bare clone for each alias (keeps sources.yaml entry).")
+    .description(`Remove all worktrees and the bare clone for each alias (keeps ${MANIFEST_FILENAME} entry).`)
     .argument("[aliases...]", "repo aliases to unsync (omit for interactive multi-select)")
     .option("--all", "unsync every registered source repo")
     .option("--force", "discard uncommitted changes in worktrees")
@@ -853,7 +958,7 @@ const worktreeCmd = program
     .addHelpText("after", exitHelp);
 worktreeCmd
     .command("add")
-    .description("Create a worktree for <branch> at sources/<alias>/<branch>/.")
+    .description(`Create a worktree for <branch> at ${DATA_DIRNAME}/<alias>/<branch>/.`)
     .argument("<alias>", "registered source alias")
     .argument("<branch>", "branch name (may include slashes)")
     .addHelpText("after", exitHelp)
@@ -870,7 +975,7 @@ worktreeCmd
 });
 worktreeCmd
     .command("remove")
-    .description("Remove the worktree at sources/<alias>/<branch>.")
+    .description(`Remove the worktree at ${DATA_DIRNAME}/<alias>/<branch>.`)
     .argument("<alias>", "registered source alias")
     .argument("<branch>", "branch name (may include slashes)")
     .option("--force", "discard uncommitted changes")

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oh-my-space",
-  "version": "0.3.0",
-  "description": "CLI for managing external source repositories declared in sources.yaml.",
+  "version": "0.4.0",
+  "description": "CLI for managing external source repositories declared in oms.yaml.",
   "license": "MIT",
   "homepage": "https://github.com/divlook/oh-my-space",
   "repository": {
@@ -12,8 +12,8 @@
     "url": "https://github.com/divlook/oh-my-space/issues"
   },
   "keywords": [
-    "sources",
-    "submodule",
+    "oms",
+    "worktree",
     "git",
     "cli"
   ],
@@ -40,7 +40,7 @@
     "prepack": "npm test",
     "changeset": "changeset",
     "version": "changeset version",
-    "release": "npm test && npm publish --provenance --access public"
+    "release": "changeset publish"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",