oh-my-space 0.2.0 → 0.3.1

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`. It syncs those entries into Git submodules under `sources/<alias>/` and runs safe fetch/pull/push operations inside selected source worktrees.
+`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>/`.
 
 Package name: `oh-my-space`
 
@@ -9,7 +9,7 @@ Command name: `oms`
 ## Requirements
 
 - [Node.js](https://nodejs.org) `>=20.19.0` for running `oms`; development uses the version in `.nvmrc` (`24`)
-- git
+- git `>=2.40` (worktree `--track -B` flow)
 
 For local development:
 
@@ -43,39 +43,53 @@ repos:
     url: git@github.com:example/web.git
 ```
 
-List, sync, and unsync registered source repositories:
+Sync and explore:
 
 ```bash
-oms doctor              # check sources.yaml and git availability
-oms sync --list         # list registered source repos
-oms sync <alias>...     # add/init/update submodules by alias
-oms sync --all          # add/init/update every registered source repo
-oms sync                # interactive multi-select
-oms unsync <alias>...   # remove submodule + worktree (sources.yaml entry kept)
-oms unsync --all        # unsync every registered source repo
-oms unsync --force ...  # discard uncommitted changes in the source worktree
+oms doctor                         # validate sources.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
+oms sync                           # interactive multi-select
+oms worktree add <alias> <branch>  # add another worktree alongside the baseline
+oms worktree list [alias]          # show every worktree
+oms worktree remove <alias> <br>   # remove a single worktree
+oms unsync <alias>...              # remove ALL worktrees + the bare clone
 ```
 
-## Managing source repositories
+`oms sync` adds `sources/` to your workspace `.gitignore` on first run; the bare clone and worktrees stay out of your project history.
 
-`sources.yaml` declares each source repo with `alias`, `url`, and optional `branch`. Checkouts live as Git submodules under `sources/<alias>/`.
+## Layout
 
-| Command | Runs in | Does | Notes |
-| --- | --- | --- | --- |
-| `oms doctor` | project root or child path | Validates `sources.yaml` and checks `git --version`. | Fails when `sources.yaml` is missing or invalid. |
-| `oms sync <alias>` / `--all` | workspace root | Adds missing submodules and initializes/updates registered ones. | Syncs `sources.yaml` to `sources/<alias>/`. |
-| `oms unsync <alias>` / `--all` | workspace root | Deinits the submodule and removes `sources/<alias>/` (leaves the staged change to commit). | Keeps the entry in `sources.yaml`; pass `--force` to discard uncommitted changes in the worktree. |
-| `oms fetch ...` | selected checked-out submodule worktree | `git fetch --all --prune` | Does not change the superproject gitlink. |
-| `oms pull ...` | selected checked-out submodule worktree | `git pull --ff-only` | Requires a branch with upstream; detached HEAD/no-upstream states fail. |
-| `oms push <alias>...` | explicitly selected checked-out submodule worktree | `git push` | No `--all`, force push, or automatic upstream setup. |
+For an alias `api` with the baseline branch `main` and an extra `feature/foo` worktree:
 
-To add a repo, add it under `repos:` in `sources.yaml`, run `oms sync <alias>`, then commit `sources.yaml`, `.gitmodules`, and the gitlink change.
+```
+sources/
+└── api/
+    ├── .bare/             # git clone --bare result
+    ├── .git               # 'gitdir: ./.bare' placeholder
+    ├── main/              # worktree for main (upstream: origin/main)
+    └── feature/
+        └── foo/           # worktree for feature/foo
+```
 
-Standard Git submodule commands still work, for example:
+Slash-containing branch names are kept nested as directories.
 
-```bash
-git submodule update --init --recursive
-```
+## 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.
+
+| 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 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. |
+| `oms worktree add <alias> <branch>` | workspace root | `git worktree add --track -B <branch> <branch> origin/<branch>` inside the alias. | Slash branches become nested 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
 
@@ -93,7 +107,30 @@ Rules:
 - `repos` must be a non-empty array.
 - `alias` must be unique and match `/^[a-z0-9][a-z0-9-]*$/`.
 - `url` is required.
-- `branch` is optional and is passed to `git submodule add --branch` only when adding a new submodule.
+- `branch` is optional; when omitted the bare clone's default branch is used as the baseline worktree.
+
+## Migrating from 0.2.x
+
+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:
+
+```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
+
+# 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)"
+```
 
 ## License
 

package/dist/oms.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, rmSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, rmdirSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Command } from "commander";
 import { cancel, isCancel, log, multiselect } from "@clack/prompts";
