git-trace 1.0.0__tar.gz

git_trace-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Karol Kiszka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_trace-1.0.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: git-trace
+Version: 1.0.0
+Summary: Visualise git commit dependencies – see which commits edit lines introduced by earlier commits.
+Author-email: Karol Kiszka <karolkisz22@gmail.com>
+License: MIT
+Project-URL: source, https://github.com/kiszkacy/git-trace
+Keywords: git
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: Console
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyvis>=0.3
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: colorama>=0.4.6
+Dynamic: license-file
+
+# git-trace
+
+![Python version](https://img.shields.io/badge/python-%3E%3D%203.10-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+![PyPI](https://img.shields.io/pypi/v/git-trace.svg)
+
+Visualize commit dependencies in a git repository. For a given branch (or commit
+range) `git-trace` analyses every diff and reports which commits **depend** on
+earlier ones, in the sense that they modify or remove lines previously added by
+those earlier commits. The result is rendered as either a text tree, a plain
+list, or an interactive HTML graph.
+
+> **Disclaimer:** This tool was built specifically with single-branch analysis in mind.
+> While it **might** work across divergent branches, your mileage may vary and
+> I am not responsible for any inaccurate results if you choose to use it that way.
+
+A secondary mode (`--picks`) treats the analysis as a cherry-pick safety check:
+given a set of commit hashes you intend to pick, it tells you which are safe,
+which are blocked by missing dependencies, and which would become "conditional"
+on picking other commits as well.
+
+![git-trace demo](docs/demo.png)
+
+## Installation
+
+```bash
+pip install git-trace
+```
+
+or from source:
+
+```bash
+git clone https://github.com/kiszkacy/git-trace
+cd git-trace
+pip install -e .
+```
+
+Requires Python 3.10+ and `git` available via `PATH`.
+
+## Quick start
+
+Run from inside a git repository:
+
+```bash
+git-trace                                  # analyse the full history of 'main'
+git-trace dev                              # analyse 'dev' branch
+git-trace dev --after abc1234              # only commits after a hash
+git-trace dev --after abc --before def     # a commit range
+git-trace --no-graph                       # skip HTML, print text only
+git-trace --list                           # simplified list output + HTML graph
+git-trace --list --no-graph                # simplified list output only
+```
+
+For cherry-pick analysis:
+
+```bash
+git-trace dev --picks h1 h2 h3             # check whether picks are safe
+git-trace dev --picks picks.txt            # picks from a file
+```
+
+By default `git-trace` writes an interactive HTML graph to `./output.html` and
+also prints a text summary to stdout.
+
+## CLI arguments
+
+| Argument | Description |
+| --- | --- |
+| `branch` | Branch to analyse. Defaults to `main`. Positional. |
+| `--after HASH` | Only include commits *after* this hash (the hash itself is excluded). |
+| `--before HASH` | Only include commits up to this hash (the hash itself is excluded). |
+| `--whitelist HASH... \| FILE` | Restrict analysis to these hashes, or to a file containing hashes (one per line). Takes priority over `--blacklist`. Auto-loaded from `whitelist.txt` if present and the flag is omitted. |
+| `--blacklist HASH... \| FILE` | Exclude these hashes from analysis, or a file containing hashes. Auto-loaded from `blacklist.txt` if present. |
+| `--picks HASH... \| FILE` | Enable cherry-pick analysis. The given hashes are treated as the intended pick set; the tool reports safe / blocked / conditional picks. Auto-loaded from `picks.txt` if present. |
+| `--ignore-paths PATH... \| FILE` | Repository-relative paths whose diffs should be ignored during analysis, or a file listing such paths. Auto-loaded from `ignore-paths.txt` if present. |
+| `--repo DIR` | Path to the git repository root. Defaults to the current directory. |
+| `--config FILE` | Path to a YAML config file. Defaults to `./config.yml`. |
+| `--no-graph` | Skip HTML graph generation. |
+| `--list` | Print a simple list of relevant commit hashes (one per line) instead of the formatted text tree. The HTML graph is still generated; combine with `--no-graph` to suppress it. |
+| `--output PATH` | Path for the generated HTML graph. Defaults to `./output.html`. |
+| `--txt-output PATH` | Also write the text output to this file. |
+| `-v`, `--version` | Print version and exit. |
+
+### Precedence rules
+
+1. CLI arguments
+2. `config.yml` values (if the file exists)
+3. Auto-loaded files (`whitelist.txt`, `blacklist.txt`, `picks.txt`, `ignore-paths.txt`)
+
+A more specific source overrides a less specific one
+(i.e. CLI wins over config, config wins over auto-load).
+
+## config.yml
+
+If a file named `config.yml` exists in the current working directory it is
+loaded automatically. Pass `--config FILE` to use a different path. Any CLI
+option can be set there. Example:
+
+```yaml
+branch: dev
+after: abc1234
+ignore-paths:
+  - vendor/
+  - generated/
+output: ./trace.html
+no-graph: false
+picks:
+  - a1b2c3d
+  - 9988776
+```
+
+Keys mirror the CLI flag names (use `-` not `_`). Values may be strings, lists,
+or booleans depending on the option.
+
+## Auto-loaded files
+
+If you omit a flag, `git-trace` looks in the current directory for a matching
+file and loads it automatically:
+
+| File | Equivalent flag |
+| --- | --- |
+| `whitelist.txt` | `--whitelist` |
+| `blacklist.txt` | `--blacklist` |
+| `picks.txt` | `--picks` |
+| `ignore-paths.txt` | `--ignore-paths` |
+
+Each file holds one entry per line. Blank lines and lines starting with `#` are
+ignored.
+
+## Output
+
+- **Formatted text** (default): a tree-style listing of commits and their
+  dependencies, printed to stdout.
+- **HTML graph** (default): an interactive force-directed graph written to
+  `./output.html`. Open it in any browser.
+- **`--list`**: a flat list of hashes (one per line), suitable for piping into
+  other scripts. The HTML graph is still produced unless `--no-graph` is also specified.
+- **`--txt-output FILE`**: also write the formatted text to a file.
+
+In `--picks` mode the text output is grouped into `safe`, `blocked` (with the
+list of missing dependencies for each) and `conditional` sections, while the HTML
+graph highlights the pick set, blockers, and conditionals in distinct colors.
+
+## How dependency detection works
+
+`git-trace` uses a position-aware analyzer. For each commit it replays the
+diff hunks against a virtual snapshot of every file, tracked as a list of
+`(line_content, owning_commit)` pairs. When a later commit removes or
+overwrites a line, the analyzer consults the owner stored for that exact
+position and records a dependency on whichever earlier commit introduced
+that line. Identical line content appearing in different places of a file is
+correctly treated as independent.
+
+The analyzer handles file creation, deletion (`+++ /dev/null`), renames
+(`rename from` / `rename to`), and the `@@ -X,0 +Y,N @@` insertion hunks
+correctly.
+
+### Textual vs. Structural Dependencies
+
+It is important to note that git-trace evaluates **purely textual dependencies**,
+not structural or semantic ones. It only tracks modifications on a line-by-line basis.
+It does not parse an Abstract Syntax Tree (AST) to understand code logic,
+variable scopes, or function calls.
+
+## Known limitations
+
+- **Copies (`copy from` / `copy to`)** → a copied file is treated as a fresh
+  new file rather than inheriting history from the source path. In practice
+  this is rare since git rarely produces copy markers by default.
+- **Binary files** are silently skipped → no dependency is recorded for
+  changes to binary blobs.
+- **Mode-only changes** (e.g. `chmod`) → are silently ignored, since they
+  don't affect any tracked content.
+- **Quoted paths in diffs** (`core.quotePath`) → git's `core.quotePath`
+  setting (default: `true`) wraps file paths containing non-ASCII or special
+  characters in backslash-escaped double quotes when producing diff output.
+  The analyser reads paths literally after `+++ b/`, so a quoted path will
+  not match its real on-disk name. If you analyse a repo with non-ASCII
+  filenames, set `git config core.quotePath false` first.
+- **`diff.noprefix` / `--no-prefix` diffs** → when `diff.noprefix` is
+  enabled, git's diff output omits the `a/` and `b/` path prefixes (e.g.
+  `--- file.txt` instead of `--- a/file.txt`). The analyser specifically
+  looks for the `a/` and `b/` prefixes to identify files, so under that
+  configuration no dependencies will be detected. Keep `diff.noprefix` at
+  its default (`false`) when running `git-trace`.
+
+## AI usage
+
+LLM was used during the development of this project, specifically for:
+- Writing the core dependency detection logic and processing the Git hunk headers.
+- Injecting the custom HTML templates and dynamic styling payloads into pyvis html output.
+- Generating most of the README.md content.
+
+## License
+
+MIT &mdash; see [LICENSE](LICENSE).

