simvx.core.git_status

Git status classification service for editor/IDE file browsers.

Provides per-file git status used to draw Sublime/VSCode-style coloured dots beside file entries. A background thread polls git status --porcelain=v2 and git ls-files --others --exclude-standard at a fixed interval; lookups are O(1) against an in-memory map.

This module is part of step I1 of the file-status feature. The dot drawer (I2) and dirty-buffer wiring (I3) live elsewhere; an optional callback hook is already provided here so that I3 can plug in without touching this file.

Module Contents

Classes

Status	Git status classification used to pick a dot colour.
GitStatusProvider	Background-polling git status classifier.

Functions

parse_porcelain_v2

Parse git status --porcelain=v2 --branch plus untracked listing.

Data

log
__all__

API

simvx.core.git_status.log

‘getLogger(…)’

simvx.core.git_status.__all__

[‘Status’, ‘GitStatusProvider’, ‘parse_porcelain_v2’]

class simvx.core.git_status.Status

Bases: enum.StrEnum

Git status classification used to pick a dot colour.

Order matters when multiple states could apply: MODIFIED_UNSAVED always wins (the user is actively editing); CONFLICTED outranks committed states; UNTRACKED, SAVED_UNCOMMITTED and COMMITTED_UNPUSHED are mutually exclusive in normal git output.

Initialization

Initialize self. See help(type(self)) for accurate signature.

CLEAN

‘clean’

MODIFIED_UNSAVED

‘modified_unsaved’

SAVED_UNCOMMITTED

‘saved_uncommitted’

COMMITTED_UNPUSHED

‘committed_unpushed’

CONFLICTED

‘conflicted’

UNTRACKED

‘untracked’

__new__(*values)

__add__()

__contains__()

__delattr__()

__dir__()

__eq__()

__format__()

__ge__()

__getattribute__()

__getitem__()

__getnewargs__()

__getstate__()

__gt__()

__hash__()

__iter__()

__le__()

__len__()

__lt__()

__mod__()

__mul__()

__ne__()

__reduce__()

__reduce_ex__()

__repr__()

__rmod__()

__rmul__()

__setattr__()

__sizeof__()

__str__()

__subclasshook__()

capitalize()

casefold()

center()

count()

encode()

endswith()

expandtabs()

find()

format()

format_map()

index()

isalnum()

isalpha()

isascii()

isdecimal()

isdigit()

isidentifier()

islower()

isnumeric()

isprintable()

isspace()

istitle()

isupper()

join()

ljust()

lower()

lstrip()

partition()

removeprefix()

removesuffix()

replace()

rfind()

rindex()

rjust()

rpartition()

rsplit()

rstrip()

split()

splitlines()

startswith()

strip()

swapcase()

title()

translate()

upper()

zfill()

__deepcopy__(memo)

__copy__()

name()

value()

simvx.core.git_status.parse_porcelain_v2(porcelain_output: str, untracked_output: str = '', repo_root: pathlib.Path | None = None) → tuple[dict[pathlib.Path, simvx.core.git_status.Status], bool]

Parse git status --porcelain=v2 --branch plus untracked listing.

Returns (map, branch_ahead) where map is a {absolute path: Status} dict and branch_ahead is True when the current branch is ahead of its upstream (# branch.ab +N -M with N > 0). The caller decides how to apply the repo-level ahead state to otherwise-clean files.

repo_root, if given, is used to absolutise the relative paths git emits. When None, paths are kept as-is (useful for unit tests).

class simvx.core.git_status.GitStatusProvider(repo_root: pathlib.Path, dirty_paths_callback: collections.abc.Callable[[], set[pathlib.Path]] | None = None, poll_interval: float = 2.0)

Background-polling git status classifier.

Spawns a daemon thread that runs git status --porcelain=v2 --branch and git ls-files --others --exclude-standard every poll_interval seconds and rebuilds an internal {path: Status} map. status_for performs an O(1) lookup against that map.

Thread-safety: the map is replaced atomically via a single attribute assignment under self._lock. Readers grab a local reference to the current map under the lock and then index into it without holding the lock — dict reads on a stable reference are safe in CPython.

A missing .git directory is not an error; everything reports CLEAN. Partial/corrupt repos (worktree pointer with stale gitdir:, .git directory with no HEAD, missing git binary) are also tolerated: the provider logs a warning, marks itself _disabled, and reports CLEAN for every lookup. Callers can check is_active to decide whether to render git dots at all.

Initialization

status_for(path: pathlib.Path | str) → simvx.core.git_status.Status

Return the status for path (absolute or relative to repo root).

property is_active: bool

Whether the provider is functional (git binary present, repo readable).

refresh() → None

Synchronously rebuild the status map. Called from the polling thread and at construction time; safe to call from tests.

Tolerates partial/corrupt repos and a missing git binary: on the first failure the provider is marked _disabled and subsequent status_for calls return CLEAN.

stop(timeout: float | None = 1.0) → None

Signal the polling thread to exit and wait briefly for it.