@@ -9,16 +9,10 @@ import { parse as parseYaml } from "yaml";
 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 MANAGE_GIT_ARGS = {
-    fetch: ["fetch", "--all", "--prune"],
-    pull: ["pull", "--ff-only"],
-    push: ["-c", "push.autoSetupRemote=false", "push"],
-};
-const RESULT_BY_COMMAND = {
-    fetch: "fetched",
-    pull: "pulled",
-    push: "pushed",
-};
+const FETCH_REFSPEC = "+refs/heads/*:refs/remotes/origin/*";
+const GITIGNORE_ENTRY = "sources/";
+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);
@@ -117,6 +111,23 @@ 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. */
+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) {
@@ -128,6 +139,18 @@ function findWorkspaceRoot(options = {}) {
         current = parent;
     }
 }
+function aliasDir(repoRoot, alias) {
+    return join(repoRoot, "sources", alias);
+}
+function bareDir(repoRoot, alias) {
+    return join(aliasDir(repoRoot, alias), ".bare");
+}
+function gitPlaceholderPath(repoRoot, alias) {
+    return join(aliasDir(repoRoot, alias), ".git");
+}
+function worktreePath(repoRoot, alias, branch) {
+    return join(aliasDir(repoRoot, alias), branch);
+}
 function isRegisteredSubmodule(repoRoot, sourcePath) {
     if (!existsSync(join(repoRoot, ".gitmodules")))
         return false;
@@ -144,143 +167,342 @@ function isRegisteredSubmodule(repoRoot, sourcePath) {
         .split("\n")
         .some((line) => line.trim().split(/\s+/)[1] === sourcePath);
 }
-function isCheckedOutGitRepo(repoRoot, sourcePath) {
-    const dest = join(repoRoot, sourcePath);
-    if (!existsSync(dest))
+/** Returns true when .gitmodules registers any sources/<alias> entry for the loaded repos. */
+function hasLegacySubmoduleLayout(repoRoot, repos) {
+    if (!existsSync(join(repoRoot, ".gitmodules")))
         return false;
-    const result = runGit(dest, ["rev-parse", "--is-inside-work-tree"]);
-    return result.success && result.stdout.trim() === "true";
-}
-function removeSubmoduleArtifacts(repo, repoRoot, options = {}) {
-    const sourcePath = `sources/${repo.alias}`;
-    const dest = join(repoRoot, sourcePath);
-    const modulesDir = join(repoRoot, ".git", "modules", repo.alias);
-    const registered = isRegisteredSubmodule(repoRoot, sourcePath);
-    const worktreeExists = existsSync(dest);
-    const worktreeIsGitRepo = worktreeExists && isCheckedOutGitRepo(repoRoot, sourcePath);
-    const moduleDirExists = existsSync(modulesDir);
-    if (!registered && !worktreeExists && !moduleDirExists) {
-        return "nothing-to-remove";
+    return repos.some((repo) => isRegisteredSubmodule(repoRoot, `sources/${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.');
+    return true;
+}
+function ensureGitignore(repoRoot) {
+    const path = join(repoRoot, ".gitignore");
+    let content = "";
+    if (existsSync(path)) {
+        content = readFileSync(path, "utf8");
+        const present = content
+            .split("\n")
+            .some((line) => line.trim() === GITIGNORE_ENTRY || line.trim() === `/${GITIGNORE_ENTRY}`);
+        if (present)
+            return;
     }
-    if (worktreeExists && !registered && !moduleDirExists && !worktreeIsGitRepo) {
-        log.error(`${repo.alias}: ${sourcePath} exists but is not a git submodule. Remove it manually if intended.`);
-        return "failed";
+    const needsNewline = content.length > 0 && !content.endsWith("\n");
+    writeFileSync(path, `${content}${needsNewline ? "\n" : ""}${GITIGNORE_ENTRY}\n`);
+    log.info(`added ${GITIGNORE_ENTRY} to .gitignore`);
+}
+function setupBareRepo(repo, repoRoot) {
+    const alias = repo.alias;
+    const aliasPath = aliasDir(repoRoot, alias);
+    const barePath = bareDir(repoRoot, alias);
+    mkdirSync(aliasPath, { recursive: true });
+    const relBare = relative(repoRoot, barePath);
+    log.step(`git clone --bare ${repo.url} ${relBare}`);
+    const clone = runGit(repoRoot, ["clone", "--bare", repo.url, relBare], true);
+    if (!clone.success) {
+        log.error(`${alias}: git clone --bare failed (exit ${clone.exitCode})`);
+        if (existsSync(barePath))
+            rmSync(barePath, { recursive: true, force: true });
+        return false;
     }
-    if (!options.force && worktreeIsGitRepo) {
-        const status = runGit(dest, ["status", "--porcelain"]);
-        if (status.success && status.stdout.trim().length > 0) {
-            log.error(`${repo.alias}: ${sourcePath} has uncommitted changes. Commit or stash them, or pass --force to discard.`);
-            return "failed";
+    // Write the placeholder before any further runBareGit calls, otherwise git ascends
+    // out of sources/<alias>/ looking for a repo and touches the wrong .git.
+    writeFileSync(gitPlaceholderPath(repoRoot, alias), "gitdir: ./.bare\n");
+    const config = runBareGit(repoRoot, alias, [
+        "config",
+        "remote.origin.fetch",
+        FETCH_REFSPEC,
+    ]);
+    if (!config.success) {
+        log.error(`${alias}: failed to set remote.origin.fetch (exit ${config.exitCode})`);
+        return false;
+    }
+    log.step(`${alias}: git fetch origin`);
+    const fetch = runBareGit(repoRoot, alias, ["fetch", "origin", "--prune"], true);
+    if (!fetch.success) {
+        log.error(`${alias}: initial fetch failed (exit ${fetch.exitCode})`);
+        return false;
+    }
+    return true;
+}
+function detectDefaultBranch(repoRoot, alias) {
+    const r = runBareGit(repoRoot, alias, ["symbolic-ref", "--short", "HEAD"]);
+    if (r.success) {
+        const out = r.stdout.trim();
+        return out.length > 0 ? out : null;
+    }
+    return null;
+}
+function listExistingWorktrees(repoRoot, alias) {
+    if (!existsSync(bareDir(repoRoot, alias)))
+        return [];
+    const result = runBareGit(repoRoot, alias, ["worktree", "list", "--porcelain"]);
+    if (!result.success)
+        return [];
+    const aliasPath = aliasDir(repoRoot, alias);
+    const entries = [];
+    const blocks = result.stdout
+        .split(/\n\n+/)
+        .map((b) => b.trim())
+        .filter((b) => b.length > 0);
+    for (const block of blocks) {
+        let path = "";
+        let branch = "(detached)";
+        let bare = false;
+        for (const line of block.split("\n")) {
+            if (line.startsWith("worktree "))
+                path = line.slice("worktree ".length);
+            else if (line.startsWith("branch ")) {
+                branch = line.slice("branch ".length).replace(/^refs\/heads\//, "");
+            }
+            else if (line === "bare")
+                bare = true;
         }
+        if (!path || bare)
+            continue;
+        const rel = relative(aliasPath, path);
+        // Skip worktrees outside sources/<alias>/ (shouldn't happen, but be safe)
+        if (rel.startsWith(".."))
+            continue;
+        entries.push({ branch, path, relativePath: rel });
     }
-    let didSomething = false;
-    if (registered) {
-        const deinit = runGit(repoRoot, ["submodule", "deinit", "-f", sourcePath]);
-        if (!deinit.success) {
-            log.error(`${repo.alias}: git submodule deinit failed (exit ${deinit.exitCode}) for ${sourcePath}`);
-            return "failed";
+    return entries;
+}
+function cleanupEmptyParents(repoRoot, alias, branch) {
+    const parts = branch.split("/").filter((p) => p.length > 0);
+    if (parts.length < 2)
+        return;
+    for (let i = parts.length - 1; i >= 1; i--) {
+        const dirPath = join(aliasDir(repoRoot, alias), ...parts.slice(0, i));
+        try {
+            const entries = readdirSync(dirPath);
+            if (entries.length === 0) {
+                rmdirSync(dirPath);
+            }
+            else {
+                break;
+            }
+        }
+        catch {
+            break;
         }
-        didSomething = true;
     }
-    if (registered || worktreeIsGitRepo) {
-        const rm = runGit(repoRoot, ["rm", "-f", sourcePath]);
-        if (!rm.success) {
-            log.error(`${repo.alias}: git rm failed (exit ${rm.exitCode}) for ${sourcePath}`);
+}
+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.`);
+        return true;
+    }
+    log.step(`${repo.alias}: git worktree add --track -B ${branch} ${branch} origin/${branch}`);
+    const result = runBareGit(repoRoot, repo.alias, ["worktree", "add", "--track", "-B", branch, branch, `origin/${branch}`], true);
+    if (!result.success) {
+        log.error(`${repo.alias}: worktree add for ${branch} failed (exit ${result.exitCode})`);
+        cleanupEmptyParents(repoRoot, repo.alias, branch);
+        return false;
+    }
+    return true;
+}
+function removeWorktree(repo, repoRoot, branch, force) {
+    const wtPath = worktreePath(repoRoot, repo.alias, branch);
+    if (!existsSync(wtPath))
+        return true;
+    const args = ["worktree", "remove", ...(force ? ["--force"] : []), branch];
+    log.step(`${repo.alias}: git worktree remove ${branch}${force ? " --force" : ""}`);
+    const result = runBareGit(repoRoot, repo.alias, args, true);
+    if (!result.success) {
+        log.error(`${repo.alias}: worktree remove for ${branch} failed (exit ${result.exitCode})`);
+        return false;
+    }
+    cleanupEmptyParents(repoRoot, repo.alias, branch);
+    return true;
+}
+function syncRepo(repo, repoRoot) {
+    const alias = repo.alias;
+    const aliasPath = aliasDir(repoRoot, alias);
+    const barePath = bareDir(repoRoot, alias);
+    const placeholderPath = gitPlaceholderPath(repoRoot, alias);
+    const bareExists = existsSync(barePath);
+    if (!bareExists) {
+        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.`);
+                return "failed";
+            }
+        }
+        if (repo.branch) {
+            const lsRemote = runGit(repoRoot, [
+                "ls-remote",
+                "--exit-code",
+                "--heads",
+                repo.url,
+                repo.branch,
+            ]);
+            if (lsRemote.exitCode === 2) {
+                log.error(`${alias}: branch "${repo.branch}" not found on ${repo.url}. Push the branch upstream or fix the alias, then retry.`);
+                return "failed";
+            }
+            if (!lsRemote.success && lsRemote.exitCode !== 2) {
+                log.warn(`${alias}: branch existence check failed (exit ${lsRemote.exitCode}); proceeding.`);
+            }
+        }
+        if (!setupBareRepo(repo, repoRoot)) {
+            if (existsSync(barePath))
+                rmSync(barePath, { recursive: true, force: true });
+            if (existsSync(placeholderPath))
+                rmSync(placeholderPath);
+            try {
+                if (readdirSync(aliasPath).length === 0)
+                    rmdirSync(aliasPath);
+            }
+            catch { }
             return "failed";
         }
-        didSomething = true;
+        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.`);
+            return "failed";
+        }
+        if (!addWorktree(repo, repoRoot, branch))
+            return "failed";
+        log.success(`${alias}: added (branch=${branch})`);
+        return "added";
     }
-    runGit(repoRoot, [
-        "config",
-        "--file",
-        ".gitmodules",
-        "--remove-section",
-        `submodule.${repo.alias}`,
-    ]);
-    if (moduleDirExists) {
-        rmSync(modulesDir, { recursive: true, force: true });
-        didSomething = true;
-    }
-    return didSomething ? "removed" : "nothing-to-remove";
-}
-function syncSubmodule(repo, repoRoot) {
-    const sourcePath = `sources/${repo.alias}`;
-    const dest = join(repoRoot, sourcePath);
-    const registered = isRegisteredSubmodule(repoRoot, sourcePath);
-    if (!registered && existsSync(dest)) {
-        log.error(`${repo.alias}: ${sourcePath} already exists but is not registered as a git submodule. Move or remove it manually, then retry.`);
+    if (!existsSync(placeholderPath)) {
+        writeFileSync(placeholderPath, "gitdir: ./.bare\n");
+    }
+    log.step(`${alias}: git fetch origin`);
+    const fetch = runBareGit(repoRoot, alias, ["fetch", "origin", "--prune"], true);
+    if (!fetch.success) {
+        log.error(`${alias}: fetch failed (exit ${fetch.exitCode})`);
         return "failed";
     }
-    if (!registered && repo.branch) {
-        const lsRemote = runGit(repoRoot, [
-            "ls-remote",
-            "--exit-code",
-            "--heads",
-            repo.url,
-            repo.branch,
-        ]);
-        if (lsRemote.exitCode === 2) {
-            log.error(`${repo.alias}: branch "${repo.branch}" not found on ${repo.url}. Push the branch upstream or fix the alias, then retry.`);
+    const branch = repo.branch ?? detectDefaultBranch(repoRoot, alias);
+    if (branch && !existsSync(worktreePath(repoRoot, alias, branch))) {
+        if (!addWorktree(repo, repoRoot, branch))
             return "failed";
+    }
+    runBareGit(repoRoot, alias, ["worktree", "prune"]);
+    log.success(`${alias}: updated`);
+    return "updated";
+}
+function unsyncRepo(repo, repoRoot, force) {
+    const aliasPath = aliasDir(repoRoot, repo.alias);
+    const barePath = bareDir(repoRoot, repo.alias);
+    const placeholderPath = gitPlaceholderPath(repoRoot, repo.alias);
+    const aliasExists = existsSync(aliasPath);
+    const bareExists = existsSync(barePath);
+    if (!aliasExists && !bareExists)
+        return "nothing-to-remove";
+    const worktrees = bareExists ? listExistingWorktrees(repoRoot, repo.alias) : [];
+    if (!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.`);
+                return "failed";
+            }
         }
-        if (!lsRemote.success && lsRemote.exitCode !== 2) {
-            log.warn(`${repo.alias}: branch existence check failed (exit ${lsRemote.exitCode}); proceeding with submodule add.`);
+    }
+    for (const wt of worktrees) {
+        const target = wt.branch === "(detached)" ? wt.relativePath : wt.branch;
+        if (!removeWorktree(repo, repoRoot, target, force)) {
+            return "failed";
         }
     }
-    const args = registered
-        ? ["submodule", "update", "--init", "--recursive", sourcePath]
-        : [
-            "submodule",
-            "add",
-            "--name",
-            repo.alias,
-            ...(repo.branch ? ["--branch", repo.branch] : []),
-            repo.url,
-            sourcePath,
-        ];
-    log.step(`git ${args.join(" ")}`);
-    const result = runGit(repoRoot, args, true);
-    if (result.success) {
-        log.success(`${repo.alias}: ${registered ? "updated" : "added"}`);
-        return registered ? "updated" : "added";
-    }
-    log.error(`${repo.alias}: submodule ${registered ? "update" : "add"} failed (exit ${result.exitCode})`);
-    if (!registered) {
-        const cleanup = removeSubmoduleArtifacts(repo, repoRoot, { force: true });
-        if (cleanup === "removed") {
-            log.info(`${repo.alias}: cleaned up partial submodule state. Retry once the upstream issue is resolved.`);
+    if (existsSync(barePath))
+        rmSync(barePath, { recursive: true, force: true });
+    if (existsSync(placeholderPath))
+        rmSync(placeholderPath);
+    try {
+        if (existsSync(aliasPath)) {
+            const remaining = readdirSync(aliasPath);
+            if (remaining.length === 0)
+                rmdirSync(aliasPath);
         }
     }
+    catch { }
+    return "removed";
+}
+function fetchRepo(repo, repoRoot) {
+    if (!existsSync(bareDir(repoRoot, repo.alias))) {
+        log.error(`${repo.alias}: not synced. Run "oms sync ${repo.alias}" first.`);
+        return "failed";
+    }
+    log.step(`${repo.alias}: git fetch origin --prune`);
+    const r = runBareGit(repoRoot, repo.alias, ["fetch", "origin", "--prune"], true);
+    if (r.success) {
+        log.success(`${repo.alias}: fetched`);
+        return "fetched";
+    }
+    log.error(`${repo.alias}: fetch failed (exit ${r.exitCode})`);
     return "failed";
 }
-function manageSubmodule(repo, repoRoot, command) {
-    const sourcePath = `sources/${repo.alias}`;
-    if (!isRegisteredSubmodule(repoRoot, sourcePath) || !isCheckedOutGitRepo(repoRoot, sourcePath)) {
-        log.error(`${repo.alias}: ${sourcePath} is not a checked-out source submodule. Run "oms sync ${repo.alias}" first.`);
+function resolveTargetWorktree(repo, repoRoot) {
+    const defaultBranch = repo.branch ?? detectDefaultBranch(repoRoot, repo.alias);
+    if (defaultBranch) {
+        const path = worktreePath(repoRoot, repo.alias, defaultBranch);
+        if (existsSync(path))
+            return { branch: defaultBranch, path };
+    }
+    const wts = listExistingWorktrees(repoRoot, repo.alias);
+    if (wts.length === 1) {
+        const only = wts[0];
+        return { branch: only.branch === "(detached)" ? only.relativePath : only.branch, path: only.path };
+    }
+    return null;
+}
+function pullRepo(repo, repoRoot) {
+    if (!existsSync(bareDir(repoRoot, repo.alias))) {
+        log.error(`${repo.alias}: not synced. Run "oms sync ${repo.alias}" first.`);
         return "failed";
     }
-    const sourceWorktree = join(repoRoot, sourcePath);
-    if (command === "push") {
-        const upstream = runGit(sourceWorktree, [
-            "rev-parse",
-            "--abbrev-ref",
-            "--symbolic-full-name",
-            "@{u}",
-        ]);
-        if (!upstream.success) {
-            log.error(`${repo.alias}: git push requires the current branch to have an upstream. Set it manually before pushing.`);
-            return "failed";
-        }
+    const target = resolveTargetWorktree(repo, repoRoot);
+    if (!target) {
+        log.error(`${repo.alias}: cannot determine which worktree to pull. Use "oms worktree list ${repo.alias}".`);
+        return "failed";
     }
-    const args = MANAGE_GIT_ARGS[command];
-    log.step(`${repo.alias}: git ${args.join(" ")}`);
-    const result = runGit(sourceWorktree, args, true);
-    if (result.success) {
-        const operation = RESULT_BY_COMMAND[command];
-        log.success(`${repo.alias}: ${operation}`);
-        return operation;
+    log.step(`${repo.alias}/${target.branch}: git pull --ff-only`);
+    const r = runGit(target.path, ["pull", "--ff-only"], true);
+    if (r.success) {
+        log.success(`${repo.alias}/${target.branch}: pulled`);
+        return "pulled";
     }
-    log.error(`${repo.alias}: git ${command} failed (exit ${result.exitCode})`);
+    log.error(`${repo.alias}/${target.branch}: pull failed (exit ${r.exitCode})`);
+    return "failed";
+}
+function pushRepo(repo, repoRoot) {
+    if (!existsSync(bareDir(repoRoot, repo.alias))) {
+        log.error(`${repo.alias}: not synced. Run "oms sync ${repo.alias}" first.`);
+        return "failed";
+    }
+    const target = resolveTargetWorktree(repo, repoRoot);
+    if (!target) {
+        log.error(`${repo.alias}: cannot determine which worktree to push. Use "oms worktree list ${repo.alias}".`);
+        return "failed";
+    }
+    const upstream = runGit(target.path, [
+        "rev-parse",
+        "--abbrev-ref",
+        "--symbolic-full-name",
+        "@{u}",
+    ]);
+    if (!upstream.success) {
+        log.error(`${repo.alias}/${target.branch}: git push requires an upstream. Set it manually before pushing.`);
+        return "failed";
+    }
+    log.step(`${repo.alias}/${target.branch}: git push`);
+    const r = runGit(target.path, ["-c", "push.autoSetupRemote=false", "push"], true);
+    if (r.success) {
+        log.success(`${repo.alias}/${target.branch}: pushed`);
+        return "pushed";
+    }
+    log.error(`${repo.alias}/${target.branch}: push failed (exit ${r.exitCode})`);
     return "failed";
 }
 function printSummary(results) {
@@ -350,10 +572,13 @@ async function runSync(aliases, options) {
         printList(repos);
         return 0;
     }
+    if (abortOnLegacy(repoRoot, repos))
+        return 1;
     const picked = await selectRepos(repos, aliases, options, "sync");
     if (!picked || picked.length === 0)
         return 1;
-    const results = picked.map((repo) => syncSubmodule(repo, repoRoot));
+    ensureGitignore(repoRoot);
+    const results = picked.map((repo) => syncRepo(repo, repoRoot));
     if (results.length > 1 || options.all)
         printSummary(results);
     return exitFromResults(results);
@@ -363,10 +588,13 @@ async function runManage(command, aliases, options) {
     if (!loaded)
         return 1;
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacy(repoRoot, repos))
+        return 1;
     const picked = await selectRepos(repos, aliases, options, command);
     if (!picked || picked.length === 0)
         return 1;
-    const results = picked.map((repo) => manageSubmodule(repo, repoRoot, command));
+    const fn = command === "fetch" ? fetchRepo : command === "pull" ? pullRepo : pushRepo;
+    const results = picked.map((repo) => fn(repo, repoRoot));
     if (results.length > 1 || options.all)
         printSummary(results);
     return exitFromResults(results);
@@ -376,14 +604,16 @@ async function runUnsync(aliases, options) {
     if (!loaded)
         return 1;
     const { repos, repoRoot } = loaded;
+    if (abortOnLegacy(repoRoot, repos))
+        return 1;
     const picked = await selectRepos(repos, aliases, options, "unsync");
     if (!picked || picked.length === 0)
         return 1;
     const results = picked.map((repo) => {
         log.step(`${repo.alias}: unsync`);
-        const outcome = removeSubmoduleArtifacts(repo, repoRoot, { force: options.force });
+        const outcome = unsyncRepo(repo, repoRoot, options.force ?? false);
         if (outcome === "removed") {
-            log.success(`${repo.alias}: unsynced (commit staged changes in .gitmodules and sources/${repo.alias} to finalize)`);
+            log.success(`${repo.alias}: unsynced`);
             return "unsynced";
         }
         if (outcome === "nothing-to-remove") {
@@ -396,19 +626,160 @@ async function runUnsync(aliases, options) {
         printSummary(results);
     return exitFromResults(results);
 }
-async function runDoctor() {
+async function runWorktreeAdd(alias, branch) {
+    const loaded = loadRepos();
+    if (!loaded)
+        return 1;
+    const { repos, repoRoot } = loaded;
+    if (abortOnLegacy(repoRoot, repos))
+        return 1;
+    const repo = repos.find((r) => r.alias === alias);
+    if (!repo) {
+        log.error(`Unknown alias "${alias}". Use "oms sync --list" to see registered aliases.`);
+        return 1;
+    }
+    if (!existsSync(bareDir(repoRoot, alias))) {
+        log.error(`${alias}: not synced. Run "oms sync ${alias}" first.`);
+        return 1;
+    }
+    if (existsSync(worktreePath(repoRoot, alias, branch))) {
+        log.error(`${alias}: worktree for ${branch} already exists at sources/${alias}/${branch}.`);
+        return 1;
+    }
+    log.step(`${alias}: git fetch origin --prune (refresh before add)`);
+    runBareGit(repoRoot, alias, ["fetch", "origin", "--prune"], true);
+    if (!addWorktree(repo, repoRoot, branch))
+        return 2;
+    log.success(`${alias}: added worktree for ${branch}`);
+    return 0;
+}
+async function runWorktreeList(alias) {
+    const loaded = loadRepos();
+    if (!loaded)
+        return 1;
+    const { repos, repoRoot } = loaded;
+    if (abortOnLegacy(repoRoot, repos))
+        return 1;
+    const targets = alias ? repos.filter((r) => r.alias === alias) : repos;
+    if (alias && targets.length === 0) {
+        log.error(`Unknown alias "${alias}".`);
+        return 1;
+    }
+    const rows = [];
+    for (const repo of targets) {
+        if (!existsSync(bareDir(repoRoot, repo.alias))) {
+            rows.push({ alias: repo.alias, branch: "(not synced)", path: "-" });
+            continue;
+        }
+        const wts = listExistingWorktrees(repoRoot, repo.alias);
+        if (wts.length === 0) {
+            rows.push({ alias: repo.alias, branch: "(no worktrees)", path: "-" });
+            continue;
+        }
+        for (const wt of wts) {
+            rows.push({
+                alias: repo.alias,
+                branch: wt.branch,
+                path: `sources/${repo.alias}/${wt.relativePath}`,
+            });
+        }
+    }
+    const aliasW = Math.max("ALIAS".length, ...rows.map((r) => r.alias.length));
+    const branchW = Math.max("BRANCH".length, ...rows.map((r) => r.branch.length));
+    console.log(dim(`${pad("ALIAS", aliasW)}  ${pad("BRANCH", branchW)}  PATH`));
+    for (const r of rows) {
+        console.log(`${pad(r.alias, aliasW)}  ${pad(r.branch, branchW)}  ${r.path}`);
+    }
+    return 0;
+}
+async function runWorktreeRemove(alias, branch, options) {
     const loaded = loadRepos();
     if (!loaded)
         return 1;
-    log.success(`Workspace root: ${loaded.repoRoot}`);
-    log.success(`sources.yaml: ${loaded.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()}`);
+    const { repos, repoRoot } = loaded;
+    if (abortOnLegacy(repoRoot, repos))
+        return 1;
+    const repo = repos.find((r) => r.alias === alias);
+    if (!repo) {
+        log.error(`Unknown alias "${alias}".`);
+        return 1;
+    }
+    const wtPath = worktreePath(repoRoot, alias, branch);
+    if (!existsSync(wtPath)) {
+        log.info(`${alias}: no worktree for ${branch}`);
         return 0;
     }
-    log.error("git: not found");
-    return 1;
+    if (!options.force) {
+        const status = runGit(wtPath, ["status", "--porcelain"]);
+        if (status.success && status.stdout.trim().length > 0) {
+            log.error(`${alias}/${branch}: has uncommitted changes. Commit, stash, or pass --force.`);
+            return 2;
+        }
+    }
+    if (!removeWorktree(repo, repoRoot, branch, options.force ?? false))
+        return 2;
+    log.success(`${alias}: removed worktree for ${branch}`);
+    return 0;
+}
+async function runDoctor() {
+    const loaded = loadRepos();
+    if (!loaded)
+        return 1;
+    const { repos, repoRoot } = loaded;
+    log.success(`Workspace root: ${repoRoot}`);
+    log.success(`sources.yaml: ${repos.length} repo(s) configured`);
+    const git = spawnSync("git", ["--version"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    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".');
+        warnings++;
+    }
+    const gi = join(repoRoot, ".gitignore");
+    const giHasSources = existsSync(gi)
+        && readFileSync(gi, "utf8")
+            .split("\n")
+            .some((l) => l.trim() === GITIGNORE_ENTRY || l.trim() === `/${GITIGNORE_ENTRY}`);
+    if (!giHasSources) {
+        log.warn(`.gitignore does not exclude ${GITIGNORE_ENTRY}. Run "oms sync" to add it automatically.`);
+        warnings++;
+    }
+    for (const repo of repos) {
+        const bare = bareDir(repoRoot, repo.alias);
+        if (!existsSync(bare)) {
+            log.info(`${repo.alias}: not synced`);
+            continue;
+        }
+        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}'`);
+            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`);
+            warnings++;
+        }
+    }
+    return warnings > 0 ? 2 : 0;
 }
 function readJson(path) {
     if (!existsSync(path))
@@ -429,23 +800,32 @@ async function exitWith(action) {
     }
 }
 const exitHelp = "\nExit codes: 0 ok | 1 usage/config error | 2 one or more git operations failed.";
-const commandNames = new Set(["doctor", "sync", "fetch", "pull", "push", "unsync", "help"]);
+const commandNames = new Set([
+    "doctor",
+    "sync",
+    "fetch",
+    "pull",
+    "push",
+    "unsync",
+    "worktree",
+    "help",
+]);
 const program = new Command();
 program
     .name("oms")
-    .description("Manage source repositories listed in sources.yaml under sources/<alias>/.")
+    .description("Manage source repositories listed in sources.yaml as bare clones + worktrees under sources/<alias>/.")
     .version(readPackageVersion())
     .addHelpText("after", exitHelp);
 program
     .command("doctor")
-    .description("Check sources.yaml configuration and git availability.")
+    .description("Check sources.yaml, git availability, bare-clone state, and .gitignore for each registered alias.")
     .addHelpText("after", exitHelp)
     .action(async () => {
     await exitWith(runDoctor());
 });
 program
     .command("sync")
-    .description("Sync sources.yaml entries into git submodules under sources/<alias>/.")
+    .description("Bare-clone each registered repo into sources/<alias>/.bare and create the baseline worktree at sources/<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")
@@ -455,7 +835,7 @@ program
 });
 program
     .command("fetch")
-    .description("Run git fetch --all --prune inside checked-out source submodule worktrees.")
+    .description("Run git fetch origin --prune in each bare clone.")
     .argument("[aliases...]", "repo aliases to fetch (omit for interactive multi-select)")
     .option("--all", "fetch every registered source repo")
     .addHelpText("after", exitHelp)
@@ -464,7 +844,7 @@ program
 });
 program
     .command("pull")
-    .description("Run git pull --ff-only inside checked-out source submodule worktrees; requires branch/upstream.")
+    .description("Run git pull --ff-only in the baseline worktree of each selected alias; requires upstream.")
     .argument("[aliases...]", "repo aliases to pull (omit for interactive multi-select)")
     .option("--all", "pull every registered source repo")
     .addHelpText("after", exitHelp)
@@ -473,7 +853,7 @@ program
 });
 program
     .command("push")
-    .description("Run git push inside explicit source submodule worktrees; no --all, force, or upstream setup.")
+    .description("Run git push in the baseline worktree of each explicitly listed alias; no --all, force, or upstream setup.")
     .argument("<aliases...>", "repo aliases to push")
     .addHelpText("after", exitHelp)
     .action(async (aliases) => {
@@ -481,14 +861,45 @@ program
 });
 program
     .command("unsync")
-    .description("Remove submodule registration and worktree (keeps sources.yaml entry). Leaves staged changes in .gitmodules and the submodule path to commit.")
+    .description("Remove all worktrees and the bare clone for each alias (keeps sources.yaml 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 the source worktree")
+    .option("--force", "discard uncommitted changes in worktrees")
     .addHelpText("after", exitHelp)
     .action(async (aliases, options) => {
     await exitWith(runUnsync(aliases, options));
 });
+const worktreeCmd = program
+    .command("worktree")
+    .description("Manage additional worktrees for a synced source repo.")
+    .addHelpText("after", exitHelp);
+worktreeCmd
+    .command("add")
+    .description("Create a worktree for <branch> at sources/<alias>/<branch>/.")
+    .argument("<alias>", "registered source alias")
+    .argument("<branch>", "branch name (may include slashes)")
+    .addHelpText("after", exitHelp)
+    .action(async (alias, branch) => {
+    await exitWith(runWorktreeAdd(alias, branch));
+});
+worktreeCmd
+    .command("list")
+    .description("List existing worktrees for the given alias (or all aliases).")
+    .argument("[alias]", "registered source alias")
+    .addHelpText("after", exitHelp)
+    .action(async (alias) => {
+    await exitWith(runWorktreeList(alias));
+});
+worktreeCmd
+    .command("remove")
+    .description("Remove the worktree at sources/<alias>/<branch>.")
+    .argument("<alias>", "registered source alias")
+    .argument("<branch>", "branch name (may include slashes)")
+    .option("--force", "discard uncommitted changes")
+    .addHelpText("after", exitHelp)
+    .action(async (alias, branch, options) => {
+    await exitWith(runWorktreeRemove(alias, branch, options));
+});
 const requestedCommand = process.argv[2];
 if (requestedCommand && !requestedCommand.startsWith("-") && !commandNames.has(requestedCommand)) {
     console.error(`error: unknown command '${requestedCommand}'`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-space",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "CLI for managing external source repositories declared in sources.yaml.",
   "license": "MIT",
   "homepage": "https://github.com/divlook/oh-my-space",
@@ -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",