git_trace-1.0.0/README.md

@@ -0,0 +1,195 @@
+# git-trace
+
+![Python version](https://img.shields.io/badge/python-%3E%3D%203.10-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+![PyPI](https://img.shields.io/pypi/v/git-trace.svg)
+
+Visualize commit dependencies in a git repository. For a given branch (or commit
+range) `git-trace` analyses every diff and reports which commits **depend** on
+earlier ones, in the sense that they modify or remove lines previously added by
+those earlier commits. The result is rendered as either a text tree, a plain
+list, or an interactive HTML graph.
+
+> **Disclaimer:** This tool was built specifically with single-branch analysis in mind.
+> While it **might** work across divergent branches, your mileage may vary and
+> I am not responsible for any inaccurate results if you choose to use it that way.
+
+A secondary mode (`--picks`) treats the analysis as a cherry-pick safety check:
+given a set of commit hashes you intend to pick, it tells you which are safe,
+which are blocked by missing dependencies, and which would become "conditional"
+on picking other commits as well.
+
+![git-trace demo](docs/demo.png)
+
+## Installation
+
+```bash
+pip install git-trace
+```
+
+or from source:
+
+```bash
+git clone https://github.com/kiszkacy/git-trace
+cd git-trace
+pip install -e .
+```
+
+Requires Python 3.10+ and `git` available via `PATH`.
+
+## Quick start
+
+Run from inside a git repository:
+
+```bash
+git-trace                                  # analyse the full history of 'main'
+git-trace dev                              # analyse 'dev' branch
+git-trace dev --after abc1234              # only commits after a hash
+git-trace dev --after abc --before def     # a commit range
+git-trace --no-graph                       # skip HTML, print text only
+git-trace --list                           # simplified list output + HTML graph
+git-trace --list --no-graph                # simplified list output only
+```
+
+For cherry-pick analysis:
+
+```bash
+git-trace dev --picks h1 h2 h3             # check whether picks are safe
+git-trace dev --picks picks.txt            # picks from a file
+```
+
+By default `git-trace` writes an interactive HTML graph to `./output.html` and
+also prints a text summary to stdout.
+
+## CLI arguments
+
+| Argument | Description |
+| --- | --- |
+| `branch` | Branch to analyse. Defaults to `main`. Positional. |
+| `--after HASH` | Only include commits *after* this hash (the hash itself is excluded). |
+| `--before HASH` | Only include commits up to this hash (the hash itself is excluded). |
+| `--whitelist HASH... \| FILE` | Restrict analysis to these hashes, or to a file containing hashes (one per line). Takes priority over `--blacklist`. Auto-loaded from `whitelist.txt` if present and the flag is omitted. |
+| `--blacklist HASH... \| FILE` | Exclude these hashes from analysis, or a file containing hashes. Auto-loaded from `blacklist.txt` if present. |
+| `--picks HASH... \| FILE` | Enable cherry-pick analysis. The given hashes are treated as the intended pick set; the tool reports safe / blocked / conditional picks. Auto-loaded from `picks.txt` if present. |
+| `--ignore-paths PATH... \| FILE` | Repository-relative paths whose diffs should be ignored during analysis, or a file listing such paths. Auto-loaded from `ignore-paths.txt` if present. |
+| `--repo DIR` | Path to the git repository root. Defaults to the current directory. |
+| `--config FILE` | Path to a YAML config file. Defaults to `./config.yml`. |
+| `--no-graph` | Skip HTML graph generation. |
+| `--list` | Print a simple list of relevant commit hashes (one per line) instead of the formatted text tree. The HTML graph is still generated; combine with `--no-graph` to suppress it. |
+| `--output PATH` | Path for the generated HTML graph. Defaults to `./output.html`. |
+| `--txt-output PATH` | Also write the text output to this file. |
+| `-v`, `--version` | Print version and exit. |
+
+### Precedence rules
+
+1. CLI arguments
+2. `config.yml` values (if the file exists)
+3. Auto-loaded files (`whitelist.txt`, `blacklist.txt`, `picks.txt`, `ignore-paths.txt`)
+
+A more specific source overrides a less specific one
+(i.e. CLI wins over config, config wins over auto-load).
+
+## config.yml
+
+If a file named `config.yml` exists in the current working directory it is
+loaded automatically. Pass `--config FILE` to use a different path. Any CLI
+option can be set there. Example:
+
+```yaml
+branch: dev
+after: abc1234
+ignore-paths:
+  - vendor/
+  - generated/
+output: ./trace.html
+no-graph: false
+picks:
+  - a1b2c3d
+  - 9988776
+```
+
+Keys mirror the CLI flag names (use `-` not `_`). Values may be strings, lists,
+or booleans depending on the option.
+
+## Auto-loaded files
+
+If you omit a flag, `git-trace` looks in the current directory for a matching
+file and loads it automatically:
+
+| File | Equivalent flag |
+| --- | --- |
+| `whitelist.txt` | `--whitelist` |
+| `blacklist.txt` | `--blacklist` |
+| `picks.txt` | `--picks` |
+| `ignore-paths.txt` | `--ignore-paths` |
+
+Each file holds one entry per line. Blank lines and lines starting with `#` are
+ignored.
+
+## Output
+
+- **Formatted text** (default): a tree-style listing of commits and their
+  dependencies, printed to stdout.
+- **HTML graph** (default): an interactive force-directed graph written to
+  `./output.html`. Open it in any browser.
+- **`--list`**: a flat list of hashes (one per line), suitable for piping into
+  other scripts. The HTML graph is still produced unless `--no-graph` is also specified.
+- **`--txt-output FILE`**: also write the formatted text to a file.
+
+In `--picks` mode the text output is grouped into `safe`, `blocked` (with the
+list of missing dependencies for each) and `conditional` sections, while the HTML
+graph highlights the pick set, blockers, and conditionals in distinct colors.
+
+## How dependency detection works
+
+`git-trace` uses a position-aware analyzer. For each commit it replays the
+diff hunks against a virtual snapshot of every file, tracked as a list of
+`(line_content, owning_commit)` pairs. When a later commit removes or
+overwrites a line, the analyzer consults the owner stored for that exact
+position and records a dependency on whichever earlier commit introduced
+that line. Identical line content appearing in different places of a file is
+correctly treated as independent.
+
+The analyzer handles file creation, deletion (`+++ /dev/null`), renames
+(`rename from` / `rename to`), and the `@@ -X,0 +Y,N @@` insertion hunks
+correctly.
+
+### Textual vs. Structural Dependencies
+
+It is important to note that git-trace evaluates **purely textual dependencies**,
+not structural or semantic ones. It only tracks modifications on a line-by-line basis.
+It does not parse an Abstract Syntax Tree (AST) to understand code logic,
+variable scopes, or function calls.
+
+## Known limitations
+
+- **Copies (`copy from` / `copy to`)** → a copied file is treated as a fresh
+  new file rather than inheriting history from the source path. In practice
+  this is rare since git rarely produces copy markers by default.
+- **Binary files** are silently skipped → no dependency is recorded for
+  changes to binary blobs.
+- **Mode-only changes** (e.g. `chmod`) → are silently ignored, since they
+  don't affect any tracked content.
+- **Quoted paths in diffs** (`core.quotePath`) → git's `core.quotePath`
+  setting (default: `true`) wraps file paths containing non-ASCII or special
+  characters in backslash-escaped double quotes when producing diff output.
+  The analyser reads paths literally after `+++ b/`, so a quoted path will
+  not match its real on-disk name. If you analyse a repo with non-ASCII
+  filenames, set `git config core.quotePath false` first.
+- **`diff.noprefix` / `--no-prefix` diffs** → when `diff.noprefix` is
+  enabled, git's diff output omits the `a/` and `b/` path prefixes (e.g.
+  `--- file.txt` instead of `--- a/file.txt`). The analyser specifically
+  looks for the `a/` and `b/` prefixes to identify files, so under that
+  configuration no dependencies will be detected. Keep `diff.noprefix` at
+  its default (`false`) when running `git-trace`.
+
+## AI usage
+
+LLM was used during the development of this project, specifically for:
+- Writing the core dependency detection logic and processing the Git hunk headers.
+- Injecting the custom HTML templates and dynamic styling payloads into pyvis html output.
+- Generating most of the README.md content.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

