@sous-io/sous 0.2.14 → 0.2.15

package/docs/markdown/commands.md

@@ -177,10 +177,30 @@ Points a repository at a working copy on this machine instead of a published ver
 clones it into `.sous/repos` and links the clone; a name or URL with a `PATH` links the checkout at that path; a
 path alone links that checkout where it is, adding the repository first if needed. Takes `--dry-run`.
 
-- `--global`: link for every project on this machine, sharing one checkout.
-- `-y, --yes`: answer the trust question a not-yet-added repository raises (also `--trust`).
-
-Example: `sous repo link sous-recipes ~/Projects/sous-recipes`
+A checkout that was already on disk is fetched (a fetch changes none of its files or branches) and compared with
+upstream: its branch, whether that branch is merged into the default branch, and how many commits it is behind.
+When upstream cannot be reached within a few seconds, a warning gives git's reason and says since when the
+checkout may have diverged, and the link is still recorded. Nothing else changes the checkout unless a flag
+asks for it; git carries out each step, and a step git refuses stops the command with git's own message.
+
+- `--global`: link for every project on this machine, sharing one checkout. Changing that checkout's branch
+  says it affects every project that links it.
+- `--branch <name>`: switch to an existing branch, fetching it from upstream first when it is not local.
+- `--create-branch <name>`: create a new branch and switch to it; git refuses a name that already exists.
+- `--generate-branch`: the same, with the generated name `sous/edit-<YYYYMMDD>-<HHMM>`, which is printed.
+- `--from <branch>`: the base of the new branch, fetched first. Defaults to the repository's default branch,
+  not whatever is checked out, and needs `--create-branch` or `--generate-branch`.
+- `--latest`: make the branch being worked from (the `--branch` target, the `--from` base, or else the default
+  branch) match upstream's, leaving every other branch alone. What that would discard (uncommitted changes and
+  local commits upstream lacks) is listed first, with one question; it fails when the fetch fails.
+- `-y, --yes`: answer the trust question a not-yet-added repository raises and the question `--latest` asks
+  (also `-f`, `--force`, `--trust`).
+
+`--branch`, `--create-branch` and `--generate-branch` exclude each other; each flag works on a checkout linked
+by path, too.
+
+Example: `sous repo link sous-recipes ~/Projects/sous-recipes`, or `sous repo link sous-recipes
+--generate-branch --latest --yes`
 
 ### `sous repo unlink REPO`
 Stops reading a repository from a working copy and goes back to published versions; `REPO` is the short name as

package/docs/markdown/repositories-authoring.md

@@ -289,6 +289,59 @@ Run 'sous repo unlink my-recipes' to go back to published versions.
 `sous repo unlink` removes the map entry and nothing else: the checkout stays where it is, and its path is
 printed so you can delete it. Unlinking a name linked in the other scope says which scope holds it.
 
+### How a checkout compares with upstream
+
+A link says which checkout to read, not why, so `sous repo link` never changes a checkout on its own. When the
+checkout was already on disk (a clone reused from an earlier link, or one you named by path), it runs a short
+`git fetch`, which updates only the remote-tracking refs, and reports what it found. The part of the output that
+reports it looks like this:
+
+```term
+$ sous repo link my-recipes
+    Branch                 : lc/my-change
+    Compared with          : origin/main
+    Merged into origin/main: yes
+    Behind origin/main     : 12 commits
+```
+
+A branch that is merged and behind has usually been released already, and the checkout is building from an older
+state than upstream's. When the fetch fails or takes longer than a few seconds, the link is still recorded, and
+a warning gives git's reason and says since when the checkout may have diverged (the last time it was fetched).
+The fetch is skipped for a checkout sous has just cloned, and a checkout with no `origin` remote says it has no
+upstream to compare with.
+
+### Choosing the branch
+
+Every change to the checkout is a flag, and git carries each one out. When git refuses a step (a conflict with
+uncommitted changes, a branch that already exists, one that does not), the command stops and shows git's message
+under a line naming the step. Each flag works on a checkout linked by path, too.
+
+```bash
+sous repo link my-recipes --branch lc/their-change     # read from an existing branch
+sous repo link my-recipes --create-branch my-change    # start a new branch
+sous repo link my-recipes --generate-branch            # start one named sous/edit-<YYYYMMDD>-<HHMM>
+sous repo link my-recipes --generate-branch --from next  # start it from another branch
+sous repo link my-recipes --latest                     # bring the default branch up to upstream's
+```
+
+- `--branch <name>` switches with `git switch`, which also checks out a branch that exists only upstream. A clone
+  sous makes holds only the default branch, so a branch that is not local is fetched first and added to the
+  branches `origin` is fetched for.
+- `--create-branch <name>` and `--generate-branch` create a new branch and switch to it; the generated name is
+  printed. The new branch starts from upstream's copy of `--from`, which defaults to the repository's default
+  branch rather than whatever is checked out, so a new branch never silently stacks on an old, already-merged
+  one. `--from` is an error without one of the two.
+- `--branch`, `--create-branch` and `--generate-branch` exclude each other.
+- `--latest` means upstream's latest version of what you are working from: the `--branch` target, the `--from`
+  base, or otherwise the default branch. It fetches that branch, switches to it and makes it match upstream's,
+  and leaves every other branch alone. Making a branch match upstream discards local work without git warning
+  about it, so this is the one place sous checks for itself: uncommitted changes to tracked files and local
+  commits upstream lacks are listed first, with one question. `--yes` answers it, and a run with no terminal
+  fails naming that flag. When the fetch fails, `--latest` fails, with git's reason.
+
+A `--global` link's checkout is shared by every project on the machine that links the repository globally, so
+changing its branch says it affects all of them.
+
 ## Contribute to someone else's repository
 
 `sous repo submit` proposes your committed changes to a repository's maintainers; it never publishes and never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.14",
