oh-my-space 0.5.0 → 0.7.0

package/README.md

@@ -1,15 +1,26 @@
 # oh-my-space
 
-`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>/`.
+`oh-my-space` provides the `oms` CLI for managing external source repositories declared in `oms.yaml`. Each registered repo is checked out as a **git submodule** at `oms/<alias>/`, so its pinned commit, branch, and history are tracked natively by your project — and `oms` wraps the submodule foot-guns (detached HEAD, remote-first branch creation, easy-to-miss pointer moves) behind a small, friendly command set.
 
 Package name: `oh-my-space`
 
 Command name: `oms`
 
+## Why submodules + a wrapper
+
+Git submodules give you three things for free: a **reproducible pin** (the parent records each source's exact commit), **visibility** (`git status` shows when a pointer moved), and **history** (the pointer travels with your commits). What they make awkward is day-to-day branch work. `oms` keeps the native benefits and removes the friction:
+
+- **Create a new branch locally, with no remote precondition.** `oms checkout <alias> <branch>` makes the branch right away even if it does not exist on the remote yet. The remote branch is created lazily on your first `oms push`.
+- **Always on a branch, never detached.** `oms sync` attaches the baseline branch at the pinned commit instead of leaving a detached HEAD.
+- **Pointer moves stay visible.** `oms pull` / `oms push` stage the updated gitlink in the parent so you can see and commit it; `oms status` surfaces drift.
+
+> Sharing a pin with your team still requires pushing the commit — that is inherent to any pinning model. `oms` removes the *local* friction; it cannot make an unpushed commit reproducible for others.
+
 ## Requirements
 
 - [Node.js](https://nodejs.org) `>=20.19.0` for running `oms`; development uses the version in `.nvmrc` (`24`)
-- git `>=2.40` (worktree `--track -B` flow)
+- git `>=2.40` (`git switch` + submodule commands)
+- The workspace must be a git repository (`git init`), since sources are submodules of it.
 
 For local development:
 
@@ -32,67 +43,72 @@ bun install -g oh-my-space
 
 ## Quick start
 
-Run `oms init` to scaffold a starter `oms.yaml` (also adds `oms/` to `.gitignore`), or create one by hand in your project root:
+Run `oms init` to scaffold a starter `oms.yaml`, or create one by hand in your project root:
 
 ```yaml
 # yaml-language-server: $schema=https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json
 repos:
   - alias: api
-    url: git@github.com:example/api.git
+    remotes:
+      origin: git@github.com:example/api.git
     branch: main
   - alias: web
-    url: git@github.com:example/web.git
+    remotes:
+      origin: git@github.com:example/web.git
+      upstream: git@github.com:upstream/web.git
 ```
 
-Sync and explore:
+Sync and work:
 
 ```bash
-oms init                           # scaffold a starter oms.yaml
-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
-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
+oms init                          # scaffold a starter oms.yaml
+oms doctor                        # validate oms.yaml + submodule state
+oms sync --list                   # list registered source repos
+oms sync <alias>...               # add/initialize submodules on their baseline branch
+oms sync --all                    # sync every registered source repo
+oms status                        # branch / pointer / dirty / ahead-behind per submodule
+oms checkout <alias> <branch>     # switch (or create a brand-new local branch)
+oms push <alias>...               # push the branch (lazy remote) + stage the pointer
+oms push <alias> --remote upstream  # target a specific remote (repeatable; defaults to origin)
+oms unsync <alias>...             # deinitialize and remove a submodule
 ```
 
-`oms sync` adds `oms/` to your workspace `.gitignore` on first run; the bare clone and worktrees stay out of your project history.
+A typical new-branch flow:
+
+```bash
+oms checkout api feature/login    # local branch, no remote needed
+# ... edit, commit inside oms/api ...
+oms push api                      # creates origin/feature/login and stages the pointer
+git add oms/api && git commit     # record the pointer in your project history
+```
 
 ## Layout
 
-For an alias `api` with the baseline branch `main` and an extra `feature/foo` worktree:
+For an alias `api` checked out on `main`:
 
 ```
+.gitmodules            # registers oms/api -> origin url, branch
 oms/
-└── api/
-    ├── .bare/             # git clone --bare result
-    ├── .git               # 'gitdir: ./.bare' placeholder
-    ├── main/              # worktree for main (upstream: origin/main)
-    └── feature/
-        └── foo/           # worktree for feature/foo
+└── api/               # git submodule (a normal working tree, on a branch)
 ```
 
-Slash-containing branch names are kept nested as directories.
+`.gitmodules` and the `oms/<alias>` gitlink are part of your project history. Submodules must **not** be gitignored; `oms sync` removes a stale `oms/` entry from `.gitignore` if a previous version added one.
 
 ## Managing source repositories
 
-`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.
+`oms.yaml` declares each source repo with `alias`, a `remotes` mapping (which must include `origin`), and optional `branch` (the baseline).
 
 | Command | Runs in | Does | Notes |
 | --- | --- | --- | --- |
-| `oms init` | current directory | Writes a starter `oms.yaml` and adds `oms/` to `.gitignore`. | Refuses if `oms.yaml` exists; use `--force` to overwrite. |
-| `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. |
-| `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. |
+| `oms init` | current directory | Writes a starter `oms.yaml`. | Refuses if `oms.yaml` exists; use `--force`. Does not gitignore `oms/`. |
+| `oms doctor` | project root or child path | Checks `oms.yaml`, git availability, that the workspace is a git repo, and each alias's submodule state. | Returns exit 2 if any warning is raised. |
+| `oms sync <alias>` / `--all` | workspace root | Registers missing repos with `git submodule add`, initializes registered-but-uninitialized ones, fetches, and attaches the baseline branch. | Reproduces the recorded pointer on a fresh clone. |
+| `oms status [alias...]` / `--all` | anywhere under root | Prints branch, pointer state (`ok`/`moved`/`uninit`), dirtiness, and ahead/behind for each submodule. | `moved` means the working commit differs from the recorded pointer — stage/commit it. |
+| `oms checkout <alias> <branch>` | workspace root | `git switch` to the branch; creates it locally if it exists nowhere yet (no remote required). | `--from <ref>` sets the start point for a new branch. |
+| `oms fetch ...` | workspace root | `git fetch <remote> --prune` in each submodule. | `--remote <name>` (repeatable) picks the remote(s); omit to choose interactively, defaults to `origin`. |
+| `oms pull ...` | workspace root | `git pull --ff-only <remote>` on each submodule's current branch, then stages the moved pointer. | Requires the submodule to be on a branch. `--remote <name>` selects a single remote (defaults to `origin`). |
+| `oms push <alias>...` | workspace root | `git push <remote> <branch>` (creating the remote branch on first push), then stages the moved pointer. | `--remote <name>` (repeatable) picks the remote(s), defaults to `origin`; upstream is set only for `origin`. `--commit` also commits the pointer update in the parent. |
+| `oms unsync <alias>` / `--all` | workspace root | `git submodule deinit` + `git rm` for the alias; drops an empty `.gitmodules`. | Keeps the `oms.yaml` entry. Use `--force` to discard uncommitted changes. |
 
 ## `oms.yaml` format
 
@@ -100,27 +116,31 @@ Slash-containing branch names are kept nested as directories.
 # yaml-language-server: $schema=https://raw.githubusercontent.com/divlook/oh-my-space/main/oms.schema.json
 repos:
   - alias: service-a
-    url: git@github.com:example/service-a.git
+    remotes:
+      origin: git@github.com:example/service-a.git
     branch: main
   - alias: docs
-    url: https://github.com/example/docs.git
+    remotes:
+      origin: https://github.com/example/docs.git
+      upstream: https://github.com/upstream/docs.git
 ```
 
 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; when omitted the bare clone's default branch is used as the baseline worktree.
+- `remotes` is required and must include an `origin` entry; each value is a clonable git URL. `origin` becomes the submodule's primary remote, and additional remotes are configured on `oms sync`.
+- `branch` is optional; when omitted the remote's default branch is used as the baseline.
 
 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).
 
 ## Migrating between versions
 
-자세한 마이그레이션 절차는 [`docs/migrations/`](./docs/migrations/) 에 버전별로 정리되어 있습니다.
+Detailed migration steps are organized per version under [`docs/migrations/`](./docs/migrations/).
 
-- [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 로 데이터 모델 전환
+- [0.5.x → 0.6.0](./docs/migrations/0.5.x-to-0.6.0.md) — switches the data model from bare clone + worktrees back to git submodules
+- [0.3.x → 0.4.0](./docs/migrations/0.3.x-to-0.4.0.md) — renames `sources.yaml`/`sources/` to `oms.yaml`/`oms/`
+- [0.2.x → 0.3.0](./docs/migrations/0.2.x-to-0.3.0.md) — (historical) switched submodules to bare clone + worktrees
 
 ## License
 

package/dist/build-info.json

@@ -0,0 +1 @@
+{"commit":"23dd80c9eef2a1ba62b193a9497f564dbe116739"}