gitroster 0.2.0__py3-none-any.whl

gitroster/opener.py

@@ -0,0 +1,218 @@
+"""Open a repo in an editor, a terminal or the file manager (Linux, macOS, Windows, WSL).
+
+Editors and terminals are detected on this machine; the user picks one in Settings.
+"""
+import glob
+import os
+import shlex
+import shutil
+import subprocess
+import threading
+import sys
+import time
+
+from .pathscan import which
+
+WIN = sys.platform == "win32"
+MAC = sys.platform == "darwin"
+WSL = bool(os.environ.get("WSL_DISTRO_NAME"))
+HOME = os.path.expanduser("~")
+
+# id, label, commands on PATH, macOS app name
+EDITORS = [
+    ("code", "VS Code", ["code"], "Visual Studio Code"),
+    ("cursor", "Cursor", ["cursor"], "Cursor"),
+    ("windsurf", "Windsurf", ["windsurf"], "Windsurf"),
+    ("codium", "VSCodium", ["codium"], "VSCodium"),
+    ("zed", "Zed", ["zed"], "Zed"),
+    ("subl", "Sublime Text", ["subl"], "Sublime Text"),
+    ("pycharm", "PyCharm", ["pycharm", "pycharm-professional", "pycharm-community", "charm", "pycharm64"], "PyCharm"),
+    ("idea", "IntelliJ IDEA", ["idea", "intellij-idea-ultimate", "intellij-idea-community", "idea64"], "IntelliJ IDEA"),
+    ("webstorm", "WebStorm", ["webstorm", "webstorm64"], "WebStorm"),
+    ("phpstorm", "PhpStorm", ["phpstorm", "phpstorm64"], "PhpStorm"),
+    ("goland", "GoLand", ["goland", "goland64"], "GoLand"),
+    ("rustrover", "RustRover", ["rustrover", "rustrover64"], "RustRover"),
+    ("clion", "CLion", ["clion", "clion64"], "CLion"),
+    ("studio", "Android Studio", ["studio", "studio64"], "Android Studio"),
+    ("xed", "Xcode", ["xed"], None),
+]
+# id, label, commands, argument template ({p} = folder), macOS app
+TERMINALS = [
+    ("wt", "Windows Terminal", ["wt"], ["-d", "{p}"], None),
+    ("powershell", "PowerShell", ["pwsh", "powershell"], None, None),
+    ("cmd", "Command Prompt", ["cmd"], None, None),
+    ("Terminal", "Terminal", [], None, "Terminal"),
+    ("iTerm", "iTerm", [], None, "iTerm"),
+    ("Warp", "Warp", [], None, "Warp"),
+    ("gnome-terminal", "GNOME Terminal", ["gnome-terminal"], ["--working-directory={p}"], None),
+    ("konsole", "Konsole", ["konsole"], ["--workdir", "{p}"], None),
+    ("xfce4-terminal", "Xfce Terminal", ["xfce4-terminal"], ["--working-directory={p}"], None),
+    ("tilix", "Tilix", ["tilix"], ["-w", "{p}"], None),
+    ("kitty", "kitty", ["kitty"], ["--directory", "{p}"], None),
+    ("alacritty", "Alacritty", ["alacritty"], ["--working-directory", "{p}"], None),
+    ("wezterm", "WezTerm", ["wezterm"], ["start", "--cwd", "{p}"], None),
+    ("x-terminal-emulator", "System default", ["x-terminal-emulator"], None, None),
+]
+
+
+def _mac_app(name):
+    return bool(name) and any(os.path.isdir(f"{d}/{name}.app") or glob.glob(f"{d}/{name}*.app") for d in ("/Applications", f"{HOME}/Applications"))
+
+
+_which = which
+
+
+def _find_cmd(cmds):
+    for c in cmds:
+        found = _which(c)
+        if found:
+            return found
+    for c in cmds:  # JetBrains Toolbox installs launchers here
+        for pattern in (f"{HOME}/.local/share/JetBrains/Toolbox/scripts/{c}", f"{HOME}/Library/Application Support/JetBrains/Toolbox/scripts/{c}",
+                        f"{os.environ.get('LOCALAPPDATA', '')}/JetBrains/Toolbox/scripts/{c}.cmd"):
+            if os.path.isfile(pattern):
+                return pattern
+    return None
+
+
+def _editor_launcher(entry):
+    _, _, cmds, app = entry
+    found = _find_cmd(cmds)
+    if found:
+        return [found]
+    if MAC and _mac_app(app):
+        return ["open", "-a", app]
+    return None
+
+
+def _terminal_available(entry):
+    tid, _, cmds, _, app = entry
+    if MAC:
+        return _mac_app(app) or bool(_find_cmd(cmds))
+    if WIN:
+        return tid in ("wt", "powershell", "cmd") and bool(_find_cmd(cmds) or tid == "cmd")
+    if WSL and tid == "wt":
+        return bool(_which("wt.exe"))
+    return not app and bool(cmds) and tid not in ("wt", "powershell", "cmd") and bool(_find_cmd(cmds))
+
+
+_detected = {"at": 0, "value": None}
+_lock = threading.Lock()
+
+
+def _refresh():
+    if not _lock.acquire(blocking=False):
+        return
+    try:
+        _detected.update(value=_detect(), at=time.time())
+    finally:
+        _lock.release()
+
+
+def warm():
+    """Scan in the background at startup so the settings panel opens instantly."""
+    threading.Thread(target=_refresh, daemon=True).start()
+
+
+def detect(max_age=600):
+    """Editors and terminals found on this machine. Scanning PATH is slow on WSL, so the last result is
+    served at once and refreshed in the background when it is stale."""
+    if _detected["value"] is None:
+        with _lock:  # waits for a background scan that is already running instead of returning nothing
+            if _detected["value"] is None:
+                _detected.update(value=_detect(), at=time.time())
+    elif time.time() - _detected["at"] > max_age:
+        warm()
+    return _detected["value"]
+
+
+def _detect():
+    editors = [{"id": e[0], "label": e[1]} for e in EDITORS if _editor_launcher(e)]
+    terminals = [{"id": t[0], "label": t[1]} for t in TERMINALS if _terminal_available(t)]
+    return {"editors": editors, "terminals": terminals}
+
+
+def _spawn(cmd, cwd=None, shell=False):
+    kw = {"creationflags": 0x08000200} if WIN else {"start_new_session": True}
+    subprocess.Popen(cmd, cwd=cwd, shell=shell, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                     stderr=subprocess.DEVNULL, **kw)
+
+
+def _win_path(path):
+    out = subprocess.run(["wslpath", "-w", path], capture_output=True, text=True).stdout.strip()
+    return out or path
+
+
+def editor_cmd(settings):
+    """Chosen editor, else $GITROSTER_EDITOR, else the first detected one. -> (command list, label)"""
+    choice = (settings or {}).get("editor", "")
+    if choice == "custom" and settings.get("editor_custom"):
+        return shlex.split(settings["editor_custom"]), "custom editor"
+    for e in EDITORS:
+        if e[0] == choice:
+            cmd = _editor_launcher(e)
+            if cmd:
+                return cmd, e[1]
+    custom = os.environ.get("GITROSTER_EDITOR")
+    if custom:
+        return shlex.split(custom), custom
+    for e in EDITORS:
+        cmd = _editor_launcher(e)
+        if cmd:
+            return cmd, e[1]
+    return None, ""
+
+
+def _terminal_entry(settings):
+    want = (settings or {}).get("terminal", "")
+    avail = [t for t in TERMINALS if _terminal_available(t)]
+    return next((t for t in avail if t[0] == want), avail[0] if avail else None)
+
+
+def _open_terminal(path, settings):
+    t = _terminal_entry(settings)
+    if not t:
+        raise RuntimeError("no terminal found; pick one in Settings")
+    tid, label, cmds, args, app = t
+    if MAC:
+        if app and _mac_app(app):
+            _spawn(["open", "-a", app, path])
+        else:
+            _spawn([_find_cmd(cmds), *[a.replace("{p}", path) for a in (args or [])]], cwd=path)
+    elif WIN:
+        if tid == "wt":
+            _spawn(["wt", "-d", path])
+        elif tid == "powershell":
+            _spawn(["cmd", "/c", "start", cmds[0], "-NoExit", "-Command", f"Set-Location -LiteralPath '{path}'"])
+        else:
+            _spawn(["cmd", "/c", "start", "cmd", "/k", f'cd /d "{path}"'])
+    elif WSL and tid == "wt":
+        _spawn(["wt.exe", "-d", _win_path(path), "wsl.exe", "--cd", path])
+    else:
+        _spawn([_find_cmd(cmds), *[a.replace("{p}", path) for a in (args or [])]], cwd=path)
+    return label
+
+
+def open_repo(path, target, settings=None):
+    if not os.path.isdir(path):
+        raise ValueError("folder no longer exists")
+    if target == "editor":
+        cmd, label = editor_cmd(settings)
+        if not cmd:
+            raise RuntimeError("no editor found; pick one in Settings")
+        full = [*cmd, path]
+        _spawn(subprocess.list2cmdline(full) if WIN else full, shell=WIN)
+        return label
+    if target == "folder":
+        if WIN:
+            os.startfile(path)
+        elif MAC:
+            _spawn(["open", path])
+        elif WSL and _which("explorer.exe"):
+            _spawn(["explorer.exe", _win_path(path)])
+        else:
+            _spawn(["xdg-open", path])
+        return "file manager"
+    if target == "terminal":
+        return _open_terminal(path, settings)
+    raise ValueError("unknown target")

