Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""A repository's local state, read fast enough to poll.
The IDE's Git tab asks for the same repository every few seconds, from every
open pane. Reading it costs a handful of ``git`` processes, and the expensive
part — every branch with how far it is ahead of / behind its upstream and the
default branch — only changes when a ref moves. So this module splits the read
in two:
* **Branches** are read once and reused until the repository's refs change.
The check is a walk over the ref files' timestamps (no process), so an
unchanged repository costs a few milliseconds instead of half a second.
* **The checkout** (uncommitted changes, ahead/behind of the current branch) is
one ``git status`` per read, shared by callers that ask within a second.
A cold read runs its git commands side by side. Nothing here raises: a folder
that is not a repository, or a machine without git, answers ``None``.
"""
from __future__ import annotations
import os
import shutil
import subprocess
import threading
import time
from collections.abc import Callable
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
from loguru import logger
from dodaios.core.process_utils import NO_WINDOW_CREATIONFLAGS
_GIT_TIMEOUT_S = 8.0
#: A status answer this young is shared instead of read again (N panes, one repository).
STATUS_SHARE_S = 1.0
#: Branches are re-read at least this often even when no ref file changed.
BRANCHES_MAX_AGE_S = 30.0
#: Where a repository's paths are remembered before git is asked again.
_PATHS_TTL_S = 60.0
#: Default-branch names tried when ``origin/HEAD`` does not say.
_DEFAULT_CANDIDATES = ("main", "master", "trunk", "develop")
class Job:
"""One call on a daemon thread, so a cold read runs its git commands side by side.
Daemon threads on purpose: a hung git must never keep the app from exiting.
"""
def __init__(self, target: Callable[..., Any], *args: Any) -> None:
self._value: Any = None
self._error: BaseException | None = None
self._thread = threading.Thread(
target=self._work, args=(target, args), name="git-local", daemon=True
)
self._thread.start()
def _work(self, target: Callable[..., Any], args: tuple[Any, ...]) -> None:
try:
self._value = target(*args)
except BaseException as exc: # re-raised in the caller by result()
self._error = exc
def result(self) -> Any:
self._thread.join()
if self._error is not None:
raise self._error
return self._value
# ------------------------------------------------------------------ plumbing
def run_git(
args: list[str], cwd: Path, *, timeout: float = _GIT_TIMEOUT_S, stdin: str | None = None
):
"""One git call that never prompts; None when git is missing or hangs."""
env = dict(os.environ)
env["GIT_TERMINAL_PROMPT"] = "0"
# Reading must never take the index lock away from the person's own git.
env["GIT_OPTIONAL_LOCKS"] = "0"
try:
return subprocess.run(
["git", "-c", "core.quotePath=false", *args],
cwd=str(cwd),
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=timeout,
check=False,
env=env,
input=stdin,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
except FileNotFoundError: # git not installed: callers report it as unavailable
return None
except subprocess.TimeoutExpired:
logger.info("Git: `git {}` did not answer in time in {}", args[0] if args else "", cwd)
return None
def git_out(args: list[str], cwd: Path) -> str | None:
result = run_git(args, cwd)
if result is None or result.returncode != 0:
return None
return result.stdout
# ------------------------------------------------------------------ model
@dataclass(slots=True)
class LocalBranch:
name: str
head: str = ""
upstream: str = ""
ahead: int = 0
behind: int = 0
#: The upstream is configured but no longer exists on the remote.
upstream_gone: bool = False
committed_at: int = 0
#: The folder this branch is checked out in ("" when it is nowhere).
worktree: str = ""
#: Commits it has that the default branch lacks / lacks that it has; None when unknown.
base_ahead: int | None = None
base_behind: int | None = None
#: Targets whose history already contains all of its commits.
merged_into: list[str] = field(default_factory=list)
@dataclass(slots=True)
class Checkout:
"""The folder's own state: what is uncommitted and how it stands to its remote."""
branch: str = ""
detached: bool = False
#: No commit yet (a fresh ``git init``).
unborn: bool = False
head: str = ""
upstream: str = ""
ahead: int = 0
behind: int = 0
#: Files with any uncommitted change; one both staged and edited counts once.
files: int = 0
staged: int = 0
unstaged: int = 0
untracked: int = 0
conflicted: int = 0
#: ``merge`` | ``rebase`` | ``cherry-pick`` | ``revert`` | ``bisect`` while one is unfinished.
operation: str = ""
stashes: int = 0
#: Epoch seconds of the last ``git fetch`` (0 when never).
last_fetch: int = 0
has_remote: bool = False
@dataclass(slots=True)
class LocalState:
root: Path
checkout: Checkout
default_branch: str = ""
#: What ``base_ahead`` / ``base_behind`` compare with (``origin/main``), "" when unknown.
base_ref: str = ""
branches: list[LocalBranch] = field(default_factory=list)
#: Remote-tracking branch (``origin/main``) → the commit it points at.
remote_heads: dict[str, str] = field(default_factory=dict)
@dataclass(slots=True)
class RepoPaths:
root: Path
#: This checkout's git directory (``.git``, or ``.git/worktrees/<name>``).
git_dir: Path
#: The directory every worktree of the repository shares.
common_dir: Path
# ------------------------------------------------------------------ locating
_paths_guard = threading.Lock()
_paths: dict[str, tuple[float, RepoPaths]] = {}
def locate(folder: str | Path) -> RepoPaths | None:
"""The repository ``folder`` is in; None when it is not one (or git is missing)."""
path = Path(folder).expanduser()
if not path.is_dir() or shutil.which("git") is None:
return None
key = os.path.normcase(str(path))
now = time.monotonic()
with _paths_guard:
hit = _paths.get(key)
if hit and now - hit[0] < _PATHS_TTL_S and hit[1].git_dir.is_dir():
return hit[1]
text = git_out(["rev-parse", "--show-toplevel", "--git-dir", "--git-common-dir"], path)
lines = [line.strip() for line in (text or "").splitlines() if line.strip()]
if len(lines) < 3:
with _paths_guard:
_paths.pop(key, None)
return None
def absolute(value: str) -> Path:
candidate = Path(value)
return candidate if candidate.is_absolute() else (path / candidate)
found = RepoPaths(
root=Path(lines[0]), git_dir=absolute(lines[1]), common_dir=absolute(lines[2])
)
with _paths_guard:
_paths[key] = (now, found)
return found
# ------------------------------------------------------------------ fingerprint
def _stamp(path: Path) -> tuple[int, int]:
try:
info = path.stat()
except OSError: # the file does not exist (no packed refs yet, no fetch yet)
return (0, 0)
return (info.st_mtime_ns, info.st_size)
def _walk(folder: Path, into: list[tuple[str, int, int]]) -> None:
try:
entries = sorted(os.scandir(folder), key=lambda entry: entry.name)
except OSError: # no such directory (a repository without remotes): nothing to add
return
for entry in entries:
try:
info = entry.stat()
is_dir = entry.is_dir()
except OSError: # deleted between the listing and the stat: the next read sees it gone
continue
into.append((entry.path, info.st_mtime_ns, info.st_size))
if is_dir:
_walk(Path(entry.path), into)
def refs_fingerprint(paths: RepoPaths) -> tuple:
"""Changes whenever a branch, a remote-tracking ref, HEAD or a worktree does.
Git moves a ref by renaming a lock file over it, so both the file's and its
directory's timestamp change; packed and reftable storage change their own
files. Reading timestamps costs no process.
"""
marks: list[tuple[str, int, int]] = []
for name in ("HEAD", "packed-refs", "config"):
marks.append((name, *_stamp(paths.common_dir / name)))
if paths.git_dir != paths.common_dir:
marks.append(("worktree-HEAD", *_stamp(paths.git_dir / "HEAD")))
_walk(paths.common_dir / "refs" / "heads", marks)
_walk(paths.common_dir / "refs" / "remotes", marks)
_walk(paths.common_dir / "reftable", marks)
try:
trees = sorted(os.scandir(paths.common_dir / "worktrees"), key=lambda entry: entry.name)
except OSError: # no linked worktrees
trees = []
for tree in trees:
marks.append((tree.name, *_stamp(Path(tree.path) / "HEAD")))
# Rewritten when the worktree's folder is moved.
marks.append((f"{tree.name}/gitdir", *_stamp(Path(tree.path) / "gitdir")))
# The reflog grows with every move of HEAD, even two inside one timestamp tick.
marks.append(("logs/HEAD", *_stamp(paths.common_dir / "logs" / "HEAD")))
return tuple(marks)
# ------------------------------------------------------------------ branches
# None until the first read; False on a git older than 2.41 (no ``ahead-behind`` atom).
_ahead_behind_ok: bool | None = None
def _parse_track(text: str) -> tuple[int, int, bool]:
ahead = behind = 0
gone = False
for part in text.split(","):
word, _, count = part.strip().partition(" ")
if word == "ahead" and count.isdigit():
ahead = int(count)
elif word == "behind" and count.isdigit():
behind = int(count)
elif word == "gone":
gone = True
return ahead, behind, gone
def _read_heads(root: Path) -> list[LocalBranch] | None:
"""Every local branch; None when git did not answer (never cached as "no branches")."""
text = git_out(
[
"for-each-ref",
"--sort=-committerdate",
"--format=%(refname:short)%09%(objectname)%09%(upstream:short)%09"
"%(upstream:track,nobracket)%09%(committerdate:unix)%09%(worktreepath)",
"refs/heads",
],
root,
)
if text is None:
return None
rows: list[LocalBranch] = []
for line in text.splitlines():
name, oid, upstream, track, stamp, tree = ([*line.split("\t"), "", "", "", "", ""])[:6]
if not name:
continue
ahead, behind, gone = _parse_track(track)
rows.append(
LocalBranch(
name=name,
head=oid,
upstream=upstream,
ahead=ahead,
behind=behind,
upstream_gone=gone,
committed_at=int(stamp) if stamp.isdigit() else 0,
worktree=str(Path(tree)) if tree else "",
)
)
return rows
def _read_remote_heads(root: Path) -> dict[str, str]:
text = git_out(
["for-each-ref", "--format=%(refname:short)%09%(objectname)", "refs/remotes"], root
)
heads: dict[str, str] = {}
for line in (text or "").splitlines():
name, _, oid = line.partition("\t")
if name and oid and not name.endswith("/HEAD"):
heads[name] = oid.strip()
return heads
def _read_origin_default(root: Path) -> str:
text = git_out(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], root)
return text.strip().split("/", 1)[-1] if text and text.strip() else ""
def _pair(text: str) -> tuple[int, int] | None:
ahead, _, behind = text.strip().partition(" ")
return (int(ahead), int(behind)) if ahead.isdigit() and behind.isdigit() else None
def _read_ahead_behind(
root: Path, refs: list[str]
) -> dict[str, list[tuple[int, int] | None]] | None:
"""Branch → (ahead, behind) against each of ``refs``, in one history walk.
None on a git without the ``ahead-behind`` atom; the caller then falls back
to one ``--merged`` listing and reports no counts.
"""
global _ahead_behind_ok
if not refs or _ahead_behind_ok is False:
return None
atoms = "%09".join(f"%(ahead-behind:{ref})" for ref in refs)
result = run_git(["for-each-ref", f"--format=%(refname:short)%09{atoms}", "refs/heads"], root)
if result is None:
return None
if result.returncode != 0:
if "unknown field name" in (result.stderr or ""):
_ahead_behind_ok = False
return None
_ahead_behind_ok = True
counts: dict[str, list[tuple[int, int] | None]] = {}
for line in result.stdout.splitlines():
name, *cells = line.split("\t")
if name:
counts[name] = [_pair(cell) for cell in cells]
return counts
def merged_into(root: Path, target_ref: str) -> dict[str, str]:
"""Branch name → tip, for every branch whose commits ``target_ref`` already has."""
text = git_out(
[
"for-each-ref",
f"--merged={target_ref}",
"--format=%(refname:short)%09%(objectname)",
"refs/heads",
],
root,
)
found: dict[str, str] = {}
for line in (text or "").splitlines():
name, _, oid = line.partition("\t")
if name:
found[name] = oid.strip()
return found
@dataclass(slots=True)
class _Branches:
fingerprint: tuple
taken_at: float
default_branch: str
base_ref: str
rows: list[LocalBranch]
remote_heads: dict[str, str]
def _read_branches(paths: RepoPaths, current: str, fingerprint: tuple) -> _Branches | None:
root = paths.root
default = _read_origin_default(root)
heads_job = Job(_read_heads, root)
remotes_job = Job(_read_remote_heads, root)
# Counted while the branch list is still being read; the guess holds
# whenever the default branch exists both here and on the remote.
guess = [f"refs/heads/{default}", f"refs/remotes/origin/{default}"] if default else []
counts_job = Job(_read_ahead_behind, root, guess) if guess else None
rows, remote_heads = heads_job.result(), remotes_job.result()
if rows is None:
if counts_job is not None:
counts_job.result()
return None
names = {row.name: row for row in rows}
if not default:
default = next((name for name in _DEFAULT_CANDIDATES if name in names), current)
# The default branch as this computer has it, and as the remote does: a
# branch whose commits are in either is merged.
targets: list[str] = []
if default and default in names:
targets.append(f"refs/heads/{default}")
if default and f"origin/{default}" in remote_heads:
targets.append(f"refs/remotes/origin/{default}")
base_ref = ""
if targets:
base_ref = f"origin/{default}" if targets[-1].startswith("refs/remotes/") else default
tips = [
names[default].head if ref.startswith("refs/heads/") else remote_heads[f"origin/{default}"]
for ref in targets
]
counts = counts_job.result() if counts_job is not None else None
if targets != guess:
counts = _read_ahead_behind(root, targets)
if counts is not None:
for row in rows:
cells = counts.get(row.name) or []
pairs = [cell for cell in cells if cell is not None]
if pairs:
row.base_ahead, row.base_behind = pairs[-1]
if row.name == default:
continue
# Tip equal to the target's: created from it, no work of its own — not "merged".
if any(
cell is not None and cell[0] == 0 and row.head != tips[index]
for index, cell in enumerate(cells[: len(tips)])
):
row.merged_into = [default]
else:
for index, ref in enumerate(targets):
for name, oid in merged_into(root, ref).items():
row = names.get(name)
if (
row is not None
and name != default
and oid != tips[index]
and not row.merged_into
):
row.merged_into = [default]
return _Branches(
fingerprint=fingerprint,
taken_at=time.monotonic(),
default_branch=default,
base_ref=base_ref,
rows=rows,
remote_heads=remote_heads,
)
# ------------------------------------------------------------------ checkout
def _parse_status(text: str, checkout: Checkout) -> None:
"""Fill ``checkout`` from ``git status --porcelain=v2 --branch``."""
for line in text.splitlines():
if line.startswith("# branch.oid "):
oid = line[len("# branch.oid ") :].strip()
checkout.unborn = oid == "(initial)"
checkout.head = "" if checkout.unborn else oid[:12]
elif line.startswith("# branch.head "):
head = line[len("# branch.head ") :].strip()
checkout.detached = head == "(detached)"
checkout.branch = "" if checkout.detached else head
elif line.startswith("# branch.upstream "):
checkout.upstream = line[len("# branch.upstream ") :].strip()
elif line.startswith("# branch.ab "):
ahead, _, behind = line[len("# branch.ab ") :].strip().partition(" ")
if ahead[1:].isdigit() and behind[1:].isdigit():
checkout.ahead, checkout.behind = int(ahead[1:]), int(behind[1:])
elif line.startswith(("1 ", "2 ")):
xy = line[2:4]
checkout.files += 1
if xy[:1] != ".":
checkout.staged += 1
if xy[1:2] != ".":
checkout.unstaged += 1
elif line.startswith("u "):
checkout.files += 1
checkout.conflicted += 1
elif line.startswith("? "):
checkout.files += 1
checkout.untracked += 1
def _operation(git_dir: Path) -> str:
if (git_dir / "rebase-merge").is_dir() or (git_dir / "rebase-apply").is_dir():
return "rebase"
for marker, name in (
("MERGE_HEAD", "merge"),
("CHERRY_PICK_HEAD", "cherry-pick"),
("REVERT_HEAD", "revert"),
("BISECT_LOG", "bisect"),
):
if (git_dir / marker).exists():
return name
return ""
def _count_lines(path: Path) -> int:
try:
with path.open("rb") as handle:
return sum(1 for _ in handle)
except OSError: # no stash was ever made
return 0
def _has_remote(common_dir: Path) -> bool:
try:
return "[remote " in (common_dir / "config").read_text(encoding="utf-8", errors="replace")
except OSError: # unreadable config: offer nothing that needs a remote
return False
def _read_checkout(paths: RepoPaths) -> Checkout | None:
"""The checkout's state; None when git did not answer."""
checkout = Checkout()
text = git_out(["status", "--porcelain=v2", "--branch", "--untracked-files=normal"], paths.root)
if text is None:
return None
_parse_status(text, checkout)
checkout.operation = _operation(paths.git_dir)
checkout.stashes = _count_lines(paths.common_dir / "logs" / "refs" / "stash")
checkout.last_fetch = _stamp(paths.common_dir / "FETCH_HEAD")[0] // 1_000_000_000
checkout.has_remote = _has_remote(paths.common_dir)
return checkout
# ------------------------------------------------------------------ cache
@dataclass(slots=True)
class _Entry:
lock: threading.Lock = field(default_factory=threading.Lock)
branches: _Branches | None = None
checkout: Checkout | None = None
checkout_at: float = 0.0
_guard = threading.Lock()
_entries: dict[str, _Entry] = {}
def forget(folder: str | Path | None = None) -> None:
"""Drop what is remembered (about one folder's repository, or everything)."""
with _guard:
if folder is None:
_entries.clear()
else:
_entries.pop(os.path.normcase(str(Path(folder).expanduser())), None)
if folder is None:
with _paths_guard:
_paths.clear()
def read(folder: str | Path, *, fresh: bool = False) -> LocalState | None:
"""The repository ``folder`` is in; None when there is none to read.
``fresh`` re-reads everything now (after an action changed the repository).
The branch rows are copies: callers may annotate them.
"""
paths = locate(folder)
if paths is None:
return None
key = os.path.normcase(str(paths.root))
with _guard:
entry = _entries.setdefault(key, _Entry())
# One read per repository at a time; a second caller waits and reuses it.
with entry.lock:
now = time.monotonic()
checkout_job = None
if fresh or entry.checkout is None or now - entry.checkout_at >= STATUS_SHARE_S:
checkout_job = Job(_read_checkout, paths)
fingerprint = refs_fingerprint(paths)
branches = entry.branches
stale = (
fresh
or branches is None
or branches.fingerprint != fingerprint
or now - branches.taken_at >= BRANCHES_MAX_AGE_S
)
if checkout_job is not None:
read_now = checkout_job.result()
if read_now is not None:
entry.checkout = read_now
entry.checkout_at = time.monotonic()
else:
# Git did not answer: show what was last known, and ask again next time.
logger.debug("Git: status of {} could not be read", paths.root)
entry.checkout_at = 0.0
checkout = entry.checkout or Checkout()
if stale:
read_branches = _read_branches(paths, checkout.branch, fingerprint)
if read_branches is not None:
branches = entry.branches = read_branches
else:
logger.debug("Git: branches of {} could not be read", paths.root)
if branches is None:
# Nothing was ever read and git is not answering: an empty repository
# for this one call, remembered nowhere.
branches = _Branches(
fingerprint=(),
taken_at=0.0,
default_branch="",
base_ref="",
rows=[],
remote_heads={},
)
return LocalState(
root=paths.root,
checkout=checkout,
default_branch=branches.default_branch or checkout.branch,
base_ref=branches.base_ref,
branches=[
LocalBranch(
name=row.name,
head=row.head,
upstream=row.upstream,
ahead=row.ahead,
behind=row.behind,
upstream_gone=row.upstream_gone,
committed_at=row.committed_at,
worktree=row.worktree,
base_ahead=row.base_ahead,
base_behind=row.base_behind,
merged_into=list(row.merged_into),
)
for row in branches.rows
],
remote_heads=branches.remote_heads,
)
def missing_commits(root: Path, oids: list[str]) -> set[str]:
"""The commits of ``oids`` this computer does not have (so: not fetched yet)."""
wanted = [oid for oid in dict.fromkeys(oids) if oid]
if not wanted:
return set()
result = run_git(["cat-file", "--batch-check"], root, stdin="\n".join(wanted) + "\n")
if result is None or result.returncode != 0:
return set()
missing: set[str] = set()
for oid, line in zip(wanted, result.stdout.splitlines(), strict=False):
if line.rstrip().endswith(" missing"):
missing.add(oid)
return missing