Write Your Own
Dependency Detectors

Repo Man can back up the dependencies of any repository — not just Swift packages and Git submodules. Write a small JavaScript plugin to teach it how to read your ecosystem's lock file, and it will automatically mirror those dependencies on every backup run.

Overview

Repo Man's backup engine discovers dependencies by running detectors against each cloned bare repository. Two detectors ship built in:

• Submodule Detection — reads .gitmodules
• Swift Package Detection — reads Package.resolved

The Integrations system lets you add detectors written in JavaScript. A plugin is a single .js file that declares which manifest files it cares about, and exposes a detect() function that parses them. Repo Man handles all file I/O and calls your function with the raw text content — you just parse it and return a list of Git repository URLs to back up.

Quickstart

Here is the smallest valid plugin. It detects Go modules by reading go.sum and extracting any entries that point to a GitHub repository.

// 1. Stable identifier — becomes the backup subfolder name.
const kindLabel = "go-modules";

// 2. Human-readable name shown in Settings → Integrations.
const displayName = "Go Modules";

// 3. Filenames to search for. Repo Man finds ALL occurrences
//    anywhere in the repository tree and calls detect() for each.
const manifestFileNames = ["go.mod"];

// 4. Parse function. Called once per found file.
//    fileContent : string — raw text of the file
//    filePath    : string — path within the repo (e.g. "go.mod")
//    Returns     : array of { url: string, name: string }
function detect(fileContent, filePath) {
    var results = [];
    var seen = {};
    var lines = fileContent.split("\n");

    for (var i = 0; i < lines.length; i++) {
        var m = lines[i].match(/^\s+([^\s]+)\s+v/);
        if (!m) continue;
        var module = m[1];
        var url = "https://" + module;
        if (seen[url]) continue;
        seen[url] = true;
        results.push({ url: url, name: module.split("/").pop() });
    }
    return results;
}

Importing a Plugin

1. Open Repo Man → Settings (⌘,) and click the Integrations tab.

2. Click the + button in the "Custom Integrations" section header.

3. Select your .js plugin file in the file picker.

4. Repo Man validates the script. If anything is missing or wrong you will see an error describing the problem. Otherwise the plugin appears in the list and is enabled immediately.

5. Run a backup. Repo Man will call your plugin against every repository it clones.

Metadata Fields

Every plugin must declare three top-level constants before the detect() function. They must be const or var declarations at the global scope — not inside any function or block.

The detect() Function

Parameters

Return Value

detect() must return an array of dependency objects. Each object must have exactly two string properties:

Objects missing either property, or where either value is an empty string, are silently skipped. Returning an empty array ([]) is valid and means no dependencies were found.

// ✓ Valid return value
return [
    { url: "https://github.com/owner/repo",       name: "repo"        },
    { url: "https://github.com/another/package.git", name: "package"     },
    { url: "git@github.com:owner/private.git",      name: "private-dep" },
];

// ✓ Valid — no dependencies found
return [];

// ✗ These entries will be silently dropped
return [
    { url: "",    name: "bad"  },  // empty url
    { url: "https://…"          },  // missing name
    null,                           // not an object
];

What the Host Does

Understanding the host's role helps you write correct plugins and avoid duplication.

File discovery

For each filename listed in your manifestFileNames array, Repo Man recursively walks the entire repository tree using libgit2 and collects all paths whose final component matches exactly. This is done in-process and is fully macOS sandbox-compatible — no shell commands are spawned.

URL deduplication

Repo Man deduplicates returned URLs both within a single detect() call and across multiple calls in the same backup session. If your plugin returns the same URL from two different branches, or two different plugins return the same URL, it is only cloned once.

Credential reuse

Dependencies discovered by your plugin are backed up using the same credentials as the parent repository. If the parent was cloned via HTTPS with a GitHub token, dependencies on the same host will also use that token. SSH dependencies fall back to the SSH agent.

Backup path

Detected repositories are backed up to:

<backupRoot> / <kindLabel> / <host> / <path>.git

For example, a plugin with kindLabel = "npm-packages" that returns https://github.com/lodash/lodash would produce:

~/Git-Backups/npm-packages/github.com/lodash/lodash.git

Sandbox Model

Plugins run inside a bare JavaScriptCore context with additional hardening applied by the host. This means:

• No file system access — there is no fs, require, import, or any Node.js / browser API.
• No network access — there is no fetch, XMLHttpRequest, or WebSocket.
• No timers — setTimeout, setInterval, and requestAnimationFrame are not available.
• No native modules — require() does not exist.
• No DOM — this is not a browser context.
• eval is disabled — replaced with an inert no-op that returns undefined.
• Function constructor is disabled — new Function("code") throws a TypeError.
• Objective-C bridge blocked — ObjC and $ globals are explicitly nulled out.
• Execution timeout — each detect() call is limited to 10 seconds of wall-clock time. See Runtime Limits.