gitroster/pathscan.py

@@ -0,0 +1,34 @@
+"""Find programs on PATH quickly.
+
+shutil.which stats every command in every PATH folder, which takes seconds on WSL where the
+Windows folders are on a slow mount. Listing each folder once and looking names up is much faster.
+"""
+import os
+import sys
+import time
+
+WIN = sys.platform == "win32"
+_index = {"at": 0.0, "map": {}}
+
+
+def index():
+    if not _index["map"] or time.time() - _index["at"] > 60:
+        found = {}
+        for d in os.environ.get("PATH", "").split(os.pathsep):
+            try:
+                names = os.listdir(d)
+            except OSError:
+                continue
+            for n in names:
+                full = os.path.join(d, n)
+                found.setdefault(n, full)
+                stem, ext = os.path.splitext(n)
+                if WIN and ext.lower() in (".exe", ".cmd", ".bat", ".com"):
+                    found.setdefault(stem.lower(), full)
+        _index.update(at=time.time(), map=found)
+    return _index["map"]
+
+
+def which(cmd):
+    path = index().get(cmd) or (index().get(cmd.lower()) if WIN else None)
+    return path if path and os.path.isfile(path) and os.access(path, os.X_OK) else None

gitroster/procs.py

@@ -0,0 +1,179 @@
+"""Listening ports, their processes, and Docker containers (Linux, macOS, Windows)."""
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+WIN = sys.platform == "win32"
+MAC = sys.platform == "darwin"
+EXPOSED = ("0.0.0.0", "*", "::")
+
+
+def _run(cmd, timeout=6):
+    try:
+        return subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace",
+                              timeout=timeout).stdout
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return ""
+
+
+def _entry(port, host, pid, name, cmd, cwd, since):
+    host = host.strip("[]")
+    return {"port": int(port), "host": host, "pid": int(pid), "proc": name, "cmd": cmd[:240], "cwd": cwd,
+            "since": since, "repo": None, "exposed": host in EXPOSED}
+
+
+def _dedupe(rows):
+    seen, out = set(), []
+    for r in sorted(rows, key=lambda r: (r["port"], r["pid"])):
+        if (r["port"], r["pid"]) not in seen:
+            seen.add((r["port"], r["pid"]))
+            out.append(r)
+    return out
+
+
+# ---- Linux -----------------------------------------------------------------
+
+def parse_ss(text):
+    """-> [(host, port, pid, name)] from `ss -ltnpH`."""
+    res = []
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) < 5:
+            continue
+        host, _, port = parts[3].rpartition(":")
+        m = re.search(r'\("([^"]*)",pid=(\d+)', line)
+        if m and port.isdigit():
+            res.append((host, port, m.group(2), m.group(1)))
+    return res
+
+
+def _linux():
+    res = []
+    for host, port, pid, name in parse_ss(_run(["ss", "-ltnpH"])):
+        try:
+            cwd = os.readlink(f"/proc/{pid}/cwd")
+            cmd = Path(f"/proc/{pid}/cmdline").read_bytes().replace(b"\0", b" ").decode(errors="replace").strip()
+            since = os.stat(f"/proc/{pid}").st_mtime
+        except OSError:
+            cwd, cmd, since = "", "", 0
+        res.append(_entry(port, host, pid, name, cmd, cwd, since))
+    return res
+
+
+# ---- macOS -----------------------------------------------------------------
+
+def parse_lsof(text):
+    """-> [(host, port, pid, name)] from `lsof -nP -iTCP -sTCP:LISTEN`."""
+    res = []
+    for line in text.splitlines()[1:]:
+        parts = line.split()
+        m = re.search(r"(\S+):(\d+) \(LISTEN\)", line)
+        if len(parts) > 8 and m and parts[1].isdigit():
+            res.append((m.group(1), m.group(2), parts[1], parts[0].replace("\\x20", " ")))
+    return res
+
+
+def _mac():
+    res = []
+    for host, port, pid, name in parse_lsof(_run(["lsof", "-nP", "-iTCP", "-sTCP:LISTEN"])):
+        cwd = next((l[1:] for l in _run(["lsof", "-a", "-p", pid, "-d", "cwd", "-Fn"]).splitlines() if l.startswith("n")), "")
+        cmd = _run(["ps", "-o", "command=", "-p", pid]).strip()
+        started = _run(["ps", "-o", "lstart=", "-p", pid]).strip()
+        try:
+            since = time.mktime(time.strptime(started, "%a %b %d %H:%M:%S %Y"))
+        except ValueError:
+            since = 0
+        res.append(_entry(port, host, pid, name, cmd, cwd, since))
+    return res
+
+
+# ---- Windows ---------------------------------------------------------------
+
+def parse_netstat(text):
+    """-> [(host, port, pid)] from `netstat -ano -p TCP` (LISTENING rows)."""
+    res = []
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) >= 5 and parts[0] == "TCP" and parts[3].upper() == "LISTENING" and parts[4].isdigit():
+            host, _, port = parts[1].rpartition(":")
+            if port.isdigit():
+                res.append((host, port, parts[4]))
+    return res
+
+
+PS_PROCS = ("Get-CimInstance Win32_Process | ForEach-Object { [pscustomobject]@{p=$_.ProcessId; n=$_.Name; "
+            "c=$_.CommandLine; t=[DateTimeOffset]$_.CreationDate | ForEach-Object { $_.ToUnixTimeSeconds() }} } "
+            "| ConvertTo-Json -Compress")
+
+
+def parse_ps_procs(text):
+    try:
+        data = json.loads(text or "[]")
+    except ValueError:
+        return {}
+    data = [data] if isinstance(data, dict) else data
+    return {int(d["p"]): d for d in data if isinstance(d, dict) and d.get("p") is not None}
+
+
+def _windows():
+    rows = parse_netstat(_run(["netstat", "-ano", "-p", "TCP"]))
+    info = parse_ps_procs(_run(["powershell", "-NoProfile", "-NonInteractive", "-Command", PS_PROCS], 15)) if rows else {}
+    res = []
+    for host, port, pid in rows:
+        d = info.get(int(pid), {})
+        name = (d.get("n") or "").removesuffix(".exe")
+        res.append(_entry(port, host, pid, name, d.get("c") or "", "", d.get("t") or 0))
+    return res
+
+
+def listening():
+    """Every listening TCP port we can attribute to a process."""
+    return _dedupe(_windows() if WIN else _mac() if MAC else _linux())
+
+
+def docker_containers():
+    out = _run(["docker", "ps", "--format", "{{json .}}"], 5)
+    res = []
+    for line in out.splitlines():
+        try:
+            c = json.loads(line)
+        except ValueError:
+            continue
+        wd = re.search(r"com\.docker\.compose\.project\.working_dir=([^,]+)", c.get("Labels", ""))
+        res.append({"name": c.get("Names", ""), "image": c.get("Image", ""), "ports": c.get("Ports", ""),
+                    "status": c.get("Status", ""), "workdir": wd.group(1) if wd else "", "repo": None})
+    return res
+
+
+def _owner(path, items):
+    best = None
+    for c in items:
+        cp = c["path"]
+        if path == cp or path.startswith(cp + os.sep):
+            if best is None or len(cp) > len(best["path"]):
+                best = c
+    return best
+
+
+def link(ports, containers, repos, envs):
+    """Attach each port/container to a repo: by cwd, then by paths in the command line."""
+    for pt in ports:
+        o = _owner(pt["cwd"], repos) if pt["cwd"] else None
+        if not o:
+            for e in sorted(envs, key=lambda e: -len(e["path"])):
+                if e["path"] in pt["cmd"]:
+                    o = _owner(e["path"], repos)
+                    break
+        if not o:
+            for r in sorted(repos, key=lambda r: -len(r["path"])):
+                if r["path"] in pt["cmd"]:
+                    o = r
+                    break
+        pt["repo"] = o["path"] if o else None
+    for c in containers:
+        o = _owner(c["workdir"], repos) if c["workdir"] else None
+        c["repo"] = o["path"] if o else None

