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

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