What is available: the full ECMAScript 5/6 standard library — JSON, Array, String, RegExp, Math, Object, Map, Set, and so on.

Validation at Import Time

When you import a plugin, Repo Man validates it before saving. Import will be rejected with a descriptive error if any of the following conditions are met:

Validation errors during a backup run (e.g. detect() throws or times out) are logged to the system log under the category ScriptedDependencyDetector and silently skipped.

Example — Node.js / npm

Parses package-lock.json (lockfileVersion 1, 2, and 3). Only packages with a Git clone URL in their resolved field are returned — tarball URLs from the npm registry are ignored.

const kindLabel = "npm-packages";
const displayName = "Node.js (npm)";
const manifestFileNames = ["package-lock.json"];

function detect(fileContent, filePath) {
    var lock;
    try { lock = JSON.parse(fileContent); } catch (e) { return []; }

    var results = [], seen = {};

    function addIfGit(url, name) {
        if (!url || seen[url]) return;
        if (url.indexOf("git+") === 0 || url.indexOf("git://") === 0) {
            var clone = url.replace(/^git\+/, "");
            seen[clone] = true;
            results.push({ url: clone, name: name });
        }
    }

    // lockfileVersion 2/3 — top-level "packages" map
    if (lock.packages) {
        Object.keys(lock.packages).forEach(function(key) {
            if (key === "") return;
            var pkg = lock.packages[key];
            var name = key.replace(/^node_modules\//, "").split("/").pop();
            addIfGit(pkg.resolved, name);
        });
        return results;
    }

    // lockfileVersion 1 — top-level "dependencies" map
    if (lock.dependencies) {
        Object.keys(lock.dependencies).forEach(function(name) {
            addIfGit(lock.dependencies[name].resolved, name);
        });
    }
    return results;
}

Example — CocoaPods

Parses Podfile.lock and extracts pods whose source is a Git repository (declared with :git:). Registry pods resolved as tarballs are ignored.

const kindLabel = "cocoapods";
const displayName = "CocoaPods";
const manifestFileNames = ["Podfile.lock"];

function detect(fileContent, filePath) {
    var results = [], seen = {};
    // Match ":git: <url>" lines in EXTERNAL SOURCES / CHECKOUT OPTIONS sections.
    var re = /^\s+:git:\s+(.+?)\s*$/gm;
    var m;
    while ((m = re.exec(fileContent)) !== null) {
        var url = m[1].trim();
        if (url && !seen[url]) {
            seen[url] = true;
            results.push({ url: url, name: url.split("/").pop().replace(/\.git$/, "") });
        }
    }
    return results;
}

Example — Cargo (Rust)

Parses Cargo.lock (v3 TOML format) and returns crates sourced from Git repositories. Crates.io registry entries are ignored.

const kindLabel = "cargo";
const displayName = "Cargo (Rust)";
const manifestFileNames = ["Cargo.lock"];

function detect(fileContent, filePath) {
    var results = [], seen = {};
    var blocks = fileContent.split(/\[\[package\]\]/);

    for (var i = 1; i < blocks.length; i++) {
        var block = blocks[i];
        var nm  = block.match(/^\s*name\s*=\s*"([^"]+)"/m);
        var src = block.match(/^\s*source\s*=\s*"([^"]+)"/m);
        if (!nm || !src || src[1].indexOf("git+") !== 0) continue;
        var url = src[1].replace(/^git\+/, "").replace(/#[^#]*$/, "");
        if (url && !seen[url]) {
            seen[url] = true;
            results.push({ url: url, name: nm[1] });
        }
    }
    return results;
}

Example — Ruby Gems (Bundler)

Parses Gemfile.lock and returns gems sourced from Git repositories (GIT sections). RubyGems.org registry gems are ignored.

const kindLabel = "ruby-gems";
const displayName = "Ruby Gems (Bundler)";
const manifestFileNames = ["Gemfile.lock"];

function detect(fileContent, filePath) {
    var results = [], seen = {};
    var sections = fileContent.split(/^GIT\s*$/m);

    for (var i = 1; i < sections.length; i++) {
        var end = sections[i].search(/^\S/m);
        var block = end > -1 ? sections[i].substring(0, end) : sections[i];
        var m = block.match(/^\s+remote:\s+(.+?)\s*$/m);
        if (!m) continue;
        var url = m[1].trim();
        if (url && !seen[url]) {
            seen[url] = true;
            results.push({ url: url, name: url.split("/").pop().replace(/\.git$/, "") });
        }
    }
    return results;
}

.NET / NuGet

Parses packages.lock.json (NuGet v2 lock file). Only packages with a resolved field containing a GitHub or GitLab URL are returned.

