git-trace 1.0.0__py3-none-any.whl

git_trace/utils.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+from enum import Enum
+
+
+class Color(Enum):
+    RESET = "\033[0m"
+
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    ITALIC = "\033[3m"
+    UNDERLINE = "\033[4m"
+    BLINK = "\033[5m"
+    REVERSE = "\033[7m"
+    HIDDEN = "\033[8m"
+
+    BLACK = "\033[30m"
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    BLUE = "\033[34m"
+    MAGENTA = "\033[35m"
+    CYAN = "\033[36m"
+    WHITE = "\033[37m"
+
+    BRIGHT_BLACK = "\033[90m"
+    BRIGHT_RED = "\033[91m"
+    BRIGHT_GREEN = "\033[92m"
+    BRIGHT_YELLOW = "\033[93m"
+    BRIGHT_BLUE = "\033[94m"
+    BRIGHT_MAGENTA = "\033[95m"
+    BRIGHT_CYAN = "\033[96m"
+    BRIGHT_WHITE = "\033[97m"
+
+    BG_BLACK = "\033[40m"
+    BG_RED = "\033[41m"
+    BG_GREEN = "\033[42m"
+    BG_YELLOW = "\033[43m"
+    BG_BLUE = "\033[44m"
+    BG_MAGENTA = "\033[45m"
+    BG_CYAN = "\033[46m"
+    BG_WHITE = "\033[47m"
+
+    BG_BRIGHT_BLACK = "\033[100m"
+    BG_BRIGHT_RED = "\033[101m"
+    BG_BRIGHT_GREEN = "\033[102m"
+    BG_BRIGHT_YELLOW = "\033[103m"
+    BG_BRIGHT_BLUE = "\033[104m"
+    BG_BRIGHT_MAGENTA = "\033[105m"
+    BG_BRIGHT_CYAN = "\033[106m"
+    BG_BRIGHT_WHITE = "\033[107m"
+
+
+# TODO: make configurable ?
+SHORT_HASH_LENGTH: int = 7
+
+MAX_COMMIT_MESSAGE_LENGTH: int = 48
+
+WARNING_COLOR: Color = Color.YELLOW
+INFO_COLOR: Color = Color.BRIGHT_BLUE
+ERROR_COLOR: Color = Color.BRIGHT_RED
+
+
+def cprint(text: str, color: Color | None = None, end: str = "\n"):
+    if color is not None:
+        print(f"{color.value}{text}{Color.RESET.value}", end=end)
+    else:
+        print(text, end=end)
+
+
+def yaml2list(value: object) -> list[str] | None:
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    return [str(value)]
+
+
+def read_cleaned_file(path: str) -> list[str]:
+    with open(path, "r", encoding="utf-8") as file:
+        return [
+            stripped
+            for line in file
+            if (stripped := line.strip()) and not stripped.startswith("#")
+        ]

git_trace/version.py

@@ -0,0 +1,2 @@
+__version__ = "1.0.0"
+VERSION = __version__.split(".")

git_trace-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,25 @@
+git_trace/__init__.py,sha256=sLoG2b_UXsgAboKmqKAht0caM7wOb-t59LGE4xGmvzA,90
+git_trace/__main__.py,sha256=hpG9V_OF_ZEiP7LEVsu5VwGxIv-pJq2ZhoE0uQ3C_5g,40
+git_trace/analysis.py,sha256=ubCftMU_rAjKWx3Al-AbGSCRMN_lgjihXrWP7C0qT4A,7295
+git_trace/git.py,sha256=DDxrRQ27_wveqlqoCuX_g5bgcX0qyIR8jmIROf65K8s,1985
+git_trace/main.py,sha256=Zpbcu9rItNLXZSj-PRUBCWX8RjgDGZGYXoqODSqDhFQ,5591
+git_trace/utils.py,sha256=LB3pKtc61UoasdqC0ZB0PmVru_HuPgYCC_vaTkDJvjY,2020
+git_trace/version.py,sha256=oXo2yBb6TVZlnuNiWlGwrRYGRjUDgr2Lsdi7jeNsBlE,55
+git_trace/input/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+git_trace/input/args.py,sha256=VMEe92GFvivaMwqtdnQvYdm3WRT1wNYRDk3COK10G6Y,7108
+git_trace/input/parser.py,sha256=04rB9fujKQU5ekjMvl4-ta25j8pS-orVW9nMrLMvxRM,6585
+git_trace/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+git_trace/output/graph.py,sha256=8q5eznPqDpd2OA7yjPl5Ih7lkQuWq2E1VZ8aMOqMpvE,7918
+git_trace/output/html_injection.py,sha256=WK_B5m6ByNm2xHTZK_GyAwSIsx43NVqR1itSUe7e3uE,924
+git_trace/output/text.py,sha256=1WVnQuptRayvhHXU7VeLqdTtQLM7q_uRa2PJYv0yJc8,4172
+git_trace/output/assets/analysis_controls.html,sha256=M7E6WMnYi8sRZm2jkZl0B5g7QQsu1-nlhFHnvB02BH4,3336
+git_trace/output/assets/analysis_legend.html,sha256=De0N9I8-VaimMsz-Stu17BDmrfdoa8-QS3xPoyhmp9A,697
+git_trace/output/assets/pick_controls.html,sha256=rD15mueaavMRj5A0M3SHgHCgCPOw8vvTM6gMMpkRbHA,4091
+git_trace/output/assets/pick_legend.html,sha256=OvjcRXlJ_w7u5i392UcOdNBZw-b25w1d520LDJEoUpI,1081
+git_trace/output/assets/styling.html,sha256=ZfUXAAdyJ8ZWT30eUYYkdqVJ97_Gz62XCktrQMXcrMk,89
+git_trace-1.0.0.dist-info/licenses/LICENSE,sha256=PXKTIdUpzeVudoU3sRbr6Q7guZ-bEAtvGYZZEalvbvQ,1077
+git_trace-1.0.0.dist-info/METADATA,sha256=hcxeHNGbtH2L5rGZuMtweU5RIXXEN435y3bmB5igrDs,9367
+git_trace-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+git_trace-1.0.0.dist-info/entry_points.txt,sha256=ddqkSwgll-iCObso5z0YOM-K_JUfDyCiTCqbAh2e_dE,50
+git_trace-1.0.0.dist-info/top_level.txt,sha256=9NrlAIs_e3v3UElq3U5y9UwstLEQ2dyDOd9jzafSVsM,10
+git_trace-1.0.0.dist-info/RECORD,,

git_trace-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

git_trace-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-trace = git_trace.main:main

git_trace-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+git_trace