Skip to content

feat: Git states simulator and watcher #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
barelyhuman merged 2 commits into from
May 28, 2026
Merged

feat: Git states simulator and watcher #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2ec8334
feat: watch metadata events
barelyhuman May 28, 2026
8220418
feat: simulator
barelyhuman May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ const oneFile = await getFileGitState('/path/to/repo', 'src/app.ts');
## Watcher API

Filesystem events are dirty hints only. The watcher debounces changed paths, runs scoped `git status --porcelain=v2 -z -- <paths>`, compares against the cache, and emits `change` only when the computed git state actually changes.
Git metadata (`index`, `HEAD`, `refs`) is watched separately, so commands like `git add`, `git commit`, `git reset`, and checkout also trigger semantic updates.

```ts
import { createGitStateWatcher } from 'git-tree-state';
Expand All @@ -37,7 +38,7 @@ const unsubscribe = watcher.on('change', (changes) => {
}
});

// After branch checkout / reset / index-only updates:
// Force a resync if watcher events may have been dropped:
await watcher.refresh();

await watcher.close();
Expand All @@ -50,9 +51,10 @@ unsubscribe();
|-----------|------|
| Startup | One full `git status --porcelain=v2 -z` |
| File edit | Debounced batch of scoped status calls for dirty paths only |
| Git metadata change (`git add`, commit, reset, checkout) | Debounced full status refresh |
| Listener | Fires only on semantic `GitState` transitions (including dirty → clean) |

Use `refresh()` when git state may change without a working-tree filesystem event (checkout, reset, stage/unstage).
Use `refresh()` to force a resync after missed watcher events or external operations you do not trust the watcher to catch.

## Types

Expand All @@ -65,6 +67,8 @@ type GitState = {
| 'renamed'
| 'copied'
| 'unknown';
staged: boolean;
unstaged: boolean;
path: string;
oldPath?: string;
};
Expand All @@ -76,12 +80,24 @@ type GitStateChange = {
};
```

## Simulation harness

For scenario-style tests and local inspection, use the test-support simulation harness in [`src/test-support/simulator.ts`](src/test-support/simulator.ts). It runs real git and filesystem operations against `createGitStateWatcher()` and renders a terminal tree with per-file git state badges.

```bash
npm test -- src/simulation.test.ts
npm run simulate
```

Set `GIT_TREE_STATE_SIM_PRINT=1` to print tree snapshots after each step (`npm run simulate` enables this automatically).

## Development

```bash
npm install
npm test
npm run build
npm run simulate
```

## CI and release
Expand Down
Loading