import-resolve

Auto-resolve Git merge conflicts in Python import blocks. Deterministic, zero dependencies, zero config, no AI.

Before / after (from a real git merge)

Two branches each added one import. Git conflicted. import-resolve kept both.

Before (docs/examples/app.before.py):

import json
<<<<<<< HEAD
import os
=======
import math
>>>>>>> feature-a

print(json.dumps({'ok': True}))

Terminal:

$ import-resolve
[ok] app.py: resolved 1 import conflict

After (docs/examples/app.after.py):

import json
import math
import os

print(json.dumps({'ok': True}))

Both branches survive. Duplicates removed. Sorted. Conflict markers gone.

Install

From PyPI (once published):

pip install import-resolve-cli

From this GitHub repo (works today):

pip install git+https://github.com/ikrame-ih/import-resolve.git

That installs the import-resolve command. The PyPI package is named import-resolve-cli because import-resolve is already taken by an unrelated project from 2017.

Requires Python 3.9+. No runtime dependencies — a few hundred lines of standard library.

Usage

import-resolve                 # fix every conflicted .py file Git reports
import-resolve app.py utils.py # fix specific files
import-resolve --dry-run       # show the diff, write nothing
import-resolve --check         # exit 1 if any conflict markers are found (CI)

Exit codes: 0 all import conflicts resolved (or none existed), 1 conflicts remain for a human, 2 usage error.

Optional: fully automatic mode

Register a merge driver in the current repository only:

import-resolve --install-hook    # .git/config + .git/info/attributes
import-resolve --uninstall-hook

After that, git merge / rebase / cherry-pick clear pure-import conflicts quietly and only stop for conflicts that need a person. Nothing goes into global Git config or into the versioned tree — teammates opt in themselves.

Safety model

If a conflict block contains one line that is not an import, a comment, or a blank line, the block is left untouched and you get a reason:

[skip] app.py:14: left untouched for safety (non-import line: 'value = compute()')

Also refused (on purpose):

• multiline imports (from typing import ( … ))
• backslash line continuations
• indented imports (inside functions / try)

Extra guards:

• merged block must pass ast.parse or nothing is written
• atomic write (temp file + os.replace)
• LF/CRLF and UTF-8 BOM preserved
• binary / non-UTF-8 / files over 5 MB refused
• no network, no AI, no telemetry — code never leaves your machine

Logic conflicts further down the same file stay exactly as Git left them.

What it does NOT do

Out of scope	Why
Business-logic conflicts	That needs a human
Multiline import blocks	Too easy to corrupt; skipped with a warning
Full isort/ruff style	Run your formatter after; we sort simply
JS/TS imports	Possible v2
Config files	Zero config is the point

Why this exists (short case study)

Import conflicts are mechanical: two people added different import lines to the same header. Current options are weak for that case:

• GitHub's CLI guide — open the editor and delete markers by hand
• StackOverflow --ours / --theirs — destructive; one side's imports vanish
• isort / ruff / Black — fail with a syntax error while markers are present
• AI resolvers — need API keys, send code off-machine, non-deterministic
• Mergiraf — excellent structural merge driver; if you want that full pipeline and can install a Rust binary + Git config, use it

import-resolve is the remaining gap: the file is already broken in front of you, and you want one local command, right now, with nothing configured.

Roadmap

• JS/TS import blocks (v2, if there's demand)
• --stage to git add fully resolved files

Development

pip install -e ".[dev]"
pytest
mypy
ruff check .

License

MIT © Ikrame Ih