const kindLabel = "nuget-packages";
const displayName = ".NET / NuGet";
const manifestFileNames = ["packages.lock.json"];

function detect(fileContent, filePath) {
    var lock;
    try { lock = JSON.parse(fileContent); } catch (e) { return []; }

    var results = [], seen = {};
    var deps = lock.dependencies || {};
    Object.keys(deps).forEach(function(framework) {
        var pkgs = deps[framework] || {};
        Object.keys(pkgs).forEach(function(pkgName) {
            var url = (pkgs[pkgName].resolved || "");
            if (
                (url.indexOf("https://github.com") === 0 ||
                 url.indexOf("https://gitlab.com") === 0) &&
                !seen[url]
            ) {
                seen[url] = true;
                results.push({ url: url, name: pkgName });
            }
        });
    });
    return results;
}

Example — Go Modules

Parses go.mod and extracts module paths on GitHub, GitLab, or Bitbucket. Other module paths are skipped since they may not correspond to a public Git repository.

const kindLabel = "go-modules";
const displayName = "Go Modules";
const manifestFileNames = ["go.mod"];

function detect(fileContent, filePath) {
    var results = [], seen = {};
    var knownHosts = ["github.com", "gitlab.com", "bitbucket.org"];
    var re = /^\s*(?:require\s+)?([^\s]+)\s+v[\d]/gm;
    var m;
    while ((m = re.exec(fileContent)) !== null) {
        var mod = m[1].trim();
        var host = mod.split("/")[0];
        if (knownHosts.indexOf(host) === -1) continue;
        var url = "https://" + mod;
        if (!seen[url]) {
            seen[url] = true;
            results.push({ url: url, name: mod.split("/").pop() });
        }
    }
    return results;
}

Kind Label Rules

The kindLabel is used as a directory name on disk, so it must be filesystem-safe and stable. All rules below are enforced at import time.

• Allowed characters: lowercase letters (a–z), digits (0–9), and hyphens (-) only.
• No leading or trailing hyphen: -go and go- are both invalid.
• Exact pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
• Must be unique across all installed plugins and the two built-ins (submodules, swift-packages).
• Treat it as permanent: changing it orphans old backups on disk.

URL Formats

Repo Man accepts HTTPS and SSH clone URLs. The host enforces a URL scheme allowlist — results with any other scheme are silently dropped before cloning begins.

Runtime Limits

The host enforces the following hard limits on every plugin execution.

Error Handling

In detect()

Wrap any parsing that might fail in a try/catch and return [] on error. An unhandled exception thrown from detect() will be caught by the host, logged to the system log, and treated as "no dependencies found" — the backup continues normally.

function detect(fileContent, filePath) {
    var data;
    try {
        data = JSON.parse(fileContent);
    } catch (e) {
        return []; // host logs the exception automatically
    }
    if (!data || typeof data !== "object") return [];
    // ... rest of parsing ...
    return results;
}

Viewing errors

Plugin errors are written to the macOS system log. To view them, open Console.app and filter by:

• Subsystem: com.corybohon.Repo-Man
• Category: ScriptedDependencyDetector

Or stream them in Terminal:

log stream --predicate 'subsystem == "com.corybohon.Repo-Man" AND category == "ScriptedDependencyDetector"' --level debug

Tips & Patterns

Deduplicate within detect()

Repo Man deduplicates URLs across calls, but doing it inside your plugin too avoids redundant work on large lock files.

var seen = {};
function add(url, name) {
    if (url && !seen[url]) { seen[url] = true; results.push({ url: url, name: name }); }
}

Filtering by path in monorepos

The filePath parameter lets you skip manifest files in irrelevant subdirectories:

function detect(fileContent, filePath) {
    if (filePath.indexOf("test/")   !== -1) return [];
    if (filePath.indexOf("vendor/") !== -1) return [];
    // ... parse ...
}

Deriving a name from a URL

function nameFromURL(url) {
    return url.replace(/\.git$/, "").split("/").pop() || url;
}

Testing before import

You can test your plugin logic in any browser's DevTools console or in Node.js before importing it into Repo Man. Because the API surface is just plain functions and JSON, writing a small test harness is easy:

// test-harness.js (run with: node test-harness.js)
const fs = require("fs");
eval(fs.readFileSync("my-plugin.js", "utf8"));
const sample = fs.readFileSync("sample-lock.json", "utf8");
const result = detect(sample, "package-lock.json");
console.log(result);

Multiple manifest files

If your ecosystem uses several different files, list them all in manifestFileNames and use filePath to branch on which one was found:

const manifestFileNames = ["Cargo.lock", "Cargo.toml"];

function detect(fileContent, filePath) {
    if (filePath.endsWith("Cargo.lock")) return parseLock(fileContent);
    if (filePath.endsWith("Cargo.toml")) return parseToml(fileContent);
    return [];
}