sem: When Git Stops Seeing Lines and Starts Seeing Code
A Rust tool that treats functions, classes, and dependencies as first-class versioning units, then uses that structure to power diff, blame, and impact analysis for humans and agents.
- `sem` changes version control from line comparison to entity comparison, so a function rename or move becomes a structural event instead of noisy churn.
- Its real differentiator is impact analysis, which turns a diff into a dependency question about what else is now suspect.
- The tool is built for human review and machine consumption at the same time, with JSON output and agent-oriented workflows as first-class interfaces.
- The trade-off is complexity: tree-sitter parsing, caching, and graph logic buy better signal, but they also demand more infrastructure than a plain diff viewer.
The hidden superpower: change becomes a dependency problem
Most diff tools answer a narrow question: what text changed? `sem` asks a better one. If a function moved, was it cosmetic, or did that change ripple through the rest of the codebase? That shift makes impact analysis the headline feature, not an afterthought.
Git’s weakness is structural blindness
Git is excellent at storing history, but it is blind to code meaning. A reformat, rename, or file move can look dramatic in a line diff even when the logic barely changed. That is fine for storage. It is not fine for review, blame, or agent context.
| Problem | Line-based Git | sem |
|---|---|---|
| Function renamed | Looks like deletion plus addition | Recognizes a rename |
| Function moved | Looks like churn across files | Recognizes a move |
| Formatting changed | Pollutes the diff | Ignored by structural hashing |
| Meaning of the change | Left to the reader | Mapped to entities and dependencies |
That difference matters because code review is not just about reading patches. It is about deciding what deserves attention. `sem` tries to compress that decision into the tool itself.
How `sem` models code as entities
Under the hood, `sem` is not styling up a regular diff. It parses source with tree-sitter, extracts SemanticEntity records, and assigns each one a stable identity. The important fields are not line numbers. They are entity_id, structural_hash, and precise byte offsets.
pub struct SemanticEntity {
pub entity_id: String,
pub structural_hash: u64,
pub start_byte: usize,
pub end_byte: usize,
// ...
}
The point of that model is simple: preserve identity across movement and formatting. If a method is renamed or a block is reformatted, `sem` still tries to answer whether the underlying structure is the same thing wearing different clothes.
The diff engine does more than match files
`compute_semantic_diff` is where the model turns into output. It compares before and after entities, then classifies the relationship: Added, Deleted, Modified, Moved, Renamed, or Reordered. That is a much richer vocabulary than Git’s usual add and remove accounting.
| Entity relation | What it means | Why it matters |
|---|---|---|
| Added | A new logical unit exists | Useful for scope and review |
| Deleted | A logical unit disappeared | Useful for regression hunting |
| Modified | Same entity, structure changed | Signals real logic drift |
| Moved | Same entity, different location | Cuts false churn |
| Renamed | Identity preserved, label changed | Keeps history readable |
| Reordered | Structure unchanged, order changed | Separates layout from logic |
This is also why the tool feels less like a pager and more like an analysis engine. The output is not just prettier. It is more categorical, which makes it easier to automate and easier to trust.
Why agents matter here
`sem` is explicitly built for machine consumers as much as humans. The JSON format is not a convenience flag. It is the interface that lets another tool, or an AI agent, ask for structured context without scraping terminal output.
If you want to layer an LLM on top for summarization, you're feeding it 10 entities instead of 500 lines of unified diff.
That design choice explains the rest of the project. `sem context` exists because agents need concise inputs. `sem impact` exists because agents need consequences, not just change. The whole stack assumes that structured output is not optional when software starts collaborating with software.
Entity-level blame and impact make the model useful
`sem blame` and `sem impact` are where the abstraction pays rent. Entity-level blame asks who last changed the logic of a function, not who last touched a noisy line. Impact asks what depends on that logic, directly and transitively.
| Question | Traditional answer | `sem` answer |
|---|---|---|
| Who touched it? | Line-level blame | Entity-level blame |
| What changed? | Unified diff | Structural diff |
| What is now risky? | Manual inspection | Dependency-driven impact |
| What should an agent read? | Raw patch text | Structured entities and JSON |
That is the real product thesis. `sem` is not just making diffs easier to read. It is making code change analysis causally useful.
Where `sem` fits among Difftastic, Delta, and Graphtage
`sem` lives in a crowded neighborhood, but it is not playing the same game. Difftastic is about syntax-aware readability. Delta is about presentation. Graphtage is about structured data. `sem` is trying to make programming-language entities and dependencies the unit of analysis.
| Tool | Primary focus | What it is best at |
|---|---|---|
| `sem` | Entity and dependency analysis | Impact, blame, agent context |
| Difftastic | Syntax-aware diff viewing | Readable terminal diffs |
| Delta | Diff presentation | Beautiful Git output |
| Graphtage | Structured data diffing | JSON, YAML, and XML comparison |
That distinction matters because the tool’s ambition is broader than review aesthetics. It wants to become part of the substrate for AI-assisted development.
The trade-off: power comes with graph and cache complexity
The cost of this model is real. Tree-sitter support, SQLite caching, Git bridge logic, and dependency graph construction are not free. They make the system smarter, but they also make it heavier than a simple text diff.
That is the honest trade. If you want a tool that can tell you whether a change is structural, where it moved, and what it now threatens, you need more than line comparison. You need parsing, identity, and a graph that can survive large repositories without collapsing under its own work.