git_trace-1.0.0/git_trace/__init__.py

@@ -0,0 +1,6 @@
+from .version import VERSION, __version__
+
+__all__ = (
+    "__version__",
+    "VERSION",
+)

git_trace-1.0.0/git_trace/__main__.py

@@ -0,0 +1,3 @@
+from git_trace.main import main
+
+main()

git_trace-1.0.0/git_trace/analysis.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+from git_trace.git import Commit
+
+
+HUNK_HEADER_PATTERN: re.Pattern[str] = re.compile(r'^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@')
+
+
+@dataclass
+class DiffHunk:
+    old_start: int
+    old_count: int
+    new_start: int
+    new_count: int
+    lines: list[tuple[str, str]] = field(default_factory=list)
+
+
+@dataclass
+class FileChange:
+    path: str
+    old_path: str | None = None
+    hunks: list[DiffHunk] = field(default_factory=list)
+
+
+@dataclass
+class VirtualLine:
+    content: str
+    owner_hash: str | None
+
+
+@dataclass
+class DependencyGraph:
+    relationships: dict[str, set[str]] = field(default_factory=lambda: defaultdict(set))
+
+    def add_dependency(self, commit_hash: str, parent_hash: str) -> None:
+        self.relationships[commit_hash].add(parent_hash)
+
+    def get_dependencies_for(self, commit_hash: str) -> set[str]:
+        return self.relationships.get(commit_hash, set())
+
+
+@dataclass
+class CherryPickAnalysis:
+    safe: list[str] = field(default_factory=list)
+    conditional: list[str] = field(default_factory=list)
+    blocked: dict[str, set[str]] = field(default_factory=dict)
+
+
+def _parse_diff(diff_text: str, ignore_paths: set[str]) -> list[FileChange]:
+    changes: list[FileChange] = []
+    current_change: FileChange | None = None
+    current_hunk: DiffHunk | None = None
+    rename_from: str | None = None
+    old_path_candidate: str | None = None
+
+    for line in diff_text.splitlines():
+        if line.startswith("diff --git "):
+            if current_change is not None:
+                changes.append(current_change)
+            current_change = None
+            current_hunk = None
+            rename_from = None
+            old_path_candidate = None
+        elif line.startswith("rename from "):
+            rename_from = line[len("rename from "):].replace("\\", "/")
+        elif line.startswith("rename to "):
+            rename_to: str = line[len("rename to "):].replace("\\", "/")
+            if rename_to not in ignore_paths:
+                current_change = FileChange(path=rename_to, old_path=rename_from)
+        elif line.startswith("--- "):
+            current_hunk = None
+            old_path_candidate = line[6:].replace("\\", "/") if line.startswith("--- a/") else None
+        elif line.startswith("+++ "):
+            current_hunk = None
+            new_path: str | None = line[6:].replace("\\", "/") if line.startswith("+++ b/") else None
+            canonical_path: str | None = new_path or old_path_candidate
+            if canonical_path is None or canonical_path in ignore_paths:
+                current_change = None
+            elif current_change is not None and current_change.path == canonical_path:
+                pass
+            else:
+                old: str | None = old_path_candidate if (old_path_candidate and new_path and old_path_candidate != new_path) else None
+                current_change = FileChange(path=canonical_path, old_path=old)
+        elif current_change is not None:
+            hunk_match: re.Match[str] | None = HUNK_HEADER_PATTERN.match(line)
+            if hunk_match:
+                old_start: int = int(hunk_match.group(1))
+                old_count: int = int(hunk_match.group(2)) if hunk_match.group(2) is not None else 1
+                new_start: int = int(hunk_match.group(3))
+                new_count: int = int(hunk_match.group(4)) if hunk_match.group(4) is not None else 1
+                current_hunk = DiffHunk(
+                    old_start=old_start,
+                    old_count=old_count,
+                    new_start=new_start,
+                    new_count=new_count,
+                )
+                current_change.hunks.append(current_hunk)
+            elif current_hunk is not None and line and line[0] in ("+", "-", " "):
+                current_hunk.lines.append((line[0], line[1:]))
+
+    if current_change is not None:
+        changes.append(current_change)
+    return changes
+
+
+# wild opus dependency graph building logic
+def build_dependency_graph(commits: list[Commit], raw_diffs: dict[str, str], ignore_paths: set[str] | None = None) -> DependencyGraph:
+    virtual_files: dict[str, list[VirtualLine]] = {}
+    graph: DependencyGraph = DependencyGraph()
+    ignore_paths = ignore_paths or set()
+
+    for commit in commits:
+        diff_text: str = raw_diffs.get(commit.hash, "")
+        file_changes: list[FileChange] = _parse_diff(diff_text, ignore_paths)
+
+        for change in file_changes:
+            if change.old_path is not None and change.old_path in virtual_files:
+                virtual_files[change.path] = virtual_files.pop(change.old_path)
+            else:
+                virtual_files.setdefault(change.path, [])
+
+            virtual_file: list[VirtualLine] = virtual_files[change.path]
+            cumulative_offset: int = 0
+
+            for hunk in change.hunks:
+                position: int = (
+                    hunk.old_start if hunk.old_count == 0
+                    else max(0, hunk.old_start - 1)
+                ) + cumulative_offset
+
+                while len(virtual_file) < position + hunk.old_count:
+                    virtual_file.append(VirtualLine(content="", owner_hash=None))
+
+                new_entries: list[VirtualLine] = []
+                old_index: int = position
+
+                for line_type, content in hunk.lines:
+                    if line_type == " ":
+                        new_entries.append(virtual_file[old_index])
+                        old_index += 1
+                    elif line_type == "-":
+                        existing_line = virtual_file[old_index]
+                        if existing_line.owner_hash is not None and existing_line.owner_hash != commit.hash:
+                            graph.add_dependency(commit.hash, existing_line.owner_hash)
+                        old_index += 1
+                    elif line_type == "+":
+                        new_entries.append(VirtualLine(content=content, owner_hash=commit.hash))
+
+                virtual_file[position:position + hunk.old_count] = new_entries
+                cumulative_offset += hunk.new_count - hunk.old_count
+
+    return graph
+
+
+def filter_picks(pick_hashes: set[str], graph: DependencyGraph) -> CherryPickAnalysis:
+    blocked: dict[str, set[str]] = {}
+    for commit_hash in pick_hashes:
+        missing: set[str] = graph.get_dependencies_for(commit_hash) - pick_hashes
+        if missing:
+            blocked[commit_hash] = missing
+
+    tainted: set[str] = set(blocked.keys())
+    changed: bool = True
+    while changed:
+        changed = False
+        for commit_hash in pick_hashes:
+            if commit_hash not in tainted:
+                in_pick_dependencies: set[str] = graph.get_dependencies_for(commit_hash) & pick_hashes
+                if in_pick_dependencies & tainted:
+                    tainted.add(commit_hash)
+                    changed = True
+
+    conditional: list[str] = [commit_hash for commit_hash in pick_hashes if commit_hash in tainted and commit_hash not in blocked]
+    safe: list[str] = [commit_hash for commit_hash in pick_hashes if commit_hash not in tainted]
+    return CherryPickAnalysis(
+        safe=safe,
+        conditional=conditional,
+        blocked=blocked
+    )

