{"id":49559441,"url":"https://github.com/jhanvi857/gitresolve","last_synced_at":"2026-05-03T07:13:06.430Z","repository":{"id":347842135,"uuid":"1187450438","full_name":"jhanvi857/gitresolve","owner":"jhanvi857","description":"A locally executed, deterministic Git merge conflict solver built on Abstract Syntax Trees and structured serialization.","archived":false,"fork":false,"pushed_at":"2026-04-06T16:22:00.000Z","size":71277,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T18:20:10.546Z","etag":null,"topics":["git","github","golang","resolver"],"latest_commit_sha":null,"homepage":"https://gitresolve.vercel.app","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jhanvi857.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T18:33:30.000Z","updated_at":"2026-04-06T16:22:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jhanvi857/gitresolve","commit_stats":null,"previous_names":["jhanvi857/gitresolve"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jhanvi857/gitresolve","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2Fgitresolve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2Fgitresolve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2Fgitresolve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2Fgitresolve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhanvi857","download_url":"https://codeload.github.com/jhanvi857/gitresolve/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhanvi857%2Fgitresolve/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32561045,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","github","golang","resolver"],"created_at":"2026-05-03T07:13:02.636Z","updated_at":"2026-05-03T07:13:06.422Z","avatar_url":"https://github.com/jhanvi857.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gitresolve\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"documentation/public/logo.png\" width=\"240\" alt=\"gitresolve logo\"\u003e\n\u003c/p\u003e\n\nA locally executed, safety-first Git merge conflict resolver with syntax-aware classification, structured data merging, and full decision auditability.\n\nStandard Git merge operations perform line-based text integration. `gitresolve` classifies conflicts into deterministic categories, applies targeted resolution strategies per conflict type, and escalates to manual review when automated resolution would be unsafe. Every decision is logged, queryable, and CI-gateable.\n\n---\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Core Features](#core-features)\n- [Command Reference](#command-reference)\n- [Policy Profiles](#policy-profiles)\n- [Observability and Stats](#observability-and-stats)\n- [CI Integration](#ci-integration)\n- [Architecture](#architecture)\n- [Testing](#testing)\n- [Evidence and Limitations](#evidence-and-limitations)\n- [Readiness Gates](#readiness-gates)\n- [Comparative Positioning](#comparative-positioning)\n\n---\n\n## Installation\n\n### Via Go Toolchain\n\n```bash\ngo install github.com/jhanvi857/gitresolve@latest\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/jhanvi857/gitresolve.git\ncd gitresolve\ngo build -o gitresolve ./cmd/gitresolve\nmv gitresolve /usr/local/bin/\n```\n\n---\n\n## Quick Start\n\n```bash\n# View current conflicts with block-level severity\ngitresolve status\n\n# Resolve interactively\ngitresolve resolve\n\n# Predict conflicts before a destructive merge\ngitresolve scan --target main\n\n# Simulate decisions without writing any files\ngitresolve resolve --shadow\n\n# Run in CI with non-interactive mode\ngitresolve resolve --non-interactive --timeout 1m\n```\n\n---\n\n## Core Features\n\n### Safety-First Execution\n\nEvery write operation is protected by atomic file swaps, PID-verified multi-layer locking, and pre-write syntax validation. If Go output validation fails, the write is skipped and the conflict escalates to manual review. The tool prefers a correct escalation over an unsafe auto-resolution.\n\n### AST-Based Classification\n\n`gitresolve` integrates `go-tree-sitter` to compile conflicting blocks into syntax trees rather than operating on raw text. This enables accurate detection of function signature modifications, struct field conflicts, and logical refactors across Go, JavaScript, and TypeScript.\n\n### Structured Data Merging\n\nDeep recursive map merges for JSON, YAML, and TOML files using language-native parsers. Includes conservative array unioning to prevent silent data corruption. Auto-resolution is restricted for critical dependency files such as `package.json` and `go.mod`.\n\n### Decision Auditability\n\nEvery conflict decision is persisted to a local SQLite database with a stable, namespaced reason code (`parser.*`, `semantic.*`, `strategy.*`, `validation.*`). The decision log records conflict type, selected action, confidence level, and operation context. This makes every resolution auditable and retrospectively analyzable.\n\n### Shadow Mode\n\nRun `--shadow` to simulate the full resolution pipeline without writing any files. Before-and-after content hashes are recorded so you can measure blast radius before enforcing automation.\n\n### Policy Profiles\n\nResolution risk posture is configurable per command, per path, and per team via `.gitresolve/policy.json`. Profiles range from `strict` (maximum escalation, minimum risk) to `aggressive` (maximum automation for low-risk paths).\n\n---\n\n## Command Reference\n\n| Command | Description |\n| :--- | :--- |\n| `gitresolve resolve` | Resolve conflicts interactively or via automation. |\n| `gitresolve resolve --non-interactive` | Exit with status 1 on any manual resolution requirement. Suitable for CI. |\n| `gitresolve resolve --strategy \u003cours/theirs/both\u003e` | Apply a fixed strategy to all automatable conflicts. |\n| `gitresolve resolve --policy-profile \u003cauto/strict/balanced/aggressive\u003e` | Apply a risk posture by explicit profile or by `.gitresolve/policy.json` path mapping when set to `auto`. |\n| `gitresolve resolve --dry-run` | Preview decisions without writing files or acquiring the repository lock. |\n| `gitresolve resolve --shadow` | Simulate decisions and record hash-only before/after diffs without writing files. |\n| `gitresolve resolve --timeout \u003cduration\u003e` | Auto-select their-side resolution after the specified duration (e.g. `30s`). |\n| `gitresolve resolve --enforce-gates --manual-rate-gate \u003cpercent\u003e` | Fail the run if the manual escalation rate exceeds the specified threshold. |\n| `gitresolve scan --target \u003cbranch\u003e` | Predict conflicts against a target branch using `git merge-tree`. |\n| `gitresolve merge --policy-profile \u003cprofile\u003e` | Apply policy-based auto-resolution posture during merge execution. |\n| `gitresolve stats` | Report decision metrics and top reason codes from local observability logs. |\n| `gitresolve stats --operation \u003call/resolve/merge\u003e` | Filter stats by operation type. |\n| `gitresolve stats --json` | Emit stats as JSON for CI consumption. |\n| `gitresolve stats --top \u003cN\u003e` | Show the top N escalation reason codes. |\n| `gitresolve status` | Display block-level conflict severity and auto-resolution status per file. |\n| `gitresolve blame` | Show resolution history for audits. |\n| `gitresolve blame --patterns` | Display conflict pattern frequency analysis. |\n| `gitresolve undo --steps \u003cN\u003e` | Reset the repository to a recorded snapshot SHA from a recent session. |\n\n---\n\n## Policy Profiles\n\nPolicy profiles tune resolution risk posture per team and per path without requiring per-command flags.\n\n| Profile | Behavior |\n| :--- | :--- |\n| `strict` | Maximum escalation. Blocks `Both` for all source files. Suitable for critical paths (auth, payments, migrations). |\n| `balanced` | Default posture. Escalates on type conflicts and unbalanced struct changes. |\n| `aggressive` | Maximum automation. Suitable for generated code, documentation, or low-risk paths. |\n| `auto` | Resolved from `.gitresolve/policy.json` by longest path match, then team ownership, then default. |\n\n### Configuration Example\n\nCreate `.gitresolve/policy.json` at the repository root:\n\n```json\n{\n  \"default\": \"balanced\",\n  \"path_profiles\": {\n    \"internal/auth/\": \"strict\",\n    \"internal/payments/\": \"strict\",\n    \"docs/\": \"aggressive\"\n  },\n  \"team_profiles\": {\n    \"security\": \"strict\",\n    \"frontend\": \"aggressive\"\n  }\n}\n```\n\nTo preview which profile applies to a given file:\n\n```bash\ngitresolve resolve --policy-profile auto --dry-run internal/auth/handler.go\n```\n\n---\n\n## Observability and Stats\n\nAll decisions are stored in a local SQLite database capped at 1000 records. Query them at any time:\n\n```bash\ngitresolve stats --json\n```\n\nExample output:\n\n```json\n{\n  \"total_decisions\": 47,\n  \"auto_resolved\": 31,\n  \"escalated_to_manual\": 16,\n  \"escalation_rate\": 0.34,\n  \"top_escalation_reasons\": [\n    { \"reason\": \"semantic.field_type_conflict\", \"count\": 9 },\n    { \"reason\": \"validation.go_syntax_failed\", \"count\": 4 },\n    { \"reason\": \"parser.malformed_marker\", \"count\": 3 }\n  ]\n}\n```\n\nReason codes follow a stable, additive contract. Existing codes are never renamed or removed between releases. New codes are added under existing namespaces:\n\n- `parser.*` for marker-level parsing failures\n- `semantic.*` for type, field, or signature conflicts\n- `strategy.*` for policy and strategy enforcement decisions\n- `validation.*` for pre-write syntax and structural validation failures\n\n---\n\n## CI Integration\n\n### Non-Interactive Mode\n\n```bash\ngitresolve resolve --non-interactive --timeout 1m\n```\n\nExits with status 1 if any conflict requires manual resolution, making it safe to use as a pipeline gate.\n\n### Escalation Rate Gating\n\nFail a CI job if manual escalation exceeds a defined threshold:\n\n```bash\ngitresolve resolve --enforce-gates --manual-rate-gate 30\n```\n\nOr query the stats output directly:\n\n```bash\ngitresolve stats --json | jq 'if .escalation_rate \u003e 0.4 then error(\"escalation rate too high\") else . end'\n```\n\n### GitHub Actions Example\n\n```yaml\n- name: Resolve merge conflicts\n  run: |\n    gitresolve resolve --non-interactive --policy-profile auto --timeout 2m\n\n- name: Check escalation rate\n  run: |\n    gitresolve stats --json | jq 'if .escalation_rate \u003e 0.35 then error(\"manual escalation rate exceeded threshold\") else . end'\n```\n\n---\n\n## Architecture\n\nThe resolution pipeline executes locally with no external API dependencies.\n\n```mermaid\nflowchart TD\n    Start[Trigger Resolve] --\u003e Lock[Acquire Repository Lock]\n    Lock --\u003e Identify[Identify Conflicted Files]\n    Identify --\u003e Loop{For Each File}\n\n    Loop --\u003e Parse[Parse Conflict Markers]\n    Parse --\u003e Recover[Symmetric Brace Recovery]\n    Recover --\u003e Classify[AST and Heuristic Classification]\n\n    Classify --\u003e Config{Config File?}\n    Config -- Yes --\u003e DeepMerge[Deep Map Merge]\n    DeepMerge --\u003e Validate\n\n    Config -- No --\u003e Safe{Safe Text Change?}\n    Safe -- Yes --\u003e AutoResolve[Auto-merge Imports / Whitespace]\n    AutoResolve --\u003e Validate\n\n    Safe -- No --\u003e Risk{High-risk Semantic?}\n    Risk -- Yes --\u003e Escalate[Escalate to Manual + Log Reason Code]\n    Risk -- No --\u003e Strategy[Apply Strategy via Policy Profile]\n    Strategy --\u003e Validate\n\n    Validate[Pre-write Syntax Validation] --\u003e Pass{Valid?}\n    Pass -- No --\u003e Escalate\n    Pass -- Yes --\u003e Write[Atomic Write + Git Stage]\n\n    Write --\u003e Log[Persist Decision to SQLite]\n    Escalate --\u003e Log\n    Log --\u003e Next{More Files?}\n    Next -- Yes --\u003e Loop\n    Next -- No --\u003e Unlock[Release Lock]\n    Unlock --\u003e Done[Exit]\n```\n\n---\n\n## Testing\n\n### Tiered Test Suite\n\nThe test suite validates resolution accuracy across four severity levels:\n\n| Level | Coverage |\n| :--- | :--- |\n| 1 - Easy | Whitespace normalization, identical dual-sided modifications, Go import deduplication. |\n| 2 - Medium | JSON deep object merging, YAML array overlaps, `go.mod` require block conflicts. |\n| 3 - Hard | Complex `package.json` script updates, delete-vs-modify conflicts, multi-file batch resolution. |\n| 4 - Severe | AST parsing resilience under malformed input, concurrent lock contention, database migration file consistency. |\n\n### Safety-Oriented Coverage\n\nBeyond functional correctness, the suite includes:\n\n- **Fuzz oracle tests** for parser and resolution invariants and corruption guards.\n- **Idempotency tests** to ensure repeated resolution runs produce identical output.\n- **Strategy consistency tests** to prevent cross-strategy contamination.\n- **Corpus deduplication tests** using normalized conflict fingerprints to keep real-world regression sets efficient and signal-rich.\n- **Regression coverage** for malformed marker behavior, brace recovery paths, and high-risk `Both` blocking.\n\n```bash\ngo test ./...\n```\n\n---\n\n## Evidence and Limitations\n\n`gitresolve` is currently best described as an early-beta, safety-oriented resolver with production-grade architectural direction.\n\n### What the tool does well\n\n- Applies deterministic processing pipelines for known conflict classes: classification, strategy selection, pre-write verification.\n- Uses full-file Go syntax validation before any write operation.\n- Provides explicit manual escalation paths with machine-readable reason codes rather than forcing risky auto-resolution.\n- Records structured decision telemetry for auditability, pattern analysis, and iterative hardening.\n\n### Current limitations\n\n- Semantic correctness is not guaranteed even when syntax validation passes. Passing compilation is a necessary but not sufficient condition for correctness.\n- AST and parser capability is language- and environment-dependent. Unsupported languages escalate with explicit reason codes rather than attempting unsafe resolution.\n- Heuristic recovery paths for malformed markers prioritize safe fallback and may still require manual review.\n- Real-world robustness is dependent on repository style, language mix, and conflict shape diversity. Published metrics will be added as corpus coverage grows.\n\n### Recommended usage posture\n\n- Treat auto-resolution as an acceleration layer, not a replacement for developer review.\n- Always run builds and tests after resolution in CI workflows.\n- Use `--shadow` and decision logs to evaluate risk before enabling stricter enforcement gates.\n\n---\n\n## Readiness Gates\n\nTo move from early-beta toward production-grade confidence, use explicit measurable gates.\n\n### Active operational gates\n\n- Validation failures are hard-fail conditions with non-zero exit.\n- Optional manual escalation-rate gating via `--enforce-gates` and `--manual-rate-gate \u003cpercent\u003e`.\n\n### Suggested release progression\n\n| Gate | Condition |\n| :--- | :--- |\n| Beta | Validation failure rate is zero across sustained CI runs. |\n| Release Candidate | Stable manual escalation rate trend over a defined observation window with no data-corruption incidents. |\n| Production | Corpus coverage and regression targets met. Real-world resolution metrics published. |\n\n---\n\n## Comparative Positioning\n\n`gitresolve` is positioned as a local-first, safety-oriented conflict resolution layer on top of standard Git workflows. It is not a visual merge tool and does not require an IDE or external AI API.\n\n### Relative strengths\n\n- Conservative escalation by default: prefers a logged escalation over a silent wrong resolution.\n- Structured-data merge support across JSON, YAML, and TOML with conservative array handling.\n- CI-oriented operational controls: `--non-interactive`, `--timeout`, `--shadow`, `--enforce-gates`.\n- Full local execution with no network dependency or API key requirement.\n- Built-in observability via decision logs, stable reason codes, and the `stats` command.\n\n### Known tradeoffs\n\n- Semantic strategies are intentionally conservative and will escalate more conflicts than tools that optimize for automation rate over safety.\n- Language breadth is still evolving. Go support is the most mature.\n- Some conflicts will remain manual by design. This is a feature, not a gap.\n\n---\n\n## License\n\nSee [LICENSE](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhanvi857%2Fgitresolve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhanvi857%2Fgitresolve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhanvi857%2Fgitresolve/lists"}