Add restore (x): make a repository exactly what git records

Restores the selection and all submodules below it recursively, asking
only if work would be lost. May clone/fetch missing objects (D23).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

internal/submodule/git/provider.go

@@ -1,5 +1,6 @@
-// Package git provides a read-only submodule.Provider backed by the git
-// command line. It never touches the network.
+// Package git provides a submodule.Provider backed by the git command line.
+// It reads; it writes only in Restore, and uses the network only in Fetch and
+// in Restore (for what is missing).
 package git
 
 import (
@@ -32,6 +33,7 @@ type Provider struct {
 	sem      chan struct{} // bounds concurrent Status calls
 	fetchSem chan struct{} // bounds concurrent fetches
 	sshEnv   []string      // extra environment for fetches
+	extraEnv []string      // more environment for fetches and clones; tests
 
 	// WatchInterval is how often Watch checks for changes.
 	WatchInterval time.Duration

internal/submodule/git/restore.go

@@ -0,0 +1,400 @@
+package git
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"submarine/internal/submodule"
+)
+
+// restoreArgs are prepended to every git command of a restore: the user's
+// submodule.recurse must not make checkout and reset recurse behind our back,
+// the restore walks the submodules itself.
+var restoreArgs = []string{"-c", "submodule.recurse=false"}
+
+// maxWalk bounds the entries visited when looking for repositories inside an
+// untracked directory.
+const maxWalk = 20000
+
+// gitlink is a submodule entry of a tree or the index.
+type gitlink struct{ path, sha string }
+
+// RestoreLoss reports what Restore(path) would discard. It walks the
+// repositories on disk, not the loaded tree.
+func (p *Provider) RestoreLoss(ctx context.Context, path string) (submodule.Loss, error) {
+	dir, target, err := p.restoreTarget(ctx, path)
+	if err != nil {
+		return submodule.Loss{}, err
+	}
+	if dir == "" { // not initialized: nothing on disk to lose
+		return submodule.Loss{}, nil
+	}
+	return p.lossOf(ctx, dir, target), nil
+}
+
+// Restore makes path ("" is the superproject) and all submodules below it
+// exactly what git records, see docs/actions.md. A missing submodule is
+// cloned and missing commits are fetched; git never prompts.
+func (p *Provider) Restore(ctx context.Context, path string) error {
+	if path == "" {
+		return p.restoreRepo(ctx, p.root, "HEAD")
+	}
+	p.mu.RLock()
+	in, ok := p.mods[path]
+	p.mu.RUnlock()
+	if !ok {
+		return fmt.Errorf("unknown submodule %q", path)
+	}
+	pin, err := indexGitlink(ctx, in)
+	if err != nil {
+		return err
+	}
+	if !initialized(in.dir) {
+		if err := p.initSubmodules(ctx, in.superDir, []string{in.relPath}); err != nil {
+			return fmt.Errorf("%s: %w", path, err)
+		}
+	}
+	return p.restoreRepo(ctx, in.dir, pin)
+}
+
+// restoreTarget returns the directory and the commit path is restored to:
+// HEAD for the superproject, else the gitlink in its parent's index. The
+// directory is "" if the submodule is not initialized.
+func (p *Provider) restoreTarget(ctx context.Context, path string) (dir, target string, err error) {
+	if path == "" {
+		return p.root, "HEAD", nil
+	}
+	p.mu.RLock()
+	in, ok := p.mods[path]
+	p.mu.RUnlock()
+	if !ok {
+		return "", "", fmt.Errorf("unknown submodule %q", path)
+	}
+	pin, err := indexGitlink(ctx, in)
+	if err != nil {
+		return "", "", err
+	}
+	if !initialized(in.dir) {
+		return "", pin, nil
+	}
+	return in.dir, pin, nil
+}
+
+func indexGitlink(ctx context.Context, in info) (string, error) {
+	out, err := run(ctx, in.superDir, "ls-files", "-s", "--", in.relPath)
+	if err != nil {
+		return "", err
+	}
+	pin := parseGitlink(out)
+	if pin == "" {
+		return "", errors.New("has no gitlink in the superproject index (stale .gitmodules entry?)")
+	}
+	return pin, nil
+}
+
+// --- restore -----------------------------------------------------------------
+
+// restoreRepo restores the initialized repository at dir to target (a commit
+// or "HEAD") and then every submodule that target records. Branches are never
+// moved: a checkout that is not on target is detached first.
+func (p *Provider) restoreRepo(ctx context.Context, dir, target string) error {
+	env := p.networkEnv()
+	g := func(args ...string) (string, error) {
+		return p.exec(ctx, dir, env, append(append([]string{}, restoreArgs...), args...)...)
+	}
+
+	sha, err := g("rev-parse", "--verify", "-q", target+"^{commit}")
+	if err != nil {
+		if sha, err = p.fetchMissing(ctx, dir, target); err != nil {
+			return fmt.Errorf("%s: %w", dir, err)
+		}
+	}
+	if gitDir, _, err := gitDirs(dir); err == nil {
+		p.clearOperations(ctx, dir, gitDir)
+	}
+	if head, err := g("rev-parse", "--verify", "-q", "HEAD"); err != nil || head != sha {
+		if _, err := g("checkout", "--force", "--detach", sha); err != nil {
+			return err
+		}
+	}
+	if _, err := g("reset", "--hard", "-q"); err != nil {
+		return err
+	}
+	// -ff also removes untracked repositories; ignored files stay
+	if _, err := g("clean", "-ffdq"); err != nil {
+		return err
+	}
+	if _, err := g("submodule", "sync", "-q"); err != nil {
+		return err
+	}
+
+	links, err := treeGitlinks(ctx, dir, sha)
+	if err != nil {
+		return err
+	}
+	var missing []string
+	for _, l := range links {
+		if !initialized(filepath.Join(dir, filepath.FromSlash(l.path))) {
+			missing = append(missing, l.path)
+		}
+	}
+	if len(missing) > 0 {
+		if err := p.initSubmodules(ctx, dir, missing); err != nil {
+			return err
+		}
+	}
+
+	// the children are independent repositories
+	var wg sync.WaitGroup
+	errs := make([]error, len(links))
+	for i, l := range links {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if err := p.restoreRepo(ctx, filepath.Join(dir, filepath.FromSlash(l.path)), l.sha); err != nil {
+				errs[i] = err
+			}
+		}()
+	}
+	wg.Wait()
+	return errors.Join(errs...)
+}
+
+// networkEnv is the environment of commands that may clone or fetch.
+func (p *Provider) networkEnv() []string {
+	return append(append([]string{}, p.sshEnv...), p.extraEnv...)
+}
+
+// initSubmodules clones or checks out the given submodules of the repository
+// at dir, whatever their active and update settings say (--checkout overrides
+// update = none/rebase/merge, the explicit paths override inactive).
+func (p *Provider) initSubmodules(ctx context.Context, dir string, rels []string) error {
+	ctx, cancel := context.WithTimeout(ctx, fetchTimeout*time.Duration(len(rels)))
+	defer cancel()
+	args := append(append([]string{}, restoreArgs...), "submodule", "update", "--init", "--checkout", "--force", "-q", "--")
+	_, err := p.exec(ctx, dir, p.networkEnv(), append(args, rels...)...)
+	return err
+}
+
+// exec runs git like runEnv, but counts against the concurrency limit. Hold
+// it only for the command, never while recursing.
+func (p *Provider) exec(ctx context.Context, dir string, env []string, args ...string) (string, error) {
+	select {
+	case p.sem <- struct{}{}:
+		defer func() { <-p.sem }()
+	case <-ctx.Done():
+		return "", ctx.Err()
+	}
+	return runEnv(ctx, dir, env, args...)
+}
+
+// fetchMissing fetches all remotes of dir to get target, and returns its SHA.
+func (p *Provider) fetchMissing(ctx context.Context, dir, target string) (string, error) {
+	fctx, cancel := context.WithTimeout(ctx, fetchTimeout)
+	defer cancel()
+	// a failing fetch is reported with the missing commit below
+	_, ferr := runEnv(fctx, dir, p.networkEnv(), "fetch", "--all", "--no-recurse-submodules", "--quiet")
+	sha, ok, err := try(ctx, dir, "rev-parse", "--verify", "-q", target+"^{commit}")
+	if err != nil {
+		return "", err
+	}
+	if !ok {
+		msg := fmt.Sprintf("commit %.7s is not available", target)
+		if ferr != nil {
+			msg += " (fetch failed: " + firstLine(ferr) + ")"
+		} else {
+			msg += " on any remote"
+		}
+		return "", errors.New(msg)
+	}
+	return sha, nil
+}
+
+func firstLine(err error) string {
+	var ge *gitError
+	msg := err.Error()
+	if errors.As(err, &ge) && ge.Stderr != "" {
+		msg = ge.Stderr
+	}
+	line, _, _ := strings.Cut(msg, "\n")
+	return strings.TrimPrefix(line, "fatal: ")
+}
+
+// clearOperations ends a merge, rebase, cherry-pick or revert in progress
+// without moving any ref (--quit, not --abort).
+func (p *Provider) clearOperations(ctx context.Context, dir, gitDir string) {
+	exists := func(name string) bool { _, err := os.Stat(filepath.Join(gitDir, name)); return err == nil }
+	if exists("rebase-merge") || exists("rebase-apply") {
+		_, _, _ = try(ctx, dir, "rebase", "--quit")
+	}
+	if exists("CHERRY_PICK_HEAD") || exists("sequencer") {
+		_, _, _ = try(ctx, dir, "cherry-pick", "--quit")
+	}
+	if exists("REVERT_HEAD") {
+		_, _, _ = try(ctx, dir, "revert", "--quit")
+	}
+	// a merge is ended by the reset --hard that follows
+}
+
+// treeGitlinks lists the submodules recorded in commit's tree, at any depth
+// of directories.
+func treeGitlinks(ctx context.Context, dir, commit string) ([]gitlink, error) {
+	out, err := run(ctx, dir, "ls-tree", "-r", "-z", commit)
+	if err != nil {
+		return nil, err
+	}
+	var links []gitlink
+	for _, rec := range strings.Split(out, "\x00") {
+		meta, path, ok := strings.Cut(rec, "\t")
+		if f := strings.Fields(meta); ok && len(f) == 3 && f[0] == "160000" {
+			links = append(links, gitlink{path: path, sha: f[2]})
+		}
+	}
+	return links, nil
+}
+
+// indexGitlinks lists the submodules in the index of the repository at dir.
+func indexGitlinks(ctx context.Context, dir string) ([]gitlink, error) {
+	out, err := run(ctx, dir, "ls-files", "-s", "-z")
+	if err != nil {
+		return nil, err
+	}
+	var links []gitlink
+	for _, rec := range strings.Split(out, "\x00") {
+		meta, path, ok := strings.Cut(rec, "\t")
+		if f := strings.Fields(meta); ok && len(f) == 3 && f[0] == "160000" && f[2] == "0" {
+			links = append(links, gitlink{path: path, sha: f[1]})
+		}
+	}
+	return links, nil
+}
+
+// --- loss --------------------------------------------------------------------
+
+// lossOf adds up what a restore of the repository at dir to target
+// discards, including the submodules on disk below it. target is "" if it is
+// not known; then commits are only judged by the refs that reach them.
+func (p *Provider) lossOf(ctx context.Context, dir, target string) submodule.Loss {
+	var own submodule.Loss
+	var children []gitlink
+	var targets map[string]string
+	unknown := func() { own.Unknown++ }
+
+	func() {
+		select {
+		case p.sem <- struct{}{}:
+			defer func() { <-p.sem }()
+		case <-ctx.Done():
+			unknown()
+			return
+		}
+
+		out, err := run(ctx, dir, "status", "--porcelain=v2", "-z", "--untracked-files=normal", "--ignore-submodules=all")
+		if err != nil {
+			unknown()
+			return
+		}
+		for _, e := range parseStatus(out) {
+			if e.submodule {
+				continue // restored without loss
+			}
+			own.Files++
+			if e.kind == submodule.ChangeUntracked && strings.HasSuffix(e.path, "/") {
+				own.Repositories += standaloneRepos(ctx, filepath.Join(dir, filepath.FromSlash(e.path)))
+			}
+		}
+
+		if gitDir, _, err := gitDirs(dir); err == nil {
+			for _, name := range []string{"rebase-merge", "rebase-apply", "MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "sequencer"} {
+				if _, err := os.Stat(filepath.Join(gitDir, name)); err == nil {
+					own.Operations++
+					break
+				}
+			}
+		}
+
+		// commits only this checkout reaches are lost if the checkout moves
+		head, err := run(ctx, dir, "rev-parse", "--verify", "-q", "HEAD")
+		if err != nil {
+			unknown()
+		} else {
+			moves := target == ""
+			if !moves {
+				if sha, ok, _ := try(ctx, dir, "rev-parse", "--verify", "-q", target+"^{commit}"); ok {
+					moves = sha != head
+				} else {
+					moves = true
+				}
+			}
+			if moves {
+				n, ok, _ := try(ctx, dir, "rev-list", "--count", "HEAD", "--not", "--branches", "--tags", "--remotes")
+				if ok {
+					fmt.Sscan(n, &own.Commits)
+				} else {
+					unknown()
+				}
+			}
+		}
+
+		if children, err = indexGitlinks(ctx, dir); err != nil {
+			unknown()
+		}
+		if target != "" {
+			if links, err := treeGitlinks(ctx, dir, target); err == nil {
+				targets = map[string]string{}
+				for _, l := range links {
+					targets[l.path] = l.sha
+				}
+			}
+		}
+	}()
+
+	if own.Files+own.Operations+own.Commits+own.Repositories+own.Unknown > 0 {
+		own.Modules = 1
+	}
+
+	// the children on disk, concurrently
+	results := make([]submodule.Loss, len(children))
+	var wg sync.WaitGroup
+	for i, c := range children {
+		sub := filepath.Join(dir, filepath.FromSlash(c.path))
+		if !initialized(sub) {
+			continue
+		}
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			results[i] = p.lossOf(ctx, sub, targets[c.path])
+		}()
+	}
+	wg.Wait()
+	for _, r := range results {
+		own = own.Add(r)
+	}
+	return own
+}
+
+// standaloneRepos counts the repositories with their own .git directory in
+// the untracked directory dir (or dir itself). An absorbed submodule leaves
+// only a .git file; its commits live on in .git/modules.
+func standaloneRepos(ctx context.Context, dir string) int {
+	n, seen := 0, 0
+	_ = filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+		if seen++; err != nil || seen > maxWalk || ctx.Err() != nil {
+			return filepath.SkipAll
+		}
+		if d.IsDir() && d.Name() == ".git" {
+			n++
+			return filepath.SkipDir
+		}
+		return nil
+	})
+	return n
+}