gitroster/repoinfo.py

@@ -0,0 +1,228 @@
+"""Read-only views of a repo: overview, file tree, file contents, commits, search. Nothing here writes."""
+import os
+import re
+import subprocess
+import tempfile
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+from .scanner import run
+
+REF_RE = re.compile(r"^[\w./@{}^~+-]{1,200}$")
+HASH_RE = re.compile(r"^[0-9a-f]{4,40}$")
+MAX_FILE = 300_000
+MAX_DIFF = 200_000
+
+LANGS = {
+    ".py": "Python", ".js": "JavaScript", ".jsx": "JavaScript", ".mjs": "JavaScript", ".ts": "TypeScript", ".tsx": "TypeScript",
+    ".html": "HTML", ".css": "CSS", ".scss": "CSS", ".astro": "Astro", ".vue": "Vue", ".svelte": "Svelte",
+    ".go": "Go", ".rs": "Rust", ".java": "Java", ".kt": "Kotlin", ".swift": "Swift", ".dart": "Dart", ".c": "C", ".h": "C",
+    ".cpp": "C++", ".cs": "C#", ".php": "PHP", ".rb": "Ruby", ".sh": "Shell", ".sql": "SQL", ".md": "Markdown",
+    ".json": "JSON", ".yml": "YAML", ".yaml": "YAML", ".toml": "TOML", ".ipynb": "Notebook", ".lua": "Lua",
+}
+
+
+def _git(path, *args, timeout=15):
+    return run(["git", "-C", str(path), *args], timeout)
+
+
+def check_ref(ref):
+    if not REF_RE.match(ref or "") or ref.startswith("-") or ".." in ref:
+        raise ValueError("bad ref")
+    return ref
+
+
+def check_rel(rel):
+    rel = (rel or "").strip("/")
+    if rel.startswith("-") or ".." in rel.split("/") or "\\" in rel or "\0" in rel:
+        raise ValueError("bad path")
+    return rel
+
+
+WEB_HOSTS = ("github.com", "gitlab.com", "bitbucket.org")
+
+
+def web_url(path):
+    """https page of the repo for well-known hosts, from origin (or the first remote)."""
+    from .scanner import norm_remote
+    remotes = _git(path, "remote", "-v").split()
+    urls = [remotes[i + 1] for i in range(0, len(remotes) - 1) if remotes[i + 1].count("/") or ":" in remotes[i + 1]]
+    origin = _git(path, "remote", "get-url", "origin").strip() or (urls[0] if urls else "")
+    n = norm_remote(origin)
+    if n.split("/")[0] not in WEB_HOSTS or n.count("/") < 2:
+        return None
+    return _keep_case(origin, n)
+
+
+def _keep_case(origin, normalized):
+    """https URL with the owner/repo spelling from the remote (normalized form is lowercase)."""
+    tail = "/".join(normalized.split("/")[1:])
+    i = origin.lower().find(tail)
+    return "https://" + normalized.split("/")[0] + "/" + (origin[i:i + len(tail)] if i >= 0 else tail)
+
+
+def contributor_url(name, email, web):
+    """GitHub profile for a contributor when it can be told from a noreply address or the repo owner's name."""
+    if not web or not web.startswith("https://github.com/"):
+        return None
+    m = re.match(r"^(?:\d+\+)?([^@]+)@users\.noreply\.github\.com$", email or "")
+    user = m.group(1) if m else ""
+    if not user and name.lower() == web.split("/")[3].lower():
+        user = web.split("/")[3]
+    if not user:
+        return None
+    return "https://github.com/apps/" + user[:-5] if user.endswith("[bot]") else "https://github.com/" + user
+
+
+def overview(path):
+    p = Path(path)
+    files = [f for f in _git(p, "ls-files", "-z").split("\0") if f]
+    langs = {}
+    for f in files:
+        ext = os.path.splitext(f)[1].lower()
+        name = LANGS.get(ext)
+        if not name:
+            continue
+        try:
+            size = (p / f).stat().st_size
+        except OSError:
+            continue
+        item = langs.setdefault(name, {"name": name, "files": 0, "bytes": 0})
+        item["files"] += 1
+        item["bytes"] += size
+    languages = sorted(langs.values(), key=lambda x: -x["bytes"])[:8]
+    web = web_url(p)
+    contributors = []
+    for line in _git(p, "shortlog", "-sne", "HEAD").splitlines()[:10]:
+        n, _, who = line.strip().partition("\t")
+        m = re.match(r"^(.*?)\s*<([^>]*)>$", who)
+        name, email = (m.group(1), m.group(2)) if m else (who, "")
+        if n.isdigit():
+            contributors.append({"name": name, "commits": int(n), "url": contributor_url(name, email, web)})
+    tags = []
+    for line in _git(p, "tag", "--sort=-creatordate", "--format=%(refname:short)\t%(creatordate:unix)").splitlines()[:12]:
+        name, _, ts = line.partition("\t")
+        tags.append({"name": name, "time": int(ts) if ts.isdigit() else None})
+    total = _git(p, "rev-list", "--count", "HEAD").strip()
+    first = _git(p, "log", "--reverse", "--format=%ct", "-n1", "--max-parents=0", "HEAD").strip()
+    changed = {}
+    for f in _git(p, "log", "-n", "60", "--name-only", "--format=").splitlines():
+        if f:
+            changed[f] = changed.get(f, 0) + 1
+    recent = [{"file": f, "changes": n} for f, n in sorted(changed.items(), key=lambda kv: -kv[1])[:10]]
+    readme = ""
+    for name in ("README.md", "readme.md", "README.rst", "README.txt", "README"):
+        try:
+            readme = (p / name).read_text(encoding="utf-8", errors="replace")[:20000]
+            break
+        except OSError:
+            continue
+    return {"web_url": web, "languages": languages, "contributors": contributors, "tags": tags, "files_total": len(files),
+            "commits_total": int(total) if total.isdigit() else 0, "first_commit": int(first) if first.isdigit() else None,
+            "hot_files": recent, "readme": readme}
+
+
+def tree(path, ref, rel):
+    ref, rel = check_ref(ref or "HEAD"), check_rel(rel)
+    spec = f"{ref}:{rel}" if rel else ref
+    out = _git(path, "ls-tree", "-l", spec)
+    entries = []
+    for line in out.splitlines():
+        meta, _, name = line.partition("\t")
+        parts = meta.split()
+        if len(parts) >= 4:
+            entries.append({"name": name, "type": parts[1], "size": int(parts[3]) if parts[3].isdigit() else None})
+    entries.sort(key=lambda e: (e["type"] != "tree", e["name"].lower()))
+    return entries
+
+
+def read_file(path, ref, rel):
+    ref, rel = check_ref(ref or "HEAD"), check_rel(rel)
+    if not rel:
+        raise ValueError("no file")
+    try:
+        proc = subprocess.run(["git", "-C", str(path), "show", f"{ref}:{rel}"], capture_output=True, timeout=15)
+    except (subprocess.TimeoutExpired, OSError):
+        raise ValueError("could not read file")
+    if proc.returncode != 0:
+        raise ValueError("file not found at that ref")
+    data = proc.stdout
+    if b"\0" in data[:8000]:
+        return {"binary": True, "size": len(data), "text": ""}
+    return {"binary": False, "size": len(data), "truncated": len(data) > MAX_FILE,
+            "text": data[:MAX_FILE].decode("utf-8", errors="replace")}
+
+
+def commit(path, h):
+    if not HASH_RE.match(h or ""):
+        raise ValueError("bad hash")
+    fmt = "%H%x1f%P%x1f%an%x1f%ct%x1f%B"
+    out = _git(path, "show", "--no-patch", f"--format={fmt}", h)
+    head = (out.split("\x1f") + [""] * 5)[:5]
+    files = []
+    for line in _git(path, "show", "--format=", "--numstat", "-M", h).splitlines():
+        a, _, rest = line.partition("\t")
+        d, _, name = rest.partition("\t")
+        if name:
+            files.append({"file": name, "added": int(a) if a.isdigit() else None, "deleted": int(d) if d.isdigit() else None})
+    diff = _git(path, "show", "--format=", "--patch", "--no-color", "-M", h, timeout=20)
+    return {"hash": head[0].strip(), "parents": head[1].split(), "author": head[2], "time": int(head[3]) if head[3].isdigit() else None,
+            "message": head[4].strip(), "files": files[:300], "diff": diff[:MAX_DIFF], "diff_truncated": len(diff) > MAX_DIFF}
+
+
+def search_repo(repo, q, scope, regex=False, per=40):
+    path = repo["path"]
+    res = {"path": path, "name": repo["name"], "code": [], "files": [], "commits": [], "capped": False}
+    if "code" in scope:
+        cmd = ["git", "-C", path, "grep", "-n", "-I", "-i", "--no-color", "-E" if regex else "-F", "-e", q]
+        proc = None
+        try:
+            proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace")
+            for line in proc.stdout:
+                f, _, rest = line.partition(":")
+                n, _, text = rest.partition(":")
+                if n.isdigit():
+                    res["code"].append({"file": f, "line": int(n), "text": text.strip()[:240]})
+                if len(res["code"]) >= per:
+                    res["capped"] = True
+                    proc.kill()
+                    break
+            proc.wait(timeout=5)
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+        finally:
+            if proc is not None and proc.stdout:
+                proc.stdout.close()
+    if "files" in scope:
+        low = q.lower()
+        res["files"] = [f for f in _git(path, "ls-files").splitlines() if low in f.lower()][:15]
+    if "commits" in scope:
+        for line in _git(path, "log", "--branches", "-i", "-F", f"--grep={q}", "-n", "8", "--format=%H%x1f%ct%x1f%s").splitlines():
+            h, _, rest = line.partition("\x1f")
+            ts, _, subject = rest.partition("\x1f")
+            res["commits"].append({"hash": h, "time": int(ts) if ts.isdigit() else None, "subject": subject[:200]})
+    return res
+
+
+def check_regex(q):
+    """Raise ValueError when `q` is not a valid extended regular expression for `git grep -E`."""
+    with tempfile.TemporaryDirectory() as d:
+        (Path(d) / "f").write_text("x")
+        try:
+            r = subprocess.run(["git", "grep", "--no-index", "-E", "-q", "-e", q], cwd=d, capture_output=True, timeout=5)
+        except (OSError, subprocess.TimeoutExpired):
+            return
+        if r.returncode > 1:
+            raise ValueError("invalid regular expression")
+
+
+def search(repos, q, scope=("code", "files", "commits"), regex=False):
+    q = (q or "").strip()
+    if len(q) < 2:
+        return []
+    if regex and "code" in scope:
+        check_regex(q)
+    with ThreadPoolExecutor(8) as ex:
+        results = list(ex.map(lambda r: search_repo(r, q, scope, regex), repos))
+    return [r for r in results if r["code"] or r["files"] or r["commits"]]