git_trace-1.0.0/git_trace/git.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Commit:
+    hash: str
+    message: str
+
+    def is_inside_hash_set(self, hash_set: set[str]) -> bool:
+        return any(self.hash.startswith(prefix) or prefix.startswith(self.hash) for prefix in hash_set)
+
+
+def run_git(*args: str, repo_directory: str) -> str:
+    command: list[str] = ["git"]
+    if repo_directory:
+        command += ["-C", repo_directory]
+    command += list(args)
+    process: subprocess.CompletedProcess[str] = subprocess.run(
+        command, capture_output=True, encoding="utf-8", errors="replace"
+    )
+    return process.stdout or ""
+
+
+def get_commits(branch: str, repo_directory: str, after: str | None = None, before: str | None = None) -> list[Commit]:
+    scope: str = f"{after if after else ''}{'..' if after else ''}{before if before else branch}"
+    output: str = run_git("log", scope, "--reverse", "--format=%H %s", repo_directory=repo_directory)
+
+    commits: list[Commit] = []
+    for line in output.splitlines():
+        line = line.strip()
+        if line:
+            commit_hash, _, message = line.partition(" ")
+            commits.append(Commit(hash=commit_hash, message=message))
+
+    if before and commits: # skip last commit to exclude it
+        commits.pop()
+
+    return commits
+
+
+def get_commit_diff(sha: str, repo_directory: str) -> str:
+    return run_git("show", "--format=", "-p", sha, repo_directory=repo_directory)
+
+
+def resolve_hashes(hashes: list[str], all_commits: list[Commit]) -> dict[str, str | None]:
+    full_hashes: list[str] = [commit.hash for commit in all_commits]
+    result: dict[str, str | None] = {}
+    for hash_ in hashes: # if user provided short hashes map them to full hashes if possible
+        matches: list[str] = [full_hash for full_hash in full_hashes if full_hash.lower().startswith(hash_.lower())]
+        result[hash_] = matches[0] if len(matches) == 1 else None
+    return result