unirepo-cli 0.2.0 → 0.3.0

package/README.md

@@ -4,63 +4,102 @@
 [![CI](https://github.com/Poko18/unirepo/actions/workflows/ci.yml/badge.svg)](https://github.com/Poko18/unirepo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**The workspace for cross-repo coding.**
+### One workspace to refactor your whole stack in one go
 
-unirepo turns a set of GitHub repos into a single unified workspace. Edit code across any of them, commit once, and push updates back to their original repos — all in one branch.
+Work across multiple repos like they’re one. Unirepo turns multiple GitHub repositories into a single unified workspace. Edit backend, frontend, and shared code in one tree, commit from one place, and push changes back to each repo using the same branch.
 
-Built for the era of AI coding agents: give your agent one place to work, and let it refactor, ship features, and update shared APIs across your entire stack.
+### Built for AI coding agents
 
+AI agents need full context to make correct changes—not one repo at a time. Unirepo gives them a single workspace to refactor your entire stack, keep changes consistent, and push updates back to each repo.
 
-## Why unirepo?
+### Example task
 
-**Before unirepo:**
+You need to update:
 
-```
-~/work/api        ← clone, checkout branch, edit
-~/work/web        ← clone, checkout same branch, edit
-~/work/shared     ← clone, checkout same branch, edit
-# remember to push all three, open three PRs
-```
-
-**With unirepo:**
-
-```
-~/work/my-workspace/
-├── api/      ← edit
-├── web/      ← edit
-└── shared/   ← edit
-# one commit, one push — all three repos updated
-```
+- `api/` for a new endpoint
+- `web/` for the UI
+- `shared/` for shared types
 
+<table>
+<tr>
+<td width="50%" valign="top">
 
-## Quick Start
+**Without `unirepo`**
 
 ```bash
-npx unirepo-cli init my-workspace \
-  https://github.com/org/api.git \
-  https://github.com/org/web.git
-```
+# clone and branch in each repo
+git clone git@github.com:org/api.git
+git clone git@github.com:org/web.git
+git clone git@github.com:org/shared.git
+
+cd api
+git checkout -b feature-auth
+cd ../web
+git checkout -b feature-auth
+cd ../shared
+git checkout -b feature-auth
+
+# edit in 3 separate checkouts
+
+# commit in each repo
+cd ../api
+git add .
+git commit -m "feat: add auth"
+cd ../web
+git add .
+git commit -m "feat: add auth UI"
+cd ../shared
+git add .
+git commit -m "feat: add auth types"
+
+# push from each repo
+cd ../api
+git push -u origin feature-auth
+cd ../web
+git push -u origin feature-auth
+cd ../shared
+git push -u origin feature-auth
+```
+
+</td>
+<td width="50%" valign="top">
+
+**With `unirepo`**
 
-This creates:
+```bash
+# create one workspace and one branch
+unirepo init my-workspace <repo...>
+cd my-workspace
+unirepo branch feature-auth
 
-```
-my-workspace/
-├── api/          ← from github.com/org/api
-├── web/          ← from github.com/org/web
-├── AGENTS.md     ← workflow guide for humans and agents
-└── .gitignore
-```
+# edit api/, web/, and shared/ together
 
-Then work across repos as if they were one:
+# commit once from the workspace
+git add .
+git commit -m "feat: add auth flow"
 
-```bash
-cd my-workspace
-# edit files in api/ and web/
-git add . && git commit -m "feat: update shared types"
+# push changed subtrees
 unirepo push
 ```
 
-That's it. Each subtree gets pushed to its upstream repo automatically.
+</td>
+</tr>
+</table>
+
+## Same workflow, fewer commands
+
+`unirepo` keeps your upstream repos separate while removing:
+
+- Repo and branch juggling  
+- Repeated setup and commands  
+- Context switching  
+- Inconsistent cross-repo changes  
+
+It enables:
+
+- One place to see the full change  
+- Safe cross-repo refactors  
+- A single workspace for humans and AI
 
 
 ## Install
@@ -82,6 +121,17 @@ npx unirepo-cli <command>
 ```
 
 
+## Why it works well for agents
+
+AI coding agents work best when they can see the full change at once.
+
+- Update backend, frontend, and shared contracts in one pass
+- Commit coordinated changes from one repo
+- Check affected subtrees with `unirepo status`
+- Push only changed subtrees with `unirepo push`
+- Reuse the generated `AGENTS.md` workflow guide
+
+
 ## Commands
 
 | Command | Description |
@@ -92,40 +142,7 @@ npx unirepo-cli <command>
 | `status` | Show subtrees, branches, and what changed |
 | `branch [name]` | Create or show the current push branch |
 | `push [subtree...]` | Push changed subtrees upstream |
-| `version` | Show CLI version |
-
-
-## Workflow
-
-A typical session looks like this:
-
-```bash
-# 1. Create a branch for your work
-unirepo branch feature-auth
-
-# 2. Pull latest upstream changes
-unirepo pull
-
-# 3. Edit files across repos
-vim api/src/auth.js web/src/login.tsx
-
-# 4. Commit in the monorepo
-git add . && git commit -m "feat: add OAuth flow"
-
-# 5. Check what will be pushed
-unirepo status
-unirepo push --dry-run
-
-# 6. Push to upstream repos
-unirepo push
-
-# 7. Open one PR per upstream repo
-```
-
-The branch name you create in the workspace is reused when pushing to each upstream repo.
-
 
-## Command Reference
 
 ### init
 
@@ -156,13 +173,14 @@ Adds a repo to an existing workspace. The directory name defaults to the repo na
 ### pull
 
 ```bash
-unirepo pull [subtree...]
+unirepo pull [subtree...] [--prefix <name>]
 ```
 
-Pulls upstream changes. Without arguments, pulls all tracked subtrees.
+Pulls upstream changes. Without arguments, pulls all tracked subtrees. When you use `--branch` without naming a subtree, `unirepo` skips tracked subtrees that do not have that upstream branch.
 
 | Flag | Effect |
 | --- | --- |
+| `--prefix <name>` | Pull only one tracked subtree |
 | `--branch <name>` | Pull a specific upstream branch |
 | `--full-history` | Pull full history instead of squash |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unirepo-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI tool for creating and managing git-subtree monorepos — run your agents across repos",
   "type": "module",
   "bin": {

package/src/commands/add.js

@@ -1,4 +1,4 @@
-import { git, detectDefaultBranch, extractRepoName } from '../git.js';
+import { git, detectDefaultBranch, extractRepoName, setConfiguredSubtreeBranch } from '../git.js';
 import { validateGitSubtree, validateUrls, validateInsideMonorepo, validateNameAvailable, validateReachable } from '../validate.js';
 import * as ui from '../ui.js';
 
@@ -39,6 +39,8 @@ export async function runAdd({ url, prefix, branch, fullHistory }) {
     git(`subtree add --squash --prefix="${name}" "${name}" "${upstreamBranch}"`, { cwd });
   }
 
+  setConfiguredSubtreeBranch(cwd, name, upstreamBranch);
+
   // ── Done ─────────────────────────────────────────────────────────────────
   ui.step(4, 4, 'Done!');
   ui.addSummary(name, url);

package/src/commands/branch.js

@@ -1,4 +1,4 @@
-import { git, getCurrentBranch, getSubtreePrefixes, getRemoteBranch } from '../git.js';
+import { git, getCurrentBranch, getSubtreePrefixes, getTrackedSubtreeBranch } from '../git.js';
 import { validateInsideMonorepo } from '../validate.js';
 import * as ui from '../ui.js';
 
@@ -17,7 +17,7 @@ export async function runBranch({ name }) {
     ui.info(`Current branch: ${currentBranch}`);
     ui.blank();
     for (const s of subtrees) {
-      const upstream = getRemoteBranch(cwd, s.name) || 'unknown';
+      const upstream = getTrackedSubtreeBranch(cwd, s.name) || 'unknown';
       ui.info(`  ${s.name}  upstream: ${upstream}  push target: ${currentBranch}`);
     }
     ui.blank();

package/src/commands/init.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
 import { resolve, join } from 'node:path';
-import { git, detectDefaultBranch, extractRepoName } from '../git.js';
+import { git, detectDefaultBranch, extractRepoName, setConfiguredSubtreeBranch } from '../git.js';
 import { validateGitSubtree, validateUrls, validateNoDuplicateNames, validateReachable } from '../validate.js';
 import { AGENTS_MD, GITIGNORE } from '../templates.js';
 import * as ui from '../ui.js';
@@ -79,6 +79,8 @@ export async function runInit({ dir, repos, fullHistory }) {
         git(`subtree add --squash --prefix="${name}" "${name}" "${branch}"`, { cwd: absDir });
       }
 
+      setConfiguredSubtreeBranch(absDir, name, branch);
+
       ui.success(`${name} imported`);
     }
   } catch (err) {

package/src/commands/pull.js

@@ -1,7 +1,53 @@
-import { git, getRemoteBranch, getSubtreePrefixes } from '../git.js';
+import { git, getSubtreePrefixes, getTrackedSubtreeBranch, hasRemoteBranch, setConfiguredSubtreeBranch } from '../git.js';
 import { validateGitSubtree, validateInsideMonorepo } from '../validate.js';
 import * as ui from '../ui.js';
 
+export function selectPullSubtrees(allPrefixes, requestedSubtrees) {
+  if (!requestedSubtrees || requestedSubtrees.length === 0) {
+    return allPrefixes;
+  }
+
+  const prefixNames = new Set(allPrefixes.map((prefix) => prefix.name));
+  for (const name of requestedSubtrees) {
+    if (!prefixNames.has(name)) {
+      throw new Error(`"${name}" is not a tracked subtree. Run "unirepo status" to see available subtrees.`);
+    }
+  }
+
+  return allPrefixes.filter((prefix) => requestedSubtrees.includes(prefix.name));
+}
+
+export function planPullTargets({
+  allPrefixes,
+  requestedSubtrees,
+  branch,
+  hasRemoteBranchFn = () => true,
+}) {
+  const explicitSelection = Boolean(requestedSubtrees && requestedSubtrees.length > 0);
+  const selectedPrefixes = selectPullSubtrees(allPrefixes, requestedSubtrees);
+
+  if (!branch || explicitSelection) {
+    return { toPull: selectedPrefixes, skipped: [] };
+  }
+
+  const toPull = [];
+  const skipped = [];
+
+  for (const prefix of selectedPrefixes) {
+    if (hasRemoteBranchFn(prefix.name, branch)) {
+      toPull.push(prefix);
+    } else {
+      skipped.push(prefix);
+    }
+  }
+
+  return { toPull, skipped };
+}
+
+export function resolvePullUpstreamBranch({ requestedBranch, trackedBranch }) {
+  return requestedBranch || trackedBranch || 'main';
+}
+
 export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory }) {
   const cwd = process.cwd();
 
@@ -12,32 +58,38 @@ export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory
   validateInsideMonorepo(cwd);
 
   const allPrefixes = getSubtreePrefixes(cwd);
-  let toPull;
-
-  if (requestedSubtrees && requestedSubtrees.length > 0) {
-    const prefixNames = new Set(allPrefixes.map((prefix) => prefix.name));
-    for (const name of requestedSubtrees) {
-      if (!prefixNames.has(name)) {
-        throw new Error(`"${name}" is not a tracked subtree. Run "unirepo status" to see available subtrees.`);
-      }
-    }
-    toPull = allPrefixes.filter((prefix) => requestedSubtrees.includes(prefix.name));
-  } else {
-    toPull = allPrefixes;
-  }
+  const { toPull, skipped } = planPullTargets({
+    allPrefixes,
+    requestedSubtrees,
+    branch,
+    hasRemoteBranchFn: (remoteName, branchName) => hasRemoteBranch(cwd, remoteName, branchName),
+  });
 
   if (toPull.length === 0) {
-    ui.info('No tracked subtrees found. Nothing to pull.');
+    if (branch && skipped.length > 0) {
+      ui.info(`No tracked subtrees have upstream branch "${branch}". Nothing to pull.`);
+    } else {
+      ui.info('No tracked subtrees found. Nothing to pull.');
+    }
     ui.blank();
     return;
   }
 
+  if (skipped.length > 0) {
+    ui.warning(`Skipping ${skipped.map((prefix) => prefix.name).join(', ')}: no upstream branch "${branch}"`);
+    ui.blank();
+  }
+
   let succeeded = 0;
   let failed = 0;
 
   for (let i = 0; i < toPull.length; i++) {
     const prefix = toPull[i];
-    const upstreamBranch = branch || getRemoteBranch(cwd, prefix.name) || 'main';
+    const trackedBranch = getTrackedSubtreeBranch(cwd, prefix.name);
+    const upstreamBranch = resolvePullUpstreamBranch({
+      requestedBranch: branch,
+      trackedBranch,
+    });
     const squashFlag = fullHistory ? '' : '--squash ';
 
     ui.repoStep(i + 1, toPull.length, prefix.name, 'Pulling');
@@ -46,6 +98,7 @@ export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory
 
     try {
       git(`subtree pull ${squashFlag}--prefix="${prefix.name}" "${prefix.name}" "${upstreamBranch}"`, { cwd });
+      setConfiguredSubtreeBranch(cwd, prefix.name, upstreamBranch);
       ui.success(`${prefix.name} pulled`);
       succeeded++;
     } catch (err) {
@@ -56,10 +109,12 @@ export async function runPull({ subtrees: requestedSubtrees, branch, fullHistory
     ui.blank();
   }
 
-  if (failed === 0) {
+  if (failed === 0 && skipped.length === 0) {
     ui.success(`All ${succeeded} subtree(s) pulled`);
+  } else if (failed === 0) {
+    ui.success(`${succeeded} subtree(s) pulled, ${skipped.length} skipped`);
   } else {
-    ui.warning(`${succeeded} pulled, ${failed} failed`);
+    ui.warning(`${succeeded} pulled, ${failed} failed${skipped.length > 0 ? `, ${skipped.length} skipped` : ''}`);
   }
   ui.blank();
-}
+}

package/src/commands/status.js

@@ -1,4 +1,4 @@
-import { getCurrentBranch, getSubtreePrefixes, getChangedSubtrees, getRemoteBranch } from '../git.js';
+import { getCurrentBranch, getSubtreePrefixes, getChangedSubtrees, getTrackedSubtreeBranch } from '../git.js';
 import { validateInsideMonorepo } from '../validate.js';
 import * as ui from '../ui.js';
 
@@ -15,7 +15,7 @@ export async function runStatus({ json }) {
   const subtrees = prefixes.map((p) => ({
     name: p.name,
     url: p.url,
-    upstream: getRemoteBranch(cwd, p.name) || 'unknown',
+    upstream: getTrackedSubtreeBranch(cwd, p.name) || 'unknown',
     pushBranch: branch,
     changed: changedNames.has(p.name),
   }));

package/src/git.js

@@ -2,6 +2,14 @@ import { execSync } from 'node:child_process';
 import { readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
+function quoteShellArg(value) {
+  return JSON.stringify(value);
+}
+
+function getSubtreeBranchConfigKey(prefixName) {
+  return `unirepo.subtree.${prefixName}.branch`;
+}
+
 /**
  * Execute a git command and return trimmed stdout.
  * @param {string} args - git arguments
@@ -213,21 +221,93 @@ export function getChangedSubtrees(cwd) {
  */
 export function getRemoteBranch(cwd, remoteName) {
   try {
-    const refs = execSync(`git branch -r --list "${remoteName}/*"`, {
+    const headRef = execSync(`git symbolic-ref --quiet --short "refs/remotes/${remoteName}/HEAD"`, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    if (headRef) {
+      const slash = headRef.indexOf('/');
+      return slash >= 0 ? headRef.slice(slash + 1) : headRef;
+    }
+  } catch {
+    // fall through
+  }
+
+  try {
+    const refs = execSync(`git for-each-ref --format="%(refname:short)" "refs/remotes/${remoteName}"`, {
       cwd,
       encoding: 'utf-8',
       stdio: ['pipe', 'pipe', 'pipe'],
     }).trim();
     if (!refs) return null;
-    // e.g. "Hello-World/master" → "master"
-    const first = refs.split('\n')[0].trim();
-    const slash = first.indexOf('/');
-    return slash >= 0 ? first.slice(slash + 1) : first;
+
+    const branches = refs
+      .split('\n')
+      .map((ref) => ref.trim())
+      .filter(Boolean)
+      .map((ref) => {
+        const slash = ref.indexOf('/');
+        return slash >= 0 ? ref.slice(slash + 1) : ref;
+      })
+      .filter((ref) => ref !== 'HEAD');
+
+    if (branches.length === 0) {
+      return null;
+    }
+
+    if (branches.includes('main')) return 'main';
+    if (branches.includes('master')) return 'master';
+    return branches[0];
   } catch {
     return null;
   }
 }
 
+/**
+ * Get the branch explicitly tracked for a subtree in local git config.
+ */
+export function getConfiguredSubtreeBranch(cwd, prefixName) {
+  const branch = git(`config --get ${quoteShellArg(getSubtreeBranchConfigKey(prefixName))}`, {
+    cwd,
+    silent: true,
+    allowFailure: true,
+  });
+  return branch || null;
+}
+
+/**
+ * Persist the branch currently tracked for a subtree in local git config.
+ */
+export function setConfiguredSubtreeBranch(cwd, prefixName, branch) {
+  git(
+    `config ${quoteShellArg(getSubtreeBranchConfigKey(prefixName))} ${quoteShellArg(branch)}`,
+    { cwd, silent: true }
+  );
+}
+
+/**
+ * Get the branch unirepo should treat as the subtree's upstream branch.
+ */
+export function getTrackedSubtreeBranch(cwd, prefixName) {
+  return getConfiguredSubtreeBranch(cwd, prefixName) || getRemoteBranch(cwd, prefixName);
+}
+
+/**
+ * Check whether a remote has a specific branch.
+ */
+export function hasRemoteBranch(cwd, remoteName, branch) {
+  try {
+    execSync(`git ls-remote --exit-code --heads "${remoteName}" "${branch}"`, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check if the working tree has uncommitted (staged or unstaged) changes.
  */

package/src/index.js

@@ -54,6 +54,52 @@ export function parseArgs(argv) {
   return { command, positional, flags };
 }
 
+const COMMAND_USAGE = {
+  init: 'Usage: unirepo init <dir> <repo-url> [repo-url...]',
+  add: 'Usage: unirepo add <repo-url> [--prefix <name>] [--branch <name>] [--full-history]',
+  pull: 'Usage: unirepo pull [subtree...] [--prefix <name>] [--branch <name>] [--full-history]',
+  status: 'Usage: unirepo status [--json]',
+  push: 'Usage: unirepo push [subtree...] [--branch <name>] [--dry-run]',
+  branch: 'Usage: unirepo branch [name]',
+};
+
+const COMMAND_FLAGS = {
+  version: new Set(),
+  init: new Set(['fullHistory']),
+  add: new Set(['prefix', 'branch', 'fullHistory']),
+  pull: new Set(['prefix', 'branch', 'fullHistory']),
+  status: new Set(['json']),
+  push: new Set(['branch', 'dryRun']),
+  branch: new Set(),
+};
+
+const FLAG_NAMES = {
+  fullHistory: '--full-history',
+  json: '--json',
+  dryRun: '--dry-run',
+  prefix: '--prefix',
+  branch: '--branch',
+};
+
+export function validateCommandFlags(command, flags) {
+  const allowedFlags = COMMAND_FLAGS[command];
+  if (!allowedFlags) {
+    return;
+  }
+
+  const unsupportedFlags = Object.keys(flags)
+    .filter((flag) => flag !== 'help' && !allowedFlags.has(flag))
+    .map((flag) => FLAG_NAMES[flag] || `--${flag}`);
+
+  if (unsupportedFlags.length === 0) {
+    return;
+  }
+
+  const label = unsupportedFlags.length === 1 ? 'Flag' : 'Flags';
+  const verb = unsupportedFlags.length === 1 ? 'is' : 'are';
+  throw new Error(`${label} ${unsupportedFlags.join(', ')} ${verb} not supported for "${command}".`);
+}
+
 // ── Main ───────────────────────────────────────────────────────────────────────
 
 export async function main() {
@@ -64,6 +110,17 @@ export async function main() {
     process.exit(0);
   }
 
+  try {
+    validateCommandFlags(command, flags);
+  } catch (err) {
+    ui.error(err.message);
+    const usage = COMMAND_USAGE[command];
+    if (usage) {
+      ui.info(usage);
+    }
+    process.exit(1);
+  }
+
   switch (command) {
     case 'version': {
       ui.version();
@@ -102,8 +159,13 @@ export async function main() {
     }
 
     case 'pull': {
+      if (flags.prefix && positional.length > 0) {
+        ui.error('Usage: unirepo pull [subtree...] [--prefix <name>] [--branch <name>] [--full-history]');
+        ui.info('Use either subtree arguments or --prefix, not both.');
+        process.exit(1);
+      }
       await runPull({
-        subtrees: positional.length > 0 ? positional : undefined,
+        subtrees: flags.prefix ? [flags.prefix] : positional.length > 0 ? positional : undefined,
         branch: flags.branch,
         fullHistory: flags.fullHistory || false,
       });

package/src/templates.js

@@ -35,7 +35,7 @@ unirepo add <repo-url> --branch <branch>
 
 - \`status\` shows tracked subtrees, upstream branches, the current push branch, and changed files.
 - \`branch <name>\` creates the local branch name you should reuse when pushing subtrees upstream.
-- \`pull\` updates one or more tracked subtrees from upstream before or during your work.
+- \`pull\` updates one or more tracked subtrees from upstream before or during your work. Use \`--prefix\` when you want a branch-specific pull for just one subtree.
 - \`push --dry-run\` is the safe first step before a real push.
 - \`push\` without subtree names auto-detects changed subtrees. \`push <subtree>\` pushes one subtree.
 - \`add\` imports another repository as a subtree. Use \`--branch\` to import from a non-default upstream branch.
@@ -56,6 +56,7 @@ git checkout -b <branch>
 CLI:
 \`\`\`bash
 unirepo pull
+unirepo pull --prefix <subtree> --branch <branch>
 \`\`\`
 Git:
 \`\`\`bash

package/src/ui.js

@@ -195,6 +195,7 @@ ${chalk.bold('Add options:')}
   --full-history              Import full git history
 
 ${chalk.bold('Pull options:')}
+  --prefix <name>             Pull only one tracked subtree
   --branch <name>             Pull a specific upstream branch for all selected subtrees
   --full-history              Pull full history instead of squash mode
 
@@ -216,6 +217,9 @@ ${chalk.bold('Examples:')}
   ${chalk.dim('# Pull upstream updates before working')}
   npx unirepo pull
 
+  ${chalk.dim('# Pull one subtree from a specific upstream branch')}
+  npx unirepo pull --prefix api --branch release/2026-04
+
   ${chalk.dim('# Check status')}
   npx unirepo status