internal/submodule/git/restore_test.go

@@ -0,0 +1,261 @@
+package git
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"submarine/internal/submodule"
+)
+
+// out runs git and returns its trimmed stdout.
+func out(t *testing.T, dir string, args ...string) string {
+	t.Helper()
+	b, err := exec.Command("git", append([]string{"-C", dir}, args...)...).Output()
+	if err != nil {
+		t.Fatalf("git %v: %v", args, err)
+	}
+	return strings.TrimSpace(string(b))
+}
+
+func exists(path string) bool { _, err := os.Stat(path); return err == nil }
+
+// assertExact checks that the superproject at dir and every submodule below
+// it is initialized, on its pin and has no change at all.
+func assertExact(t *testing.T, dir string) {
+	t.Helper()
+	if s := out(t, dir, "status", "--porcelain"); s != "" {
+		t.Errorf("%s not clean:\n%s", dir, s)
+	}
+	raw, err := exec.Command("git", "-C", dir, "submodule", "status", "--recursive").Output() // the prefix is a leading space
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, line := range strings.Split(string(raw), "\n") {
+		if line == "" {
+			continue
+		}
+		if line[0] != ' ' {
+			t.Errorf("submodule not exact: %s", line)
+			continue
+		}
+		f := strings.Fields(line)
+		if s := out(t, filepath.Join(dir, f[1]), "status", "--porcelain"); s != "" {
+			t.Errorf("%s not clean:\n%s", f[1], s)
+		}
+	}
+}
+
+func TestRestoreSuperprojectMakesEverythingExact(t *testing.T) {
+	p, root := ownFixture(t)
+	super := filepath.Join(root, "super")
+	ctx := context.Background()
+
+	// ignored files stay
+	if err := os.WriteFile(filepath.Join(super, ".git", "info", "exclude"), []byte("keep.log\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	keep := filepath.Join(super, "libs", "work", "keep.log")
+	// libs/work is a submodule: its own exclude file lives in its git dir
+	wkGit := out(t, filepath.Join(super, "libs", "work"), "rev-parse", "--absolute-git-dir")
+	if err := os.WriteFile(filepath.Join(wkGit, "info", "exclude"), []byte("keep.log\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(keep, []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// a branch must not move
+	conflict := filepath.Join(super, "libs", "conflict")
+	mainTip := out(t, conflict, "rev-parse", "main")
+
+	if err := p.Restore(ctx, ""); err != nil {
+		t.Fatal(err)
+	}
+	assertExact(t, super)
+	if got := out(t, conflict, "rev-parse", "main"); got != mainTip {
+		t.Errorf("branch main moved: %s -> %s", mainTip, got)
+	}
+	if !exists(keep) {
+		t.Error("ignored file was deleted")
+	}
+	if exists(filepath.Join(conflict, ".git", "MERGE_HEAD")) || exists(filepath.Join(out(t, conflict, "rev-parse", "--absolute-git-dir"), "MERGE_HEAD")) {
+		t.Error("merge still in progress")
+	}
+	if !exists(filepath.Join(super, "libs", "missing", ".git")) {
+		t.Error("libs/missing was not initialized")
+	}
+	if out(t, super, "diff", "--cached", "--name-only") != "" {
+		t.Error("staged pin survived a superproject restore")
+	}
+}
+
+func TestRestoreSubmoduleKeepsStagedPinAsTarget(t *testing.T) {
+	p, root := ownFixture(t)
+	super := filepath.Join(root, "super")
+	staged := out(t, filepath.Join(super, "libs", "staged"), "rev-parse", "HEAD")
+	// the fixture staged the checked-out commit; move the checkout away
+	git(t, filepath.Join(super, "libs", "staged"), "checkout", "-q", "--detach", "HEAD~1")
+
+	if err := p.Restore(context.Background(), "libs/staged"); err != nil {
+		t.Fatal(err)
+	}
+	if got := out(t, filepath.Join(super, "libs", "staged"), "rev-parse", "HEAD"); got != staged {
+		t.Errorf("HEAD = %s, want the staged pin %s", got, staged)
+	}
+	if !strings.Contains(out(t, super, "diff", "--cached", "--name-only"), "libs/staged") {
+		t.Error("restoring a submodule must keep its staged pin")
+	}
+}
+
+func TestRestoreLoss(t *testing.T) {
+	p, root := ownFixture(t)
+	super := filepath.Join(root, "super")
+	ctx := context.Background()
+
+	loss := func(path string) submodule.Loss {
+		t.Helper()
+		l, err := p.RestoreLoss(ctx, path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return l
+	}
+
+	// off pin and missing lose nothing; neither does an unpushed pin
+	for _, path := range []string{"src/core", "libs/missing", "src/net", "libs/staged"} {
+		if l := loss(path); !l.Empty() {
+			t.Errorf("%s: loss %+v, want none", path, l)
+		}
+	}
+
+	// libs/work: 6 files and a directory, untracked and changed
+	if l := loss("libs/work"); l.Files < 6 || l.Modules != 1 {
+		t.Errorf("libs/work: %+v", l)
+	}
+	// a nested change counts for its ancestors
+	if l := loss("libs/log"); l.Files != 1 || l.Modules != 1 {
+		t.Errorf("libs/log: %+v, want the nested change", l)
+	}
+	// a merge in progress
+	if l := loss("libs/conflict"); l.Operations != 1 || l.Files == 0 {
+		t.Errorf("libs/conflict: %+v", l)
+	}
+
+	// commits: detached and unreachable are lost, on a branch they are not
+	ui := filepath.Join(super, "src", "ui")
+	git(t, ui, "checkout", "-q", "--detach")
+	git(t, ui, "commit", "-q", "--allow-empty", "-m", "detached work")
+	if l := loss("src/ui"); l.Commits != 1 {
+		t.Errorf("detached commit: %+v", l)
+	}
+	git(t, ui, "switch", "-q", "-c", "wip")
+	if l := loss("src/ui"); l.Commits != 0 {
+		t.Errorf("commit on a branch: %+v", l)
+	}
+
+	// a clone nobody added as a submodule
+	git(t, super, "clone", "-q", filepath.Join(root, "remotes", "core.git"), "stray")
+	if l := loss(""); l.Repositories != 1 {
+		t.Errorf("root: %+v, want one standalone repository", l)
+	}
+}
+
+func TestRestoreRemovesLeftoversAndEndsRebase(t *testing.T) {
+	p, root := ownFixture(t)
+	super := filepath.Join(root, "super")
+	ctx := context.Background()
+
+	// a standalone clone is deleted
+	git(t, super, "clone", "-q", filepath.Join(root, "remotes", "core.git"), "stray")
+
+	// a submodule the branch no longer has leaves its directory behind
+	git(t, super, "rm", "-q", "--cached", "libs/topic")
+	git(t, super, "commit", "-q", "-m", "Drop topic")
+
+	// a rebase in progress in vendor; the branches must survive
+	v := filepath.Join(super, "vendor")
+	base := out(t, v, "rev-parse", "HEAD")
+	git(t, v, "switch", "-q", "-c", "x")
+	os.WriteFile(filepath.Join(v, "README"), []byte("x\n"), 0o644)
+	git(t, v, "commit", "-q", "-am", "x")
+	git(t, v, "switch", "-q", "-c", "y", base)
+	os.WriteFile(filepath.Join(v, "README"), []byte("y\n"), 0o644)
+	git(t, v, "commit", "-q", "-am", "y")
+	yTip := out(t, v, "rev-parse", "y")
+	_ = exec.Command("git", "-C", v, "rebase", "x").Run() // conflicts
+	if !exists(filepath.Join(out(t, v, "rev-parse", "--absolute-git-dir"), "rebase-merge")) {
+		t.Fatal("setup: no rebase in progress")
+	}
+
+	if err := p.Restore(ctx, ""); err != nil {
+		t.Fatal(err)
+	}
+	for _, gone := range []string{"stray", "libs/topic"} {
+		if exists(filepath.Join(super, gone)) {
+			t.Errorf("%s still exists", gone)
+		}
+	}
+	if exists(filepath.Join(out(t, v, "rev-parse", "--absolute-git-dir"), "rebase-merge")) {
+		t.Error("rebase still in progress")
+	}
+	if got := out(t, v, "rev-parse", "y"); got != yTip {
+		t.Errorf("branch y moved: %s -> %s", yTip, got)
+	}
+	if out(t, super, "status", "--porcelain") != "" {
+		t.Errorf("superproject not clean:\n%s", out(t, super, "status", "--porcelain"))
+	}
+}
+
+func TestRestoreClonesAMissingSubmodule(t *testing.T) {
+	p, root := ownFixture(t)
+	p.extraEnv = []string{"GIT_CONFIG_COUNT=1", "GIT_CONFIG_KEY_0=protocol.file.allow", "GIT_CONFIG_VALUE_0=always"}
+	super := filepath.Join(root, "super")
+
+	// no object database left: it must be cloned again
+	if err := os.RemoveAll(filepath.Join(super, ".git", "modules", "libs", "missing")); err != nil {
+		t.Fatal(err)
+	}
+	if err := p.Restore(context.Background(), "libs/missing"); err != nil {
+		t.Fatal(err)
+	}
+	if !exists(filepath.Join(super, "libs", "missing", ".git")) {
+		t.Error("not cloned")
+	}
+	if got, want := out(t, filepath.Join(super, "libs", "missing"), "rev-parse", "HEAD"), strings.Fields(out(t, super, "ls-files", "-s", "libs/missing"))[1]; got != want {
+		t.Errorf("HEAD = %s, want pin %s", got, want)
+	}
+}
+
+func TestRestoreReportsAnUnavailablePin(t *testing.T) {
+	p, root := ownFixture(t)
+	super := filepath.Join(root, "super")
+	// pin a commit that exists on no remote and not in the submodule
+	core := filepath.Join(super, "src", "core")
+	bogus := "0123456789abcdef0123456789abcdef01234567"
+	git(t, super, "update-index", "--cacheinfo", "160000,"+bogus+",src/core")
+	_ = core
+	err := p.Restore(context.Background(), "src/core")
+	if err == nil || !strings.Contains(err.Error(), "not available") {
+		t.Fatalf("err = %v, want a message about the unavailable commit", err)
+	}
+}
+
+func TestRestoreIgnoresUpdateNoneAndInactive(t *testing.T) {
+	p, root := ownFixture(t)
+	super := filepath.Join(root, "super")
+	git(t, super, "config", "submodule.libs/missing.update", "none")
+	git(t, super, "config", "submodule.libs/missing.active", "false")
+	git(t, super, "config", "submodule.active", "src")
+
+	if err := p.Restore(context.Background(), ""); err != nil {
+		t.Fatal(err)
+	}
+	if !exists(filepath.Join(super, "libs", "missing", ".git")) {
+		t.Error("libs/missing not initialized")
+	}
+	assertExact(t, super)
+}

internal/submodule/provider.go

@@ -33,6 +33,42 @@ type Locator interface {
 	Dir(path string) string
 }
 
+// Restorer is implemented by providers that can make a repository (and all
+// submodules below it) exactly what git records. Path "" is the
+// superproject. Restore may clone or fetch objects that are missing, but must
+// never prompt the user.
+type Restorer interface {
+	// RestoreLoss reports what Restore would discard, read from the disk at
+	// this moment.
+	RestoreLoss(ctx context.Context, path string) (Loss, error)
+	Restore(ctx context.Context, path string) error
+}
+
+// Loss is what a restore discards. The zero Loss means nothing is lost.
+type Loss struct {
+	Files        int // changed, conflicted and untracked files and directories
+	Modules      int // repositories with a loss, the repository itself included
+	Operations   int // merges, rebases, cherry-picks, reverts in progress
+	Commits      int // commits that no branch, tag or remote ref reaches
+	Repositories int // untracked repositories with their own .git directory
+	Unknown      int // repositories whose state could not be read
+}
+
+// Empty reports whether nothing would be lost.
+func (l Loss) Empty() bool { return l == Loss{} }
+
+// Add sums two losses.
+func (l Loss) Add(o Loss) Loss {
+	return Loss{
+		Files:        l.Files + o.Files,
+		Modules:      l.Modules + o.Modules,
+		Operations:   l.Operations + o.Operations,
+		Commits:      l.Commits + o.Commits,
+		Repositories: l.Repositories + o.Repositories,
+		Unknown:      l.Unknown + o.Unknown,
+	}
+}
+
 // Change reports that the git metadata of a repository changed.
 type Change struct {
 	Path      string // "" is the superproject

internal/tui/app.go

@@ -56,6 +56,9 @@ type Model struct {
 	// exactly then. The input is focused while typing and blurred after enter.
 	filtering bool
 
+	restore *restoreState // the restore in progress, nil if none
+	notice  string        // an error to show above the footer until the next key
+
 	width, height int
 	showDetail    bool
 }
@@ -156,7 +159,7 @@ func (m *Model) startFetch() tea.Cmd {
 
 // busy reports whether something shows a spinner.
 func (m Model) busy() bool {
-	if m.repo == nil || m.fetch.Running {
+	if m.repo == nil || m.fetch.Running || (m.restore != nil && m.restore.phase != restoreAsking) {
 		return true
 	}
 	loading := m.repo.Root != nil && m.repo.Root.Status == nil && m.repo.Root.Err == nil
@@ -202,6 +205,12 @@ func (m Model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	case changeMsg:
 		return m.changed(msg)
 
+	case lossMsg:
+		return m.lossChecked(msg)
+
+	case restoreDoneMsg:
+		return m.restoreDone(msg)
+
 	case fetchDoneMsg:
 		m.fetch.Done++
 		if msg.err != nil {
@@ -322,6 +331,13 @@ func (m Model) changed(msg changeMsg) (tea.Model, tea.Cmd) {
 
 func (m Model) handleKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 	k := m.keys
+	if m.restore != nil && m.restore.phase == restoreAsking {
+		return m.answerRestore(msg)
+	}
+	if m.notice != "" {
+		m.notice = ""
+		m.layout()
+	}
 	if m.filter.Focused() {
 		return m.typeFilter(msg)
 	}
@@ -377,6 +393,8 @@ func (m Model) handleKey(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 		m.filtering = true
 		m.layout()
 		return m, m.filter.Focus()
+	case key.Matches(msg, k.Restore):
+		return m.startRestore()
 	case key.Matches(msg, k.Issues):
 		m.tree.SetProblemsOnly(!m.tree.ProblemsOnly())
 		m.layout()
@@ -438,9 +456,12 @@ func (m Model) filterView() string {
 	return lipgloss.NewStyle().Width(m.width).Padding(0, 1).Render(in + strings.Repeat(" ", gap) + hint)
 }
 
-// extraLine reports whether a line above the footer is shown: the filter, or
-// the notice that only problems are shown.
-func (m Model) extraLine() bool { return m.filtering || m.tree.ProblemsOnly() }
+// extraLine reports whether a line above the footer is shown: a restore in
+// progress, a failure, the filter, or the notice that only problems are
+// shown.
+func (m Model) extraLine() bool {
+	return m.filtering || m.tree.ProblemsOnly() || m.restore != nil || m.notice != ""
+}
 
 // problemsView is the line above the footer while only problems are shown, so
 // a short list is not mistaken for a healthy repository.
@@ -512,7 +533,11 @@ func (m Model) View() string {
 
 	head := header.View(m.theme, m.repo, m.fetch, m.spinner.View(), m.width, m.tree.RootSelected())
 	parts := []string{zone.Mark(m.tree.RootZone(), head), body}
-	if m.filtering {
+	if m.restore != nil {
+		parts = append(parts, m.restoreView())
+	} else if m.notice != "" {
+		parts = append(parts, m.noticeView())
+	} else if m.filtering {
 		parts = append(parts, m.filterView())
 	} else if m.tree.ProblemsOnly() {
 		parts = append(parts, m.problemsView())

internal/tui/keys.go

@@ -7,7 +7,7 @@ type keyMap struct {
 	CollapseAll, ExpandAll        key.Binding
 	Home, End, PageUp, PageDown   key.Binding
 	Fetch, Reload, Filter, Issues key.Binding
-	Copy, Help, Quit              key.Binding
+	Copy, Restore, Help, Quit     key.Binding
 }
 
 func defaultKeys() keyMap {
@@ -27,6 +27,7 @@ func defaultKeys() keyMap {
 		Reload:      key.NewBinding(key.WithKeys("r"), key.WithHelp("r", "reload")),
 		Filter:      key.NewBinding(key.WithKeys("/"), key.WithHelp("/", "filter")),
 		Issues:      key.NewBinding(key.WithKeys("!"), key.WithHelp("!", "problems only")),
+		Restore:     key.NewBinding(key.WithKeys("x"), key.WithHelp("x", "restore")),
 		Copy:        key.NewBinding(key.WithKeys("c"), key.WithHelp("c", "copy path")),
 		Help:        key.NewBinding(key.WithKeys("?"), key.WithHelp("?", "help")),
 		Quit:        key.NewBinding(key.WithKeys("q", "ctrl+c"), key.WithHelp("q", "quit")),
@@ -43,7 +44,7 @@ func (k keyMap) Navigation() []key.Binding {
 
 // Submodule returns the bindings that act on the selected submodule. They
 // are shown in the detail pane, or in the footer if the pane can't show them.
-func (k keyMap) Submodule() []key.Binding { return []key.Binding{k.Copy} }
+func (k keyMap) Submodule() []key.Binding { return []key.Binding{k.Copy, k.Restore} }
 
 // Global returns the bindings that don't depend on the selection.
 func (k keyMap) Global() []key.Binding { return []key.Binding{k.Help, k.Quit} }
@@ -57,7 +58,7 @@ func (k keyMap) FullHelp() [][]key.Binding {
 		{k.Up, k.Down, k.Left, k.Right, k.Toggle},
 		{k.CollapseAll, k.ExpandAll},
 		{k.Home, k.End, k.PageUp, k.PageDown},
-		{k.Copy},
+		{k.Copy, k.Restore},
 		{k.Fetch, k.Reload, k.Filter, k.Issues},
 		{k.Help, k.Quit},
 	}

internal/tui/restore.go

@@ -0,0 +1,206 @@
+package tui
+
+import (
+	"fmt"
+	"strings"
+
+	tea "github.com/charmbracelet/bubbletea"
+	"github.com/charmbracelet/lipgloss"
+	"github.com/charmbracelet/x/ansi"
+
+	"submarine/internal/submodule"
+	"submarine/internal/tui/theme"
+)
+
+type restorePhase int
+
+const (
+	restoreChecking restorePhase = iota // reading what would be lost
+	restoreAsking                       // waiting for y / n
+	restoreRunning
+)
+
+// restoreState is the restore in progress; only one runs at a time.
+type restoreState struct {
+	path, name string // name is how the footer calls it
+	phase      restorePhase
+	loss       submodule.Loss
+}
+
+// lossMsg is the result of the check before a restore.
+type lossMsg struct {
+	path string
+	loss submodule.Loss
+	err  error
+}
+
+type restoreDoneMsg struct {
+	path string
+	err  error
+}
+
+// startRestore checks what restoring the selection would discard. If nothing
+// would be lost it restores at once, else it asks first.
+func (m Model) startRestore() (tea.Model, tea.Cmd) {
+	s := m.tree.Selected()
+	r, ok := m.provider.(submodule.Restorer)
+	var flash string
+	switch {
+	case s == nil:
+		return m, nil
+	case !ok:
+		flash = "this data source can't restore"
+	case m.restore != nil:
+		flash = "wait for the restore of " + m.restore.name + " to finish"
+	}
+	if flash != "" {
+		cmd := m.footer.Flash(flash)
+		m.layout()
+		return m, cmd
+	}
+
+	m.restore = &restoreState{path: s.Path, name: restoreName(s)}
+	m.layout()
+	ctx, path := m.ctx, s.Path
+	check := func() tea.Msg {
+		loss, err := r.RestoreLoss(ctx, path)
+		return lossMsg{path, loss, err}
+	}
+	return m, tea.Batch(check, m.tick())
+}
+
+// lossChecked reacts to the check: restore, or ask.
+func (m Model) lossChecked(msg lossMsg) (tea.Model, tea.Cmd) {
+	if m.restore == nil || m.restore.path != msg.path || m.restore.phase != restoreChecking {
+		return m, nil
+	}
+	if msg.err != nil {
+		m.restore = nil
+		m.notice = "can't check " + restoreName(m.byPath[msg.path]) + ": " + msg.err.Error()
+		m.layout()
+		return m, nil
+	}
+	m.restore.loss = msg.loss
+	if msg.loss.Empty() {
+		return m.runRestore()
+	}
+	m.restore.phase = restoreAsking
+	m.layout()
+	return m, nil
+}
+
+// answerRestore handles a key while the restore waits for its answer: y
+// restores, anything else cancels.
+func (m Model) answerRestore(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
+	switch {
+	case msg.Type == tea.KeyCtrlC:
+		return m, tea.Quit
+	case msg.String() == "y":
+		return m.runRestore()
+	}
+	m.restore = nil
+	m.layout()
+	return m, nil
+}
+
+func (m Model) runRestore() (tea.Model, tea.Cmd) {
+	m.restore.phase = restoreRunning
+	m.layout()
+	r := m.provider.(submodule.Restorer)
+	ctx, path := m.ctx, m.restore.path
+	run := func() tea.Msg { return restoreDoneMsg{path, r.Restore(ctx, path)} }
+	return m, tea.Batch(run, m.tick())
+}
+
+// restoreDone shows the result and reloads everything: the structure may have
+// changed.
+func (m Model) restoreDone(msg restoreDoneMsg) (tea.Model, tea.Cmd) {
+	name := "the superproject"
+	if m.restore != nil {
+		name = m.restore.name
+	}
+	m.restore = nil
+	var cmds []tea.Cmd
+	if msg.err != nil {
+		m.notice = "restore of " + name + " failed: " + msg.err.Error()
+	} else {
+		cmds = append(cmds, m.footer.Flash("restored "+name))
+	}
+	cmds = append(cmds, m.reloadTree(true))
+	m.layout()
+	return m, tea.Batch(cmds...)
+}
+
+func restoreName(s *submodule.Submodule) string {
+	if s == nil || s.IsRoot() {
+		return "the superproject"
+	}
+	return s.Path
+}
+
+// restoreView is the line above the footer while a restore is in progress.
+func (m Model) restoreView() string {
+	r := m.restore
+	left, right := "", ""
+	switch r.phase {
+	case restoreChecking:
+		left = theme.Fg(m.theme.Primary).Render(m.spinner.View()) + " " + theme.Fg(m.theme.Muted).Render("checking "+r.name+"…")
+	case restoreRunning:
+		left = theme.Fg(m.theme.Primary).Render(m.spinner.View()) + " " + theme.Fg(m.theme.Warn).Render("restoring "+r.name+"…")
+	case restoreAsking:
+		left = theme.Fg(m.theme.Warn).Render("Restore "+r.name+"?") + " " +
+			theme.Fg(m.theme.Danger).Render("Discards "+lossText(r.loss)+".")
+		right = theme.Fg(m.theme.Text).Bold(true).Render("y") + theme.Fg(m.theme.Muted).Render(" restore · ") +
+			theme.Fg(m.theme.Text).Bold(true).Render("n") + theme.Fg(m.theme.Muted).Render(" cancel")
+	}
+	return m.line(left, right)
+}
+
+// line lays out one line above the footer: left, right-aligned right. The
+// left part is cut if both don't fit.
+func (m Model) line(left, right string) string {
+	w := m.width - 2
+	if right != "" {
+		left = ansi.Truncate(left, max(w-lipgloss.Width(right)-2, 1), "…")
+	}
+	gap := max(w-lipgloss.Width(left)-lipgloss.Width(right), 1)
+	return lipgloss.NewStyle().Width(m.width).Padding(0, 1).Render(left + strings.Repeat(" ", gap) + right)
+}
+
+// noticeView is the line above the footer after a restore failed.
+func (m Model) noticeView() string {
+	return m.line(theme.Fg(m.theme.Danger).Render(m.notice), "")
+}
+
+// lossText words what a restore discards, e.g. "7 changed files in 3
+// repositories, 2 commits on no branch, 1 untracked repository".
+func lossText(l submodule.Loss) string {
+	var parts []string
+	if l.Files > 0 {
+		s := plural(l.Files, "changed file", "changed files")
+		if l.Modules > 1 {
+			s += fmt.Sprintf(" in %d repositories", l.Modules)
+		}
+		parts = append(parts, s)
+	}
+	if l.Operations > 0 {
+		parts = append(parts, plural(l.Operations, "operation in progress", "operations in progress"))
+	}
+	if l.Commits > 0 {
+		parts = append(parts, plural(l.Commits, "commit on no branch", "commits on no branch"))
+	}
+	if l.Repositories > 0 {
+		parts = append(parts, plural(l.Repositories, "untracked repository", "untracked repositories"))
+	}
+	if l.Unknown > 0 {
+		parts = append(parts, plural(l.Unknown, "repository of unknown state", "repositories of unknown state"))
+	}
+	return strings.Join(parts, ", ")
+}
+
+func plural(n int, one, many string) string {
+	if n == 1 {
+		return "1 " + one
+	}
+	return fmt.Sprintf("%d %s", n, many)
+}

internal/tui/restore_test.go

@@ -0,0 +1,153 @@
+package tui
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	tea "github.com/charmbracelet/bubbletea"
+	zone "github.com/lrstanley/bubblezone"
+
+	"submarine/internal/submodule"
+	"submarine/internal/submodule/mock"
+)
+
+func TestMain(m *testing.M) {
+	zone.NewGlobal()
+	os.Exit(m.Run())
+}
+
+func TestLossText(t *testing.T) {
+	cases := []struct {
+		in   submodule.Loss
+		want string
+	}{
+		{submodule.Loss{Files: 1, Modules: 1}, "1 changed file"},
+		{submodule.Loss{Files: 7, Modules: 3, Commits: 2, Repositories: 1}, "7 changed files in 3 repositories, 2 commits on no branch, 1 untracked repository"},
+		{submodule.Loss{Operations: 1, Modules: 1, Unknown: 2}, "1 operation in progress, 2 repositories of unknown state"},
+	}
+	for _, c := range cases {
+		if got := lossText(c.in); got != c.want {
+			t.Errorf("lossText(%+v) = %q, want %q", c.in, got, c.want)
+		}
+	}
+}
+
+// fakeRestorer is the mock data with a restore that records its calls.
+type fakeRestorer struct {
+	submodule.Provider
+	loss     submodule.Loss
+	restored []string
+}
+
+func (f *fakeRestorer) RestoreLoss(context.Context, string) (submodule.Loss, error) {
+	return f.loss, nil
+}
+
+func (f *fakeRestorer) Restore(_ context.Context, path string) error {
+	f.restored = append(f.restored, path)
+	return nil
+}
+
+// run executes a command, flattening batches, and returns the messages.
+func run(cmd tea.Cmd) []tea.Msg {
+	if cmd == nil {
+		return nil
+	}
+	msg := cmd()
+	if b, ok := msg.(tea.BatchMsg); ok {
+		var out []tea.Msg
+		for _, c := range b {
+			if c != nil {
+				out = append(out, run(c)...)
+			}
+		}
+		return out
+	}
+	return []tea.Msg{msg}
+}
+
+func press(m tea.Model, k string) (tea.Model, tea.Cmd) {
+	return m.Update(tea.KeyMsg{Type: tea.KeyRunes, Runes: []rune(k)})
+}
+
+// newRestoreModel returns a model with the mock tree loaded.
+func newRestoreModel(t *testing.T, loss submodule.Loss) (tea.Model, *fakeRestorer) {
+	t.Helper()
+	f := &fakeRestorer{Provider: mock.New(), loss: loss}
+	var m tea.Model = New(context.Background(), f)
+	m, _ = m.Update(tea.WindowSizeMsg{Width: 120, Height: 30})
+	repo, err := f.Tree(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	m, _ = m.Update(treeLoadedMsg{repo: repo})
+	return m, f
+}
+
+// feed delivers the messages of cmd to m, once.
+func feed(m tea.Model, cmd tea.Cmd) tea.Model {
+	for _, msg := range run(cmd) {
+		switch msg.(type) {
+		case lossMsg, restoreDoneMsg:
+			m, _ = m.Update(msg)
+		}
+	}
+	return m
+}
+
+func TestRestoreWithoutLossRunsAtOnce(t *testing.T) {
+	m, f := newRestoreModel(t, submodule.Loss{})
+	m, cmd := press(m, "x")
+	var next tea.Cmd
+	for _, msg := range run(cmd) {
+		if l, ok := msg.(lossMsg); ok {
+			m, next = m.Update(l)
+		}
+	}
+	m = feed(m, next)
+	if len(f.restored) != 1 || f.restored[0] != "" {
+		t.Fatalf("restored %q, want the superproject once", f.restored)
+	}
+	if m.(Model).restore != nil {
+		t.Error("restore still in progress")
+	}
+}
+
+func TestRestoreAsksWhenSomethingIsLost(t *testing.T) {
+	m, f := newRestoreModel(t, submodule.Loss{Files: 3, Modules: 1})
+	m, cmd := press(m, "x")
+	var next tea.Cmd
+	for _, msg := range run(cmd) {
+		if l, ok := msg.(lossMsg); ok {
+			m, next = m.Update(l)
+		}
+	}
+	if next != nil || m.(Model).restore == nil || m.(Model).restore.phase != restoreAsking {
+		t.Fatalf("want a question, got %+v", m.(Model).restore)
+	}
+
+	// any other key cancels
+	c, _ := press(m, "n")
+	if c.(Model).restore != nil || len(f.restored) != 0 {
+		t.Fatal("n must cancel without restoring")
+	}
+
+	// y restores
+	m, cmd = press(m, "y")
+	m = feed(m, cmd)
+	if len(f.restored) != 1 {
+		t.Fatalf("restored %q", f.restored)
+	}
+}
+
+func TestRestoreWithoutRestorerSaysSo(t *testing.T) {
+	var m tea.Model = New(context.Background(), mock.New())
+	m, _ = m.Update(tea.WindowSizeMsg{Width: 120, Height: 30})
+	repo, _ := mock.New().Tree(context.Background())
+	m, _ = m.Update(treeLoadedMsg{repo: repo})
+	m, _ = press(m, "x")
+	if m.(Model).restore != nil {
+		t.Fatal("the mock can't restore")
+	}
+}