+  "version": "0.2.15",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.14
+version: 0.2.15
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/commands/repo/link.ts

@@ -12,13 +12,30 @@ import { enabledRepos } from "../../lib/repos/defaults.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
 import type { LinkOrigin } from "../../lib/repos/formats/links-map.js";
 import {
+  assertBranchName,
   cloneRepo,
+  compareWithUpstream,
+  createBranch,
+  currentBranch,
+  defaultBranch,
+  discardableWork,
+  fetchBranch,
+  generatedBranchName,
   isGitCheckout,
+  lastFetchedAt,
+  localBranchExists,
   looksLikeRepoUrl,
   remoteUrlOf,
   repoSlugFromUrl,
+  resetBranchToUpstream,
   sameRemote,
+  switchBranch,
+  tryFetchUpstream,
+  UPSTREAM_REMOTE,
+  type DiscardableWork,
 } from "../../lib/repos/git-clone.js";
+import { isInteractive, nonInteractiveError } from "../../lib/interactive.js";
+import { askYesNo } from "../../utils/prompts.js";
 import {
   assertLocalRepoDirectory,
   expandHomePath,
@@ -36,12 +53,16 @@ import {
   writeProjectLinks,
 } from "../../lib/repos/links.js";
 import {
+  BULLET,
   blankLine,
   dryRunNotice,
   footer,
   heading,
   log,
+  note,
+  paragraph,
   showCommandVars,
+  showVariable,
   showVariables,
   warning,
 } from "../../utils/formatting.js";
@@ -68,6 +89,15 @@ import {
  * adding one. Naming a repository this project has not added therefore runs the
  * same trust ceremony `sous repo add` runs, rather than skipping it; there is no
  * way to read from a repository this project does not trust.
+ *
+ * A link says nothing about WHY a checkout is being read (authoring, running a
+ * teammate's branch, a local fork, debugging), so the command never changes a
+ * checkout on its own. A checkout that was already on disk is fetched and
+ * compared with upstream, which changes none of its files or branches; every
+ * change to it is an explicit flag (`--branch`, `--create-branch`,
+ * `--generate-branch`, `--latest`), carried out by git, whose refusals are
+ * passed through. `--latest` is the one place sous checks for itself, because
+ * making a branch match upstream discards local work without git warning.
  */
 export default class RepoLink extends BaseCommand {
   static description = [
@@ -79,6 +109,8 @@ export default class RepoLink extends BaseCommand {
       "that clone.",
     "'sous repo link <name-or-url> <path>' links the checkout at that path to that " +
       "repository, and clones nothing.",
+    "A checkout that was already on disk is fetched and compared with upstream; " +
+      "only the branch flags and --latest change it.",
   ].join("\n");
 
   /**
@@ -93,6 +125,9 @@ export default class RepoLink extends BaseCommand {
     "<%= config.bin %> repo link sous-recipes ~/Projects/sous-recipes",
     "<%= config.bin %> repo link https://github.com/sous-io/sous-recipes",
     "<%= config.bin %> repo link sous-recipes --global",
+    "<%= config.bin %> repo link sous-recipes --latest",
+    "<%= config.bin %> repo link sous-recipes --generate-branch",
+    "<%= config.bin %> repo link sous-recipes --branch my-change --latest",
   ];
 
   static args = {
@@ -124,6 +159,33 @@ export default class RepoLink extends BaseCommand {
       description: "Print what would change without cloning or writing anything",
       default: false,
     }),
+    branch: Flags.string({
+      description: "Switch the checkout to this existing branch, fetching it from upstream first",
+      helpValue: "<name>",
+      exclusive: ["create-branch", "generate-branch"],
+    }),
+    "create-branch": Flags.string({
+      description: "Create this new branch in the checkout and switch to it",
+      helpValue: "<name>",
+      exclusive: ["branch", "generate-branch"],
+    }),
+    "generate-branch": Flags.boolean({
+      description: "Create a new branch named sous/edit-<date>-<time> in the checkout and switch to it",
+      exclusive: ["branch", "create-branch"],
+    }),
+    from: Flags.string({
+      description:
+        "Start the new branch from this branch instead of the repository's default branch",
+      helpValue: "<branch>",
+      // oclif's `dependsOn` wants every listed flag, and these two exclude each
+      // other; `some` is its spelling of "at least one of".
+      relationships: [{ type: "some", flags: ["create-branch", "generate-branch"] }],
+    }),
+    latest: Flags.boolean({
+      description:
+        "Make the branch being worked from match upstream's, after listing any local work that would be discarded",
+      default: false,
+    }),
   };
 
   async run(): Promise<void> {
@@ -175,9 +237,12 @@ export default class RepoLink extends BaseCommand {
         ? this.planLinkToPath(existingCheckout)
         : this.planClone(name, url, isGlobal, dryRun);
 
+    const request = branchRequestFrom(flags);
+
     if (dryRun) {
       blankLine();
       dryRunNotice(`would link '${name}' to ${plan.directory}`);
+      for (const line of describeBranchRequest(request)) dryRunNotice(line);
       dryRunNotice(
         `would record it in ${isGlobal ? "the machine-wide" : "this project's"} links map`
       );
@@ -185,6 +250,19 @@ export default class RepoLink extends BaseCommand {
       return;
     }
 
+    // Branch work happens before the link is recorded, so a step git refuses
+    // leaves no link pointing at a checkout in a state nobody asked for.
+    if (hasBranchWork(request)) {
+      if (isGlobal) {
+        warning(
+          `This checkout is SHARED by every project on this machine that links '${name}' ` +
+            `with --global.\n` +
+            `Changing its branch changes what all of them build from.`
+        );
+      }
+      plan.notes.push(...(await this.applyBranchRequest(plan.directory, request, flags.yes)));
+    }
+
     const map = isGlobal ? readGlobalLinks() : readProjectLinks(sousDir);
     const previous = map.links[name];
     map.links[name] = {
@@ -204,9 +282,11 @@ export default class RepoLink extends BaseCommand {
     for (const line of plan.notes) log(`  ${line}`);
     if (plan.notes.length > 0) blankLine();
 
+    const branch = isGitCheckout(plan.directory) ? currentBranch(plan.directory) : undefined;
     showVariables({
       Repository: name,
       Checkout: plan.directory,
+      ...(branch === undefined ? {} : { Branch: branch }),
       "Recorded in": linksPath,
     });
 
@@ -215,6 +295,10 @@ export default class RepoLink extends BaseCommand {
       log(`  This replaces an earlier link to ${previous.path}, which is untouched.`);
     }
 
+    // A checkout sous has just cloned is as current as upstream by definition;
+    // any other one may be days or months old, so say how it compares.
+    if (plan.kind !== "cloned") this.reportUpstream(plan.directory);
+
     warning(
       `The repository '${name}' is now LINKED.\n` +
         `Its recipes are read from the checkout above, so versions, the lockfile\n` +
@@ -227,6 +311,227 @@ export default class RepoLink extends BaseCommand {
     footer();
   }
 
+  /**
+   * Carries out the branch flags on the checkout, in order: `--latest` first
+   * (which switches to the branch being worked from and makes it match
+   * upstream's), then `--branch` when `--latest` did not already switch to it,
+   * then the new branch. Git decides whether each step may happen; the one
+   * thing checked here is what `--latest` would discard, because making a
+   * branch match upstream discards work without git warning about it.
+   *
+   * @param directory - The checkout.
+   * @param request - What the flags asked for.
+   * @param yes - The confirmation flag, which answers the discard question.
+   * @returns Lines describing what was done, for the notes block.
+   */
+  private async applyBranchRequest(
+    directory: string,
+    request: BranchRequest,
+    yes: boolean
+  ): Promise<string[]> {
+    if (!isGitCheckout(directory)) {
+      throw new ConfigError(
+        `${directory} is not a git checkout, so it has no branches to switch or create.\n` +
+          `  Link it without the branch flags, or turn it into a git repository first.`
+      );
+    }
+
+    for (const name of [request.switchTo, request.create, request.from]) {
+      if (name !== undefined) assertBranchName(directory, name);
+    }
+
+    const hasUpstream = remoteUrlOf(directory) !== undefined;
+    const needsDefault =
+      (request.create !== undefined && request.from === undefined) ||
+      (request.latest && request.switchTo === undefined && request.from === undefined);
+    const fallback = needsDefault ? this.requireDefaultBranch(directory) : undefined;
+    const notes: string[] = [];
+
+    if (request.latest) {
+      const target = (request.switchTo ?? request.from ?? fallback)!;
+      if (!hasUpstream) {
+        throw new ConfigError(
+          `--latest makes '${target}' match upstream's, and this checkout has no ` +
+            `'${UPSTREAM_REMOTE}' remote to be upstream.\n` +
+            `  Add one with 'git remote add ${UPSTREAM_REMOTE} <url>' in ${directory}, or ` +
+            `link without --latest.`
+        );
+      }
+      fetchBranch(directory, target);
+      const work = discardableWork(directory, target);
+      await this.confirmDiscard(target, work, yes);
+      resetBranchToUpstream(directory, target);
+      notes.push(`Made the branch '${target}' match ${UPSTREAM_REMOTE}/${target}.`);
+    } else if (request.switchTo !== undefined) {
+      // A branch that exists locally is switched to as it is; one that does not
+      // is fetched first, since a single-branch clone cannot see it otherwise.
+      if (hasUpstream && !localBranchExists(directory, request.switchTo)) {
+        fetchBranch(directory, request.switchTo);
+      }
+      switchBranch(directory, request.switchTo);
+      notes.push(`Switched to the branch '${request.switchTo}'.`);
+    }
+
+    if (request.create !== undefined) {
+      const base = (request.from ?? fallback)!;
+      let startPoint = base;
+      if (hasUpstream) {
+        // With --latest the base was fetched a moment ago.
+        if (!request.latest) fetchBranch(directory, base);
+        startPoint = `${UPSTREAM_REMOTE}/${base}`;
+      }
+      createBranch(directory, request.create, startPoint);
+      notes.push(
+        request.generated
+          ? `Created the branch '${request.create}' (a generated name) from ${startPoint}, ` +
+              `and switched to it.`
+          : `Created the branch '${request.create}' from ${startPoint}, and switched to it.`
+      );
+    }
+
+    return notes;
+  }
+
+  /**
+   * The upstream default branch, or a ConfigError saying it could not be
+   * worked out and which flag names a branch instead.
+   *
+   * @param directory - The checkout.
+   */
+  private requireDefaultBranch(directory: string): string {
+    const found = defaultBranch(directory);
+    if (found !== undefined) return found;
+    throw new ConfigError(
+      `Could not work out the default branch of the repository checked out at ${directory}.\n` +
+        `  git records it as '${UPSTREAM_REMOTE}/HEAD' when it clones, and this checkout ` +
+        `has no such record, nor could '${UPSTREAM_REMOTE}' be asked for it.\n` +
+        `  Name the branch to work from with --from, or with --branch.`
+    );
+  }
+
+  /**
+   * Lists what `--latest` would discard and asks once before going on. Nothing
+   * is asked when there is nothing to discard, and the confirmation flag
+   * answers the question ahead of time.
+   *
+   * @param branch - The branch being made to match upstream's.
+   * @param work - What would be discarded.
+   * @param yes - The confirmation flag.
+   */
+  private async confirmDiscard(
+    branch: string,
+    work: DiscardableWork,
+    yes: boolean
+  ): Promise<void> {
+    if (work.uncommitted.length === 0 && work.localCommits.length === 0) return;
+
+    blankLine();
+    paragraph(
+      `Making '${branch}' match ${UPSTREAM_REMOTE}/${branch} discards the local work below.`,
+      { indent: 2 }
+    );
+    if (work.uncommitted.length > 0) {
+      blankLine();
+      showVariable("Uncommitted changes", work.uncommitted.length);
+      for (const line of work.uncommitted) log(`      ${BULLET} ${line}`);
+    }
+    if (work.localCommits.length > 0) {
+      blankLine();
+      showVariable(`Commits ${UPSTREAM_REMOTE} does not have`, work.localCommits.length);
+      for (const line of work.localCommits) log(`      ${BULLET} ${line}`);
+    }
+
+    if (yes) return;
+
+    if (!isInteractive()) {
+      throw nonInteractiveError({
+        prompt: `whether to discard the local work on '${branch}' listed above`,
+        remedy:
+          "pass '--yes' (spelled '-y', '--force' or '--trust' if you prefer) to discard it " +
+          "without being asked.",
+      });
+    }
+
+    const proceed = await askYesNo("Discard it?");
+    if (!proceed) {
+      throw new ConfigError(
+        `Nothing was changed: the local work on '${branch}' was kept.\n` +
+          `  The checkout is on the branch it was on before, and no link was recorded.`
+      );
+    }
+  }
+
+  /**
+   * Says how a checkout that was already on disk compares with upstream. A
+   * short fetch comes first; it updates only the remote-tracking refs, never
+   * the user's files or branches. When upstream cannot be reached, the link
+   * still stands and the warning says since when the checkout may have
+   * diverged.
+   *
+   * @param directory - The checkout.
+   */
+  private reportUpstream(directory: string): void {
+    if (!isGitCheckout(directory)) return;
+
+    blankLine();
+    if (remoteUrlOf(directory) === undefined) {
+      note(
+        `The checkout has no '${UPSTREAM_REMOTE}' remote, so there is no upstream to ` +
+          `compare it with.`,
+        { indent: 2 }
+      );
+      return;
+    }
+
+    const fetched = tryFetchUpstream(directory);
+    const branch = defaultBranch(directory);
+
+    if (!fetched.ok) {
+      const since = lastFetchedAt(directory, branch);
+      warning(
+        `Could not reach upstream; the checkout may have diverged since ` +
+          (since === undefined
+            ? `it was last fetched, and git has no record of when that was.`
+            : `${formatWhen(since)}, when it was last fetched.`) +
+          `\n\nGit said:\n${fetched.reason}\n\n` +
+          `The link was recorded all the same, and nothing in the checkout was changed.`
+      );
+      return;
+    }
+
+    if (branch === undefined) {
+      note(
+        `Upstream was fetched, but its default branch could not be worked out, so there ` +
+          `is nothing to compare the checkout with.`,
+        { indent: 2 }
+      );
+      return;
+    }
+
+    const comparison = compareWithUpstream(directory, branch);
+    const upstream = `${UPSTREAM_REMOTE}/${branch}`;
+    const yesNo = (value: boolean | undefined) =>
+      value === undefined ? "unknown" : value ? "yes" : "no";
+
+    // The branch is already in the summary above; a detached HEAD has none
+    // there, so it is named here instead.
+    showVariables({
+      ...(comparison.branch === undefined
+        ? { "Checked out": `no branch; HEAD is detached at ${comparison.commit ?? "an unknown commit"}` }
+        : {}),
+      "Compared with": upstream,
+      [`Merged into ${upstream}`]: yesNo(comparison.merged),
+      [`Behind ${upstream}`]:
+        comparison.behind === undefined
+          ? "unknown"
+          : `${comparison.behind} ${comparison.behind === 1 ? "commit" : "commits"}`,
+    });
+    blankLine();
+    note(`Upstream was fetched just now; nothing in the checkout was changed.`, {
+      indent: 2,
+    });
+  }
+
   /**
    * The checkout a REPO argument names outright, as an absolute path, or
    * undefined when the argument is a short name or a URL instead.
@@ -381,6 +686,7 @@ export default class RepoLink extends BaseCommand {
     return {
       directory,
       origin: "path",
+      kind: "path",
       notes: [`Linked the checkout already at ${directory}.`],
     };
   }
@@ -429,6 +735,7 @@ export default class RepoLink extends BaseCommand {
       return {
         directory,
         origin: "clone",
+        kind: "reused",
         notes: [
           `Reused the checkout already at ${directory}; nothing was cloned.`,
         ],
@@ -439,6 +746,7 @@ export default class RepoLink extends BaseCommand {
       return {
         directory,
         origin: "clone",
+        kind: "cloned",
         notes: [`Would clone ${url} into ${directory}.`],
       };
     }
@@ -468,7 +776,7 @@ export default class RepoLink extends BaseCommand {
       );
     }
 
-    return { directory, origin: "clone", notes };
+    return { directory, origin: "clone", kind: "cloned", notes };
   }
 }
 
@@ -495,6 +803,97 @@ type LinkPlan = {
   directory: string;
   /** Whether sous cloned it or was pointed at it. */
   origin: LinkOrigin;
+  /**
+   * What this run did to get the checkout: cloned it just now, reused a clone
+   * already in place, or was given the path of one.
+   */
+  kind: "cloned" | "reused" | "path";
   /** Lines describing what happened, printed before the summary. */
   notes: string[];
 };
+
+/** What the branch flags asked for, with a generated name already chosen. */
+type BranchRequest = {
+  /** `--branch`: the existing branch to switch to. */
+  switchTo?: string;
+  /** `--create-branch` or `--generate-branch`: the branch to create. */
+  create?: string;
+  /** True when the name to create was generated rather than typed. */
+  generated: boolean;
+  /** `--from`: the base of the new branch; the default branch when unset. */
+  from?: string;
+  /** `--latest`: make the branch being worked from match upstream's. */
+  latest: boolean;
+};
+
+/**
+ * Reads the branch flags into one request. The generated name is chosen here,
+ * once, so the dry run and the real run would print the same thing.
+ *
+ * @param flags - The parsed flags.
+ */
+function branchRequestFrom(flags: {
+  branch?: string;
+  "create-branch"?: string;
+  "generate-branch"?: boolean;
+  from?: string;
+  latest: boolean;
+}): BranchRequest {
+  const generated = flags["generate-branch"] === true;
+  const create = generated ? generatedBranchName() : flags["create-branch"];
+  return {
+    ...(flags.branch === undefined ? {} : { switchTo: flags.branch }),
+    ...(create === undefined ? {} : { create }),
+    generated,
+    ...(flags.from === undefined ? {} : { from: flags.from }),
+    latest: flags.latest,
+  };
+}
+
+/** True when the request asks for anything to be done to the checkout. */
+function hasBranchWork(request: BranchRequest): boolean {
+  return request.switchTo !== undefined || request.create !== undefined || request.latest;
+}
+
+/**
+ * What a dry run says the branch flags would do, one line per step, in the
+ * order the real run takes them.
+ *
+ * @param request - The branch request.
+ */
+function describeBranchRequest(request: BranchRequest): string[] {
+  const lines: string[] = [];
+  const workingFrom = request.switchTo ?? request.from ?? "the default branch";
+  const quoted = (name: string) => (name === "the default branch" ? name : `'${name}'`);
+
+  if (request.latest) {
+    lines.push(
+      `would fetch ${quoted(workingFrom)}, list any local work on it that would be ` +
+        `discarded, and make it match upstream's`
+    );
+  } else if (request.switchTo !== undefined) {
+    lines.push(`would switch the checkout to the branch '${request.switchTo}'`);
+  }
+
+  if (request.create !== undefined) {
+    lines.push(
+      `would create the branch '${request.create}' from upstream's ` +
+        `${quoted(request.from ?? "the default branch")} and switch to it`
+    );
+  }
+  return lines;
+}
+
+/**
+ * Renders a moment as `YYYY-MM-DD HH:MM` in local time, which is what a person
+ * reads a "since when" as.
+ *
+ * @param when - The moment to render.
+ */
+function formatWhen(when: Date): string {
+  const pad = (value: number) => String(value).padStart(2, "0");
+  return (
+    `${when.getFullYear()}-${pad(when.getMonth() + 1)}-${pad(when.getDate())} ` +
+    `${pad(when.getHours())}:${pad(when.getMinutes())}`
+  );
+}

package/src/lib/repos/git-clone.ts

@@ -27,13 +27,25 @@ export type GitResult = {
   stderr: string;
 };
 
+/** Where and for how long one git command may run. */
+export type GitRunOptions = {
+  /** The directory git runs in. */
+  cwd?: string;
+  /**
+   * How long git may run, in milliseconds, before it is stopped. A command that
+   * runs out of time comes back with a null status and a sentence saying so in
+   * `stderr`, never as an exception. Unset means no limit.
+   */
+  timeoutMs?: number;
+};
+
 /**
  * Runs one git command. Swappable so tests never need a real git binary.
  *
  * @param args - The arguments passed to git, without the leading "git".
- * @param options - Where to run it.
+ * @param options - Where to run it, and for how long.
  */
-export type GitRunner = (args: string[], options: { cwd?: string }) => GitResult;
+export type GitRunner = (args: string[], options: GitRunOptions) => GitResult;
 
 /** Options shared by every function here. */
 export type GitOptions = {
@@ -54,8 +66,22 @@ export const runGit: GitRunner = (args, options = {}) => {
     // A clone must never stop to ask for a password; a prompt in a
     // non-interactive run would hang the command with no explanation.
     env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    timeout: options.timeoutMs,
+    killSignal: "SIGKILL",
   });
 
+  if ((result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT") {
+    const seconds = Math.round((options.timeoutMs ?? 0) / 1000);
+    const partial = (result.stderr ?? "").trim();
+    return {
+      status: null,
+      stdout: (result.stdout ?? "").trim(),
+      stderr:
+        `git did not finish within ${seconds} seconds and was stopped.` +
+        (partial.length > 0 ? `\n${partial}` : ""),
+    };
+  }
+
   if (result.error !== undefined) {
     const reason = (result.error as NodeJS.ErrnoException).code === "ENOENT"
       ? "git is not installed, or is not on your PATH"
@@ -75,25 +101,42 @@ export const runGit: GitRunner = (args, options = {}) => {
   };
 };
 
-/** Runs git and throws a ConfigError, carrying git's own message, on failure. */
+/**
+ * Runs git and throws a ConfigError on failure: a first line naming the step
+ * that failed, then the command, then git's own message, line for line. Git is
+ * the authority on what it will and will not do to a checkout, so its refusal
+ * is passed through rather than paraphrased.
+ */
 function runGitOrThrow(
   args: string[],
-  options: { cwd?: string; runner?: GitRunner; what: string }
+  options: { cwd?: string; runner?: GitRunner; what: string; timeoutMs?: number }
 ): GitResult {
   const runner = options.runner ?? runGit;
-  const result = runner(args, { cwd: options.cwd });
+  const result = runner(args, { cwd: options.cwd, timeoutMs: options.timeoutMs });
   if (result.status !== 0) {
-    const detail = result.stderr.length > 0 ? result.stderr : result.stdout;
+    const detail = gitMessage(result);
+    const said =
+      detail.length > 0
+        ? `  git said:\n${detail
+            .split("\n")
+            .map((line) => `    ${line}`)
+            .join("\n")}\n`
+        : "";
     throw new ConfigError(
       `${options.what} failed.\n` +
         `  Command: git ${args.join(" ")}\n` +
-        (detail.length > 0 ? `  git said: ${detail}\n` : "") +
+        said +
         `  Fix the problem git reported, then run the command again.`
     );
   }
   return result;
 }
 
+/** What git said about a result: its error output, or its standard output when that is all. */
+function gitMessage(result: GitResult): string {
+  return result.stderr.length > 0 ? result.stderr : result.stdout;
+}
+
 /**
  * True when the directory is inside a git working tree whose root is that same
  * directory. A subdirectory of a checkout is deliberately not a checkout here:
@@ -280,6 +323,424 @@ export function looksLikeRepoUrl(value: string): boolean {
   return value.startsWith("/") || value.startsWith("./") || value.startsWith("../");
 }
 
+// --- Branches and upstream ----------------------------------------------------------------------
+//
+// Everything below works on the `origin` remote, which is the one a clone
+// creates and the one `remoteUrlOf` reads. Each function either reports a fact
+// or runs exactly one git operation; when git refuses an operation, its own
+// message is passed through under a line naming the step, and nothing here
+// second-guesses it. The one exception is `discardableWork`, which exists
+// because making a branch match upstream discards work without git warning
+// about it.
+
+/** The remote every function here reads from and fetches. */
+export const UPSTREAM_REMOTE = "origin";
+
+/**
+ * How long the fetch behind the divergence report may take, in milliseconds.
+ * It is tight on purpose: the report is a courtesy, and an unreachable host
+ * must fall back to a warning rather than hold the link up.
+ */
+export const UPSTREAM_CHECK_TIMEOUT_MS = 10_000;
+
+/** What a fetch that is allowed to fail produced. */
+export type FetchOutcome =
+  | { ok: true }
+  | {
+      ok: false;
+      /** Git's own explanation, or the sentence saying it ran out of time. */
+      reason: string;
+    };
+
+/**
+ * The branch a checkout has checked out, or undefined when HEAD is detached
+ * (a tag or a bare commit is checked out instead of a branch).
+ *
+ * @param directory - The checkout to inspect.
+ * @param options - The git runner to use.
+ */
+export function currentBranch(directory: string, options: GitOptions = {}): string | undefined {
+  const runner = options.runner ?? runGit;
+  const result = runner(["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: directory });
+  if (result.status !== 0 || result.stdout.length === 0) return undefined;
+  return result.stdout;
+}
+
+/**
+ * The abbreviated commit HEAD points at, for describing a detached checkout.
+ *
+ * @param directory - The checkout to inspect.
+ * @param options - The git runner to use.
+ */
+export function headCommit(directory: string, options: GitOptions = {}): string | undefined {
+  const runner = options.runner ?? runGit;
+  const result = runner(["rev-parse", "--short", "HEAD"], { cwd: directory });
+  if (result.status !== 0 || result.stdout.length === 0) return undefined;
+  return result.stdout;
+}
+
+/**
+ * The upstream repository's default branch, or undefined when it cannot be
+ * worked out. A clone records it as `origin/HEAD`, which is read first and
+ * needs no network; a checkout that lacks that record (one made with `git
+ * init` and a remote added later, say) is asked about over the network, under
+ * the same tight timeout as the upstream check.
+ *
+ * @param directory - The checkout to inspect.
+ * @param options - The git runner to use.
+ */
+export function defaultBranch(directory: string, options: GitOptions = {}): string | undefined {
+  const runner = options.runner ?? runGit;
+  const prefix = `${UPSTREAM_REMOTE}/`;
+
+  const local = runner(
+    ["symbolic-ref", "--quiet", "--short", `refs/remotes/${UPSTREAM_REMOTE}/HEAD`],
+    { cwd: directory }
+  );
+  if (local.status === 0 && local.stdout.startsWith(prefix)) {
+    return local.stdout.slice(prefix.length);
+  }
+
+  const remote = runner(["ls-remote", "--symref", UPSTREAM_REMOTE, "HEAD"], {
+    cwd: directory,
+    timeoutMs: UPSTREAM_CHECK_TIMEOUT_MS,
+  });
+  if (remote.status !== 0) return undefined;
+  const match = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/m.exec(remote.stdout);
+  return match?.[1];
+}
+
+/**
+ * Fetches from upstream, allowing the fetch to fail. A fetch updates only the
+ * remote-tracking refs, never the user's files or branches, which is why the
+ * divergence report may run one unasked.
+ *
+ * @param directory - The checkout to fetch into.
+ * @param options - The git runner to use, and how long the fetch may take.
+ */
+export function tryFetchUpstream(
+  directory: string,
+  options: GitOptions & { timeoutMs?: number } = {}
+): FetchOutcome {
+  const runner = options.runner ?? runGit;
+  const result = runner(["fetch", "--quiet", UPSTREAM_REMOTE], {
+    cwd: directory,
+    timeoutMs: options.timeoutMs ?? UPSTREAM_CHECK_TIMEOUT_MS,
+  });
+  if (result.status === 0) return { ok: true };
+  const reason = gitMessage(result);
+  return {
+    ok: false,
+    reason: reason.length > 0 ? reason : `git exited with status ${String(result.status)}`,
+  };
+}
+
+/**
+ * When this checkout last heard from upstream, as far as it recorded: the
+ * newer of the last fetch and the last update to the default branch's
+ * remote-tracking ref (a clone writes the second and not the first).
+ * Undefined when neither record exists.
+ *
+ * @param directory - The checkout to inspect.
+ * @param branch - The upstream default branch, when it is known.
+ * @param options - The git runner to use.
+ */
+export function lastFetchedAt(
+  directory: string,
+  branch: string | undefined,
+  options: GitOptions = {}
+): Date | undefined {
+  const runner = options.runner ?? runGit;
+  const records = ["FETCH_HEAD"];
+  if (branch !== undefined) records.push(`logs/refs/remotes/${UPSTREAM_REMOTE}/${branch}`);
+
+  let newest: Date | undefined;
+  for (const record of records) {
+    const located = runner(["rev-parse", "--git-path", record], { cwd: directory });
+    if (located.status !== 0 || located.stdout.length === 0) continue;
+    const file = path.resolve(directory, located.stdout);
+    try {
+      const modified = fs.statSync(file).mtime;
+      if (newest === undefined || modified > newest) newest = modified;
+    } catch {
+      // No such record; the other one may still exist.
+    }
+  }
+  return newest;
+}
+
+/** How a checkout's current state compares with upstream's default branch. */
+export type UpstreamComparison = {
+  /** The branch checked out, or undefined when HEAD is detached. */
+  branch: string | undefined;
+  /** The commit HEAD points at, abbreviated. */
+  commit: string | undefined;
+  /** The upstream default branch compared against. */
+  defaultBranch: string;
+  /**
+   * True when every commit on HEAD is already on the upstream default branch;
+   * undefined when git could not tell (the remote-tracking ref is missing).
+   */
+  merged: boolean | undefined;
+  /** Commits on the upstream default branch that HEAD lacks; undefined when git could not tell. */
+  behind: number | undefined;
+};
+
+/**
+ * Compares a checkout's HEAD with the upstream default branch, from the
+ * remote-tracking refs as they stand. It runs no fetch of its own.
+ *
+ * @param directory - The checkout to inspect.
+ * @param branch - The upstream default branch.
+ * @param options - The git runner to use.
+ */
+export function compareWithUpstream(
+  directory: string,
+  branch: string,
+  options: GitOptions = {}
+): UpstreamComparison {
+  const runner = options.runner ?? runGit;
+  const upstream = `${UPSTREAM_REMOTE}/${branch}`;
+
+  const ancestor = runner(["merge-base", "--is-ancestor", "HEAD", upstream], {
+    cwd: directory,
+  });
+  const merged = ancestor.status === 0 ? true : ancestor.status === 1 ? false : undefined;
+
+  const count = runner(["rev-list", "--count", `HEAD..${upstream}`], { cwd: directory });
+  const parsed = Number.parseInt(count.stdout, 10);
+  const behind = count.status === 0 && Number.isFinite(parsed) ? parsed : undefined;
+
+  return {
+    branch: currentBranch(directory, options),
+    commit: headCommit(directory, options),
+    defaultBranch: branch,
+    merged,
+    behind,
+  };
+}
+
+/**
+ * Asks git whether a name is a valid branch name, and passes its refusal
+ * through when it is not. Every name the user types goes through this before
+ * it reaches any other git command, which is also what stops a name that starts
+ * with a dash from being read as an option.
+ *
+ * @param directory - The checkout the name is for.
+ * @param name - The branch name as the user typed it.
+ * @param options - The git runner to use.
+ */
+export function assertBranchName(directory: string, name: string, options: GitOptions = {}): void {
+  runGitOrThrow(["check-ref-format", "--branch", name], {
+    cwd: directory,
+    runner: options.runner,
+    what: `Checking the branch name '${name}'`,
+  });
+}
+
+/**
+ * True when the checkout has a local branch of that name.
+ *
+ * @param directory - The checkout to inspect.
+ * @param name - The branch name.
+ * @param options - The git runner to use.
+ */
+export function localBranchExists(
+  directory: string,
+  name: string,
+  options: GitOptions = {}
+): boolean {
+  const runner = options.runner ?? runGit;
+  const result = runner(["show-ref", "--verify", "--quiet", `refs/heads/${name}`], {
+    cwd: directory,
+  });
+  return result.status === 0;
+}
+
+/**
+ * Fetches one named branch from upstream into its remote-tracking ref.
+ *
+ * A clone sous makes is single-branch, so its fetch configuration covers only
+ * the default branch, and neither a plain fetch nor `git switch` would ever see
+ * another one. The branch is therefore fetched by an explicit refspec, and then
+ * added to the remote's fetch list (`git remote set-branches --add`), so later
+ * fetches keep it current and `git switch` can find it. A checkout whose fetch
+ * configuration already covers the branch is left as it is.
+ *
+ * @param directory - The checkout to fetch into.
+ * @param name - The branch to fetch.
+ * @param options - The git runner to use.
+ */
+export function fetchBranch(directory: string, name: string, options: GitOptions = {}): void {
+  runGitOrThrow(
+    [
+      "fetch",
+      "--quiet",
+      UPSTREAM_REMOTE,
+      `+refs/heads/${name}:refs/remotes/${UPSTREAM_REMOTE}/${name}`,
+    ],
+    {
+      cwd: directory,
+      runner: options.runner,
+      what: `Fetching the branch '${name}' from ${UPSTREAM_REMOTE}`,
+    }
+  );
+
+  if (fetchConfigCovers(directory, name, options)) return;
+
+  runGitOrThrow(["remote", "set-branches", "--add", UPSTREAM_REMOTE, name], {
+    cwd: directory,
+    runner: options.runner,
+    what: `Adding the branch '${name}' to the branches ${UPSTREAM_REMOTE} is fetched for`,
+  });
+}
+
+/**
+ * True when the remote's configured fetch refspecs already bring the branch
+ * in: a wildcard over every branch, or the branch by name.
+ */
+function fetchConfigCovers(directory: string, name: string, options: GitOptions): boolean {
+  const runner = options.runner ?? runGit;
+  const result = runner(["config", "--get-all", `remote.${UPSTREAM_REMOTE}.fetch`], {
+    cwd: directory,
+  });
+  if (result.status !== 0) return false;
+  return result.stdout.split("\n").some((line) => {
+    const source = line.trim().replace(/^\+/, "").split(":")[0];
+    return source === "refs/heads/*" || source === `refs/heads/${name}`;
+  });
+}
+
+/**
+ * Switches the checkout to an existing branch with `git switch`, which also
+ * creates a local branch tracking an upstream one of the same name.
+ *
+ * @param directory - The checkout to switch.
+ * @param name - The branch to switch to.
+ * @param options - The git runner to use.
+ */
+export function switchBranch(directory: string, name: string, options: GitOptions = {}): void {
+  runGitOrThrow(["switch", name], {
+    cwd: directory,
+    runner: options.runner,
+    what: `Switching to the branch '${name}'`,
+  });
+}
+
+/**
+ * Creates a branch at a start point and switches to it, with `git switch
+ * --create`, which refuses a branch that already exists. The new branch tracks
+ * nothing, so pushing it never lands on the branch it started from.
+ *
+ * @param directory - The checkout to work in.
+ * @param name - The branch to create.
+ * @param startPoint - Where it starts, such as `origin/main`.
+ * @param options - The git runner to use.
+ */
+export function createBranch(
+  directory: string,
+  name: string,
+  startPoint: string,
+  options: GitOptions = {}
+): void {
+  runGitOrThrow(["switch", "--create", name, "--no-track", startPoint], {
+    cwd: directory,
+    runner: options.runner,
+    what: `Creating the branch '${name}' from ${startPoint}`,
+  });
+}
+
+/** The local work that making a branch match upstream would throw away. */
+export type DiscardableWork = {
+  /** Changes to tracked files that are not committed, in `git status --short` form. */
+  uncommitted: string[];
+  /** Commits on the local branch that its upstream counterpart lacks, one line each. */
+  localCommits: string[];
+};
+
+/**
+ * Lists what `resetBranchToUpstream` would discard: uncommitted changes to
+ * tracked files (untracked files are left alone by it, so they are not listed),
+ * and commits on the local branch that the fetched upstream branch lacks. Run
+ * it after fetching the branch.
+ *
+ * @param directory - The checkout to inspect.
+ * @param name - The branch that would be made to match upstream.
+ * @param options - The git runner to use.
+ */
+export function discardableWork(
+  directory: string,
+  name: string,
+  options: GitOptions = {}
+): DiscardableWork {
+  const status = runGitOrThrow(["status", "--porcelain", "--untracked-files=no"], {
+    cwd: directory,
+    runner: options.runner,
+    what: "Listing the uncommitted changes",
+  });
+  const uncommitted = status.stdout
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+
+  let localCommits: string[] = [];
+  if (localBranchExists(directory, name, options)) {
+    const log = runGitOrThrow(
+      ["log", "--oneline", "--no-decorate", `refs/remotes/${UPSTREAM_REMOTE}/${name}..refs/heads/${name}`],
+      {
+        cwd: directory,
+        runner: options.runner,
+        what: `Listing the commits on '${name}' that ${UPSTREAM_REMOTE} does not have`,
+      }
+    );
+    localCommits = log.stdout
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  }
+
+  return { uncommitted, localCommits };
+}
+
+/**
+ * Switches to a branch and makes it match its fetched upstream counterpart
+ * exactly, creating the local branch when there is none. Uncommitted changes to
+ * tracked files and local commits upstream lacks are discarded, which is why a
+ * caller lists them with `discardableWork` and asks first. Every other branch
+ * is left as it is.
+ *
+ * @param directory - The checkout to work in.
+ * @param name - The branch to update.
+ * @param options - The git runner to use.
+ */
+export function resetBranchToUpstream(
+  directory: string,
+  name: string,
+  options: GitOptions = {}
+): void {
+  runGitOrThrow(
+    ["switch", "--discard-changes", "--force-create", name, `${UPSTREAM_REMOTE}/${name}`],
+    {
+      cwd: directory,
+      runner: options.runner,
+      what: `Making the branch '${name}' match ${UPSTREAM_REMOTE}/${name}`,
+    }
+  );
+}
+
+/**
+ * The name `--generate-branch` gives a new branch: `sous/edit-<YYYYMMDD>-<HHMM>`,
+ * in local time.
+ *
+ * @param now - The moment to name it after. Defaults to now.
+ */
+export function generatedBranchName(now: Date = new Date()): string {
+  const pad = (value: number) => String(value).padStart(2, "0");
+  const date = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
+  const time = `${pad(now.getHours())}${pad(now.getMinutes())}`;
+  return `sous/edit-${date}-${time}`;
+}
+
 // --- Small filesystem helpers -------------------------------------------------------------------
 
 /** Replaces anything outside a safe path segment, so a URL can never escape the store. */