@shortlink-org/portolan 0.1.0

package/plugins/fetch-git/fetch_test.go

@@ -0,0 +1,332 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// A repository to fetch from, made on the spot: git itself is the fake, and
+// what it serves is what a forge would serve.
+type remote struct {
+	url    string
+	commit string
+}
+
+func repository(t *testing.T) remote {
+	t.Helper()
+	if _, err := exec.LookPath("git"); err != nil {
+		t.Skip("no git on PATH")
+	}
+	dir := t.TempDir()
+	run := func(args ...string) string {
+		t.Helper()
+		cmd := exec.Command("git", append([]string{
+			"-c", "user.name=test", "-c", "user.email=test@example.com",
+			"-c", "commit.gpgsign=false", "-c", "init.defaultBranch=main",
+		}, args...)...)
+		cmd.Dir = dir
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, out)
+		}
+
+		return strings.TrimSpace(string(out))
+	}
+	write := func(rel, contents string) {
+		t.Helper()
+		if err := os.MkdirAll(filepath.Dir(filepath.Join(dir, rel)), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, rel), []byte(contents), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	run("init", "--quiet")
+	write("services/oms/internal/domain/order/order.go", "package order\n")
+	write("services/oms/README.md", "# OMS\n")
+	write("proto/shop/v1/orders.proto", "syntax = \"proto3\";\n")
+	write("README.md", "# shop\n")
+	run("add", ".")
+	run("commit", "--quiet", "-m", "the estate")
+	// A forge lets a client fetch a commit by name; a plain file remote does
+	// not unless told to, and the fallback to branches is tested separately.
+	run("config", "uploadpack.allowAnySHA1InWant", "true")
+
+	return remote{url: "file://" + dir, commit: run("rev-parse", "HEAD")}
+}
+
+func options(r remote, cache string, paths ...string) Options {
+	return Options{
+		Cache: cache,
+		Repos: []Repo{{Repo: r.url, Commit: r.commit, Paths: paths}},
+	}
+}
+
+// Every test decides for itself whether it is online.
+func isolate(t *testing.T) {
+	t.Helper()
+	t.Setenv(OfflineEnv, "")
+	t.Setenv("CI", "")
+}
+
+func names(resp plugin.Response) []string {
+	out := make([]string, 0, len(resp.Files))
+	for _, f := range resp.Files {
+		out = append(out, f.Name)
+	}
+	sort.Strings(out)
+
+	return out
+}
+
+func contentsOf(resp plugin.Response, name string) string {
+	for _, f := range resp.Files {
+		if f.Name == name {
+			return f.Contents
+		}
+	}
+
+	return ""
+}
+
+// write does what the host does with a response.
+func write(t *testing.T, dir string, resp plugin.Response) {
+	t.Helper()
+	for _, f := range resp.Files {
+		at := filepath.Join(dir, filepath.FromSlash(f.Name))
+		if err := os.MkdirAll(filepath.Dir(at), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(at, []byte(f.Contents), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestFetchWritesTheNarrowedCopyAndALock(t *testing.T) {
+	isolate(t)
+	r := repository(t)
+
+	resp, err := fetch(options(r, t.TempDir(), "services/oms", "proto"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The directory is owner/name, read off the URL; the paths inside are
+	// the repository's own, so an extractor can read the copy as a checkout.
+	dir := filepath.Base(filepath.Dir(strings.TrimPrefix(r.url, "file://"))) + "/" + filepath.Base(strings.TrimPrefix(r.url, "file://"))
+	want := []string{
+		dir + "/git.lock.json",
+		dir + "/git.repo.json",
+		dir + "/proto/shop/v1/orders.proto",
+		dir + "/services/oms/README.md",
+		dir + "/services/oms/internal/domain/order/order.go",
+	}
+	if got := names(resp); strings.Join(got, "\n") != strings.Join(want, "\n") {
+		t.Fatalf("files = %v, want %v", got, want)
+	}
+	lock := contentsOf(resp, dir+"/git.lock.json")
+	if !strings.Contains(lock, `"commit": "`+r.commit+`"`) || !strings.Contains(lock, `"sha256"`) || !strings.Contains(lock, `"services/oms"`) {
+		t.Errorf("lock = %s", lock)
+	}
+	if len(resp.Warnings()) != 0 {
+		t.Errorf("diagnostics = %+v", resp.Warnings())
+	}
+
+	// The fragment is the lock's commit said in the shape the catalog reads,
+	// and it is a catalog: empty lists rather than absent ones, so the merge
+	// never has to tell "no contexts" from "not a source".
+	fragment := contentsOf(resp, dir+"/git.repo.json")
+	if !strings.Contains(fragment, `"commit": "`+r.commit+`"`) {
+		t.Errorf("fragment does not pin the fetched commit: %s", fragment)
+	}
+	for _, empty := range []string{`"contexts": []`, `"defs": {}`, `"flows": []`, `"adrs": []`} {
+		if !strings.Contains(fragment, empty) {
+			t.Errorf("fragment is missing %s: %s", empty, fragment)
+		}
+	}
+}
+
+func TestOfflineReplayIsByteIdentical(t *testing.T) {
+	isolate(t)
+	r := repository(t)
+	cache := t.TempDir()
+
+	online, err := fetch(options(r, cache, "services/oms"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	write(t, cache, online)
+
+	t.Setenv(OfflineEnv, "1")
+	replayed, err := fetch(options(r, cache, "services/oms"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Join(names(online), "\n") != strings.Join(names(replayed), "\n") {
+		t.Fatalf("offline names = %v, online %v", names(replayed), names(online))
+	}
+	for _, f := range online.Files {
+		if contentsOf(replayed, f.Name) != f.Contents {
+			t.Errorf("%s differs offline", f.Name)
+		}
+	}
+	if len(replayed.Warnings()) != 1 || !strings.Contains(replayed.Warnings()[0].Message, "offline") {
+		t.Errorf("diagnostics = %+v, want the one saying the copy was used", replayed.Warnings())
+	}
+}
+
+func TestCiImpliesOffline(t *testing.T) {
+	isolate(t)
+	r := repository(t)
+	cache := t.TempDir()
+	online, err := fetch(options(r, cache, "proto"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	write(t, cache, online)
+
+	t.Setenv("CI", "true")
+	replayed, err := fetch(options(r, cache, "proto"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(replayed.Warnings()) != 1 {
+		t.Errorf("CI should replay and say so: %+v", replayed.Warnings())
+	}
+}
+
+func TestEditedCacheIsReportedByPath(t *testing.T) {
+	isolate(t)
+	r := repository(t)
+	cache := t.TempDir()
+	online, err := fetch(options(r, cache, "services/oms"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	write(t, cache, online)
+
+	var edited string
+	for _, name := range names(online) {
+		if strings.HasSuffix(name, "order.go") {
+			edited = name
+		}
+	}
+	if err := os.WriteFile(filepath.Join(cache, filepath.FromSlash(edited)), []byte("package order // edited\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Setenv(OfflineEnv, "1")
+	_, err = fetch(options(r, cache, "services/oms"))
+	if err == nil || !strings.Contains(err.Error(), "order.go") || !strings.Contains(err.Error(), "edited by hand") {
+		t.Fatalf("err = %v, want the edited file named", err)
+	}
+}
+
+func TestOfflineWithNoCacheFailsRatherThanEmittingNothing(t *testing.T) {
+	isolate(t)
+	t.Setenv(OfflineEnv, "1")
+	resp, err := fetch(options(remote{url: "file:///nowhere/acme/shop", commit: "0000000000000000000000000000000000000000"}, t.TempDir()))
+	if err == nil || len(resp.Files) != 0 {
+		t.Fatalf("err = %v, files = %v", err, names(resp))
+	}
+}
+
+func TestFailedFetchWithNoCacheFails(t *testing.T) {
+	isolate(t)
+	_, err := fetch(options(remote{url: "file://" + filepath.Join(t.TempDir(), "acme", "gone"), commit: "0000000000000000000000000000000000000000"}, t.TempDir()))
+	if err == nil || !strings.Contains(err.Error(), "no usable copy") {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+func TestFailedFetchFallsBackToTheCommittedCopy(t *testing.T) {
+	isolate(t)
+	r := repository(t)
+	cache := t.TempDir()
+	online, err := fetch(options(r, cache, "proto"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	write(t, cache, online)
+
+	// The forge is gone; the URL is the same, so the copy is in the same place.
+	if err := os.RemoveAll(strings.TrimPrefix(r.url, "file://")); err != nil {
+		t.Fatal(err)
+	}
+	fallback, err := fetch(options(r, cache, "proto"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Join(names(fallback), "\n") != strings.Join(names(online), "\n") {
+		t.Errorf("fallback = %v", names(fallback))
+	}
+	if len(fallback.Warnings()) != 1 || !strings.Contains(fallback.Warnings()[0].Message, "not fetched") {
+		t.Errorf("diagnostics = %+v", fallback.Warnings())
+	}
+}
+
+func TestUnpinnedRepositoryIsResolvedOnlineAndRefusedOffline(t *testing.T) {
+	isolate(t)
+	r := repository(t)
+	opts := Options{Cache: t.TempDir(), Repos: []Repo{{Repo: r.url, Ref: "main", Paths: []string{"proto"}}}}
+
+	resp, err := fetch(opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(resp.Warnings()) != 1 || !strings.Contains(resp.Warnings()[0].Message, "not pinned") || !strings.Contains(resp.Warnings()[0].Message, r.commit) {
+		t.Errorf("diagnostics = %+v", resp.Warnings())
+	}
+
+	t.Setenv(OfflineEnv, "1")
+	if _, err := fetch(opts); err == nil || !strings.Contains(err.Error(), "not pinned") {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+// A remote that does not serve commits by name still serves its branches,
+// and the commit is found among them.
+func TestACommitIsFetchedThroughItsBranchWhenTheRemoteRefusesIt(t *testing.T) {
+	isolate(t)
+	r := repository(t)
+	cmd := exec.Command("git", "config", "--unset", "uploadpack.allowAnySHA1InWant")
+	cmd.Dir = strings.TrimPrefix(r.url, "file://")
+	if out, err := cmd.CombinedOutput(); err != nil {
+		t.Fatalf("%v: %s", err, out)
+	}
+
+	resp, err := fetch(options(r, t.TempDir(), "README.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The file, the lock, and the fragment naming the commit.
+	if got := names(resp); len(got) != 3 {
+		t.Errorf("files = %v", got)
+	}
+}
+
+func TestSplitRepo(t *testing.T) {
+	cases := map[string]string{
+		"github.com/acme/shop":              "https://github.com/acme/shop|acme/shop",
+		"https://gitlab.com/acme/shop.git":  "https://gitlab.com/acme/shop.git|acme/shop",
+		"git@github.com:acme/shop.git":      "git@github.com:acme/shop.git|acme/shop",
+		"ssh://git@github.com/acme/shop":    "ssh://git@github.com/acme/shop|acme/shop",
+		"https://gitlab.com/org/group/shop": "https://gitlab.com/org/group/shop|group/shop",
+	}
+	for name, want := range cases {
+		url, dir, err := splitRepo(name)
+		if err != nil || url+"|"+dir != want {
+			t.Errorf("%s = %s|%s %v, want %s", name, url, dir, err, want)
+		}
+	}
+	if _, _, err := splitRepo("shop"); err == nil {
+		t.Error("a bare name has no owner and should be refused")
+	}
+}

package/plugins/fetch-git/git.go

@@ -0,0 +1,169 @@
+package main
+
+// The only file that runs git.
+//
+// The host already needs a git binary to stamp fragments, so this leans on
+// the same one rather than on a library: whatever git is configured to do
+// about credentials and hosts, it does here too, and this plugin has no
+// opinion about it. Everything happens in a directory that exists for one
+// call: a fetch of the one commit, and an archive of the paths wanted, read
+// straight into memory.
+
+import (
+	"archive/tar"
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path"
+	"strings"
+)
+
+// splitRepo turns the name the manifest uses into a URL git can fetch and
+// the directory the copy lives in: owner/name, the same shape as fetch-bsr.
+func splitRepo(name string) (url, dir string, err error) {
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return "", "", fmt.Errorf("a repo entry names no repository")
+	}
+
+	var where string
+	switch {
+	case strings.HasPrefix(name, "git@"):
+		// git@host:owner/name
+		url = name
+		_, where, _ = strings.Cut(name, ":")
+	case strings.Contains(name, "://"):
+		url = name
+		_, where, _ = strings.Cut(name, "://")
+		if i := strings.Index(where, "/"); i >= 0 {
+			where = where[i+1:]
+		}
+	default:
+		// host/owner/name, the way go.mod spells it.
+		url = "https://" + name
+		if i := strings.Index(name, "/"); i >= 0 {
+			where = name[i+1:]
+		}
+	}
+
+	where = strings.TrimSuffix(strings.Trim(where, "/"), ".git")
+	segments := strings.Split(where, "/")
+	if len(segments) < 2 {
+		return "", "", fmt.Errorf("%q does not name an owner and a repository", name)
+	}
+	dir = path.Join(segments[len(segments)-2], segments[len(segments)-1])
+
+	return url, dir, nil
+}
+
+// git runs one command and answers with its output, or with what it printed
+// on stderr when it failed. Prompts are off: a fetch that needs a credential
+// git does not have is a failure to report, not a question to hang on.
+func git(dir string, args ...string) ([]byte, error) {
+	cmd := exec.Command("git", args...)
+	cmd.Dir = dir
+	cmd.Env = append(os.Environ(), "GIT_TERMINAL_PROMPT=0")
+	var stderr bytes.Buffer
+	cmd.Stderr = &stderr
+	out, err := cmd.Output()
+	if err != nil {
+		msg := strings.TrimSpace(stderr.String())
+		if msg == "" {
+			msg = err.Error()
+		}
+
+		return nil, errors.New("git " + args[0] + ": " + firstLine(msg))
+	}
+
+	return out, nil
+}
+
+func firstLine(s string) string {
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		return s[:i]
+	}
+
+	return s
+}
+
+// resolve asks the remote what a ref points at right now.
+func resolve(url, ref string) (string, error) {
+	args := []string{"ls-remote", "--quiet", url}
+	if ref != "" {
+		args = append(args, ref)
+	} else {
+		args = append(args, "HEAD")
+	}
+	out, err := git("", args...)
+	if err != nil {
+		return "", err
+	}
+	for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+		fields := strings.Fields(line)
+		if len(fields) >= 1 && len(fields[0]) == 40 {
+			return fields[0], nil
+		}
+	}
+
+	return "", fmt.Errorf("%s has no ref %q", url, firstNonEmpty(ref, "HEAD"))
+}
+
+// download fetches one commit and reads the wanted paths out of it.
+//
+// The commit is fetched by name where the forge allows it - GitHub and GitLab
+// do - and by its branches where it does not, which is the case for a plain
+// file:// remote; either way what is read is verified to be that commit.
+func download(url, commit string, paths []string) (map[string][]byte, error) {
+	tmp, err := os.MkdirTemp("", "portolan-fetch-git-")
+	if err != nil {
+		return nil, err
+	}
+	defer os.RemoveAll(tmp)
+
+	if _, err := git(tmp, "init", "--quiet"); err != nil {
+		return nil, err
+	}
+	if _, err := git(tmp, "fetch", "--quiet", "--depth", "1", url, commit); err != nil {
+		if _, fallback := git(tmp, "fetch", "--quiet", "--depth", "1", url, "+refs/heads/*:refs/remotes/src/*"); fallback != nil {
+			return nil, err
+		}
+	}
+	if _, err := git(tmp, "cat-file", "-e", commit+"^{commit}"); err != nil {
+		return nil, fmt.Errorf("%s is not a commit %s has, or not one reachable from a branch", commit, url)
+	}
+
+	args := []string{"archive", "--format=tar", commit}
+	if len(paths) > 0 {
+		args = append(args, "--")
+		args = append(args, paths...)
+	}
+	archive, err := git(tmp, args...)
+	if err != nil {
+		return nil, err
+	}
+
+	files := map[string][]byte{}
+	reader := tar.NewReader(bytes.NewReader(archive))
+	for {
+		header, err := reader.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return nil, err
+		}
+		if header.Typeflag != tar.TypeReg {
+			continue
+		}
+		content, err := io.ReadAll(reader)
+		if err != nil {
+			return nil, err
+		}
+		files[path.Clean(header.Name)] = content
+	}
+
+	return files, nil
+}

package/plugins/fetch-git/lock.go

@@ -0,0 +1,72 @@
+package main
+
+// What was fetched, so it can be checked without fetching again.
+//
+// One lock per repository directory rather than one for the whole step, so a
+// vendored copy is self-describing: the files and the statement of where they
+// came from sit together.
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"sort"
+)
+
+// LockName is the file written beside each repository's copy.
+const LockName = "git.lock.json"
+
+type Lock struct {
+	Repos []LockRepo `json:"repos"`
+}
+
+type LockRepo struct {
+	Repo string `json:"repo"`
+
+	// Commit is what was actually fetched. A commit is immutable, so a pinned
+	// fetch is byte-reproducible and this is what makes replaying from disk
+	// equivalent to fetching again.
+	Commit string `json:"commit"`
+
+	// Paths is the narrowing the copy was made with, so a wider or narrower
+	// manifest is a change to the copy rather than a mystery.
+	Paths []string `json:"paths,omitempty"`
+
+	Files []LockEntry `json:"files"`
+}
+
+type LockEntry struct {
+	Path string `json:"path"`
+
+	// SHA256 is over the bytes as written. It is what turns a cache into
+	// something checkable: a vendored copy someone edited by hand stops
+	// matching, which is exactly the drift docs/adr/org.0001.md wants visible.
+	SHA256 string `json:"sha256"`
+	Size   int    `json:"size"`
+}
+
+func digestOf(content []byte) string {
+	sum := sha256.Sum256(content)
+
+	return hex.EncodeToString(sum[:])
+}
+
+// encode writes the lock the way every generated file in this repository is
+// written: sorted, indented, newline-terminated. It is committed and compared
+// by `gen:check`, so an unstable order would rewrite it on every run.
+func (l Lock) encode() (string, error) {
+	for i := range l.Repos {
+		sort.Slice(l.Repos[i].Files, func(a, b int) bool {
+			return l.Repos[i].Files[a].Path < l.Repos[i].Files[b].Path
+		})
+		sort.Strings(l.Repos[i].Paths)
+	}
+	sort.Slice(l.Repos, func(a, b int) bool { return l.Repos[a].Repo < l.Repos[b].Repo })
+
+	out, err := json.MarshalIndent(l, "", "  ")
+	if err != nil {
+		return "", err
+	}
+
+	return string(out) + "\n", nil
+}

package/plugins/fetch-git/main.go

@@ -0,0 +1,127 @@
+// Package main is portolan-fetch-git: a git repository on one side, a narrowed
+// copy of it committed to this repository on the other.
+//
+// It exists for the estate whose services live in repositories of their own.
+// An extractor reads one tree, and reads it as a pure function of what is on
+// disk; fetching is the step that can fail, need a credential, or come back
+// with something different than it did yesterday. Keeping the two apart is
+// what lets CI verify an estate it never clones.
+//
+// The fetched files are the plugin's Response.Files, not a side effect. The
+// host writes them, so they get a manifest entry, are compared by `gen:check`
+// like any other generated file, and are removed when the step stops naming
+// them. Paths inside the copy are the repository's own, so the extract step
+// that follows points its `in` at the vendored service and reads it exactly
+// as it would read the service's own checkout. Refreshing a pin then produces
+// ONE pull request holding the pin bump, the source diff, the lock diff and
+// the fragment diff - which is the review worth having.
+//
+// Two files land beside each copy. `git.lock.json` is for the next run of this
+// step - the commit and every file's digest, which is what makes replaying it
+// equivalent to fetching again. `git.repo.json` is for the estate: a catalog
+// fragment naming the repository and the commit, which is the only way that
+// fact reaches a page. Nothing downstream can work it out - a service says
+// which repository it lives in, and an extractor reads a directory as a pure
+// function of what is on disk - so without it a vendored service's source
+// paths are text nobody can open. It has to be matched by `sources` in the
+// manifest, and by SOURCE_GLOBS in src/data.ts, to be read.
+//
+// It is not wired into portolan.json until there is a second repository. The
+// manifest it expects:
+//
+//	{
+//	  "sources": ["data/*.json", "vendor/repos/*/*/git.repo.json"],
+//	  "plugins": [
+//	    { "name": "git", "process": { "command": "go", "args": ["run", "./plugins/fetch-git"] } }
+//	  ],
+//	  "extract": [
+//	    {
+//	      "plugin": "git",
+//	      "in": "vendor",
+//	      "out": "vendor/repos",
+//	      "options": {
+//	        "cache": "vendor/repos",
+//	        "repos": [
+//	          {
+//	            "repo": "github.com/acme/shop",
+//	            "commit": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0",
+//	            "paths": ["services/oms", "proto"]
+//	          }
+//	        ]
+//	      }
+//	    },
+//	    {
+//	      "plugin": "go-domain",
+//	      "in": "vendor/repos/acme/shop/services/oms",
+//	      "out": "data/shop",
+//	      "options": { "context": "shop", "service": "oms", "store": "pg" }
+//	    }
+//	  ]
+//	}
+//
+// The git step is declared FIRST: extract steps run in list order, so the copy
+// and its lock are on disk by the time the extractors read them.
+//
+// In CI, set PORTOLAN_OFFLINE=1. The step then replays the committed copies,
+// checks them against their locks and emits an identical file list, so a fork's
+// pull request needs no credential and a forge being down cannot turn the tree
+// red.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are what the manifest tells the fetcher.
+//
+// No credential, ever. portolan.json is committed; git reaches the forge with
+// whatever it is configured with - a credential helper, a netrc entry, an ssh
+// agent - and this plugin reads none of it.
+type Options struct {
+	Repos []Repo `json:"repos"`
+
+	// Cache is where the last run's files were written, repo-relative, and
+	// should be the same path as the step's `out`.
+	//
+	// Stated twice because a plugin is never told where its output goes. That
+	// is the whole shape of the protocol - a plugin returns files and the host
+	// decides what to do with them - and not an oversight to work around.
+	Cache string `json:"cache"`
+}
+
+type Repo struct {
+	// Repo is where the repository is: "github.com/acme/shop", or any URL git
+	// accepts - https://, ssh://, git@host:owner/name.
+	Repo string `json:"repo"`
+
+	// Commit pins it. A commit is immutable, so a pinned fetch is
+	// byte-reproducible - which is the only reason replaying from disk is
+	// equivalent to fetching again. Leaving it out is allowed and warned about;
+	// offline it is refused, because there is nothing to replay against.
+	Commit string `json:"commit,omitempty"`
+
+	// Ref is the branch or tag to resolve when there is no commit. Defaults to
+	// the remote's HEAD.
+	Ref string `json:"ref,omitempty"`
+
+	// Paths narrows the copy to the directories actually read, which is how a
+	// vendored repository stays small. Left out, the whole tree.
+	Paths []string `json:"paths,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-fetch-git:", err)
+		os.Exit(1)
+	}
+}
+
+func run(stdin io.Reader, stdout io.Writer) error {
+	return plugin.Serve(stdin, stdout, descriptor(), func(_ plugin.Request, opts Options) (plugin.Response, error) {
+		return fetch(opts)
+	})
+}