git-xray-tool 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ckh0at
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,160 @@
1
+ Metadata-Version: 2.5
2
+ Name: git-xray-tool
3
+ Version: 0.1.0
4
+ Summary: X-ray any git repo in one command: hotspots, bus factor, hidden coupling, stale code. Zero dependencies.
5
+ Project-URL: Homepage, https://github.com/ckh0at/git-xray
6
+ Project-URL: Source, https://github.com/ckh0at/git-xray
7
+ Project-URL: Issues, https://github.com/ckh0at/git-xray/issues
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: bus-factor,cli,code-analysis,code-quality,git,hotspots,technical-debt
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development :: Quality Assurance
15
+ Classifier: Topic :: Software Development :: Version Control :: Git
16
+ Requires-Python: >=3.9
17
+ Description-Content-Type: text/markdown
18
+
19
+ <div align="center">
20
+
21
+ # git-xray 🩻
22
+
23
+ **X-ray any git repository in one command.**
24
+ Find the code that hurts: hotspots, bus factor, hidden coupling, stale and orphaned files.
25
+
26
+ [![PyPI](https://img.shields.io/pypi/v/git-xray-tool.svg)](https://pypi.org/project/git-xray-tool/)
27
+ [![Python](https://img.shields.io/pypi/pyversions/git-xray-tool.svg)](https://pypi.org/project/git-xray-tool/)
28
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
29
+
30
+ <img src="https://raw.githubusercontent.com/ckh0at/git-xray/main/docs/demo.svg" alt="git-xray running on the Flask repository" width="820">
31
+
32
+ </div>
33
+
34
+ ```bash
35
+ pipx install git-xray-tool # or: pip install git-xray-tool
36
+ # one-off run: uvx --from git-xray-tool git-xray
37
+ cd your-repo
38
+ git xray
39
+ ```
40
+
41
+ The package is called `git-xray-tool` on PyPI; the command is `git-xray`, or just
42
+ `git xray`. No config, no server, no dependencies. Pure Python and `git`. It analyses Flask's
43
+ 3,800 commits in **under a second**.
44
+
45
+ ---
46
+
47
+ ## Why?
48
+
49
+ Your git history already knows where the problems are. The files that change
50
+ all the time *and* are large are where bugs pile up and velocity goes to die.
51
+ Directories that only one person understands are a risk. Files that always change
52
+ together hint at a missing abstraction.
53
+
54
+ Tools like [code-maat](https://github.com/adamtornhill/code-maat) pioneered this
55
+ analysis (see *Your Code as a Crime Scene*), but they need a JVM, a log export
56
+ step and a spreadsheet. `git-xray` gives you the answers in one command.
57
+
58
+ ## What it shows
59
+
60
+ | Section | Question it answers |
61
+ |---|---|
62
+ | πŸ”₯ **Hotspots** | Which files change most often *and* are big? Your best refactoring targets. |
63
+ | 🚌 **Bus factor** | How many people would have to leave before nobody knows a directory? |
64
+ | πŸ”— **Hidden coupling** | Which files keep changing in the same commits, even though nothing says they're related? |
65
+ | 🧊 **Stale code** | Which big files has nobody touched in a year? |
66
+ | πŸ‘» **Orphaned code** | Which files were mostly written by someone who is no longer active? |
67
+ | πŸ‘₯ **Contributors** | Who did the work in this time range? |
68
+
69
+ ## Usage
70
+
71
+ ```bash
72
+ git xray # whole history of the current repo
73
+ git xray --since "6 months ago" # recent activity only
74
+ git xray src/ lib/ # limit to some paths
75
+ git xray -n 25 # show 25 rows per section
76
+ git xray --depth 2 # bus factor per src/foo instead of src/
77
+ git xray -x "*.generated.ts" # extra excludes (repeatable)
78
+ git xray -C ~/code/other-repo # analyse another repo
79
+ ```
80
+
81
+ ### Output formats
82
+
83
+ ```bash
84
+ git xray --md > XRAY.md # Markdown: paste into a PR, wiki or issue
85
+ git xray --json | jq '.hotspots' # JSON: build your own dashboards or CI checks
86
+ ```
87
+
88
+ <details>
89
+ <summary>All options</summary>
90
+
91
+ ```text
92
+ usage: git-xray [-h] [-C DIR] [--since WHEN] [-n TOP] [--depth DEPTH]
93
+ [--min-coupling N] [--stale-days N] [-x GLOB]
94
+ [--no-default-excludes] [--include-bots] [--json | --md]
95
+ [--color {auto,always,never}] [-V]
96
+ [paths ...]
97
+ ```
98
+
99
+ | Option | Default | Meaning |
100
+ |---|---|---|
101
+ | `--since WHEN` | all history | Only commits newer than `WHEN` (anything `git log --since` accepts) |
102
+ | `-n, --top` | 10 | Rows per section |
103
+ | `--depth` | 1 | Directory depth used for bus-factor grouping |
104
+ | `--min-coupling` | 5 | Minimum shared commits before a pair is reported |
105
+ | `--stale-days` | 365 | Days without change before a file counts as stale / an author as inactive |
106
+ | `-x, --exclude` | | Glob to skip, repeatable |
107
+ | `--no-default-excludes` | | Keep lockfiles, `vendor/`, `dist/`, changelogs, minified files… |
108
+ | `--include-bots` | | Count dependabot, renovate and other bots |
109
+ | `--color` | auto | Respects `NO_COLOR` and `FORCE_COLOR` |
110
+ | `--icons` | auto | `emoji`, `plain` (no emoji) or `ascii`. Also `GIT_XRAY_ICONS` |
111
+
112
+ </details>
113
+
114
+ ## How the numbers are computed
115
+
116
+ - **Hotspot score** = `commits / max_commits Γ— log(loc) / log(max_loc)`. Change frequency
117
+ matters most; size is log-scaled so one giant file does not drown out everything else.
118
+ - **Bus factor** = the smallest number of authors who together wrote more than 50% of the
119
+ changed lines in a directory.
120
+ - **Coupling degree** = `shared_commits / average(commits of A, commits of B)`. Commits
121
+ touching more than 30 files (mass renames, formatting) are ignored.
122
+ - **Orphaned** = the main author wrote at least 50% of the file and has made no commit in
123
+ `--stale-days`.
124
+ - Renames are followed (`git log -M`), so history survives `git mv`. Merge commits are skipped.
125
+ Author identities respect your `.mailmap`.
126
+
127
+ These are heuristics, not verdicts. A hotspot can be a healthy, central module; the
128
+ point is to know *where to look*.
129
+
130
+ ## FAQ
131
+
132
+ **Is it fast on big repos?** It runs `git log` once and parses it in a single pass.
133
+ Most repos take a second or two. On huge monorepos, narrow it down with `--since` or a path.
134
+
135
+ **Does it send my code anywhere?** No. It runs `git` locally and prints to your terminal.
136
+
137
+ **I see boxes, garbled symbols or broken columns.** git-xray picks a glyph set
138
+ from your terminal. In Japanese, Chinese and Korean locales it uses plain ASCII,
139
+ because those terminals draw box and block characters double-wide. Some other
140
+ terminals still can't draw emoji. Use
141
+ `git xray --icons plain` (no emoji) or `--icons ascii`, or set it once with
142
+ `export GIT_XRAY_ICONS=plain` (PowerShell: `$env:GIT_XRAY_ICONS="plain"`).
143
+
144
+ **Why `git xray` and not `git-xray`?** Both work. git treats any `git-<name>`
145
+ executable on your `PATH` as a subcommand.
146
+
147
+ ## Contributing
148
+
149
+ Issues and PRs are welcome! Ideas we would love help with:
150
+ an HTML report, `--fail-on` thresholds for CI, and per-author knowledge maps.
151
+
152
+ ```bash
153
+ git clone https://github.com/ckh0at/git-xray && cd git-xray
154
+ python -m venv .venv && .venv/bin/pip install -e . pytest
155
+ .venv/bin/pytest
156
+ ```
157
+
158
+ ## License
159
+
160
+ MIT
@@ -0,0 +1,142 @@
1
+ <div align="center">
2
+
3
+ # git-xray 🩻
4
+
5
+ **X-ray any git repository in one command.**
6
+ Find the code that hurts: hotspots, bus factor, hidden coupling, stale and orphaned files.
7
+
8
+ [![PyPI](https://img.shields.io/pypi/v/git-xray-tool.svg)](https://pypi.org/project/git-xray-tool/)
9
+ [![Python](https://img.shields.io/pypi/pyversions/git-xray-tool.svg)](https://pypi.org/project/git-xray-tool/)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
11
+
12
+ <img src="https://raw.githubusercontent.com/ckh0at/git-xray/main/docs/demo.svg" alt="git-xray running on the Flask repository" width="820">
13
+
14
+ </div>
15
+
16
+ ```bash
17
+ pipx install git-xray-tool # or: pip install git-xray-tool
18
+ # one-off run: uvx --from git-xray-tool git-xray
19
+ cd your-repo
20
+ git xray
21
+ ```
22
+
23
+ The package is called `git-xray-tool` on PyPI; the command is `git-xray`, or just
24
+ `git xray`. No config, no server, no dependencies. Pure Python and `git`. It analyses Flask's
25
+ 3,800 commits in **under a second**.
26
+
27
+ ---
28
+
29
+ ## Why?
30
+
31
+ Your git history already knows where the problems are. The files that change
32
+ all the time *and* are large are where bugs pile up and velocity goes to die.
33
+ Directories that only one person understands are a risk. Files that always change
34
+ together hint at a missing abstraction.
35
+
36
+ Tools like [code-maat](https://github.com/adamtornhill/code-maat) pioneered this
37
+ analysis (see *Your Code as a Crime Scene*), but they need a JVM, a log export
38
+ step and a spreadsheet. `git-xray` gives you the answers in one command.
39
+
40
+ ## What it shows
41
+
42
+ | Section | Question it answers |
43
+ |---|---|
44
+ | πŸ”₯ **Hotspots** | Which files change most often *and* are big? Your best refactoring targets. |
45
+ | 🚌 **Bus factor** | How many people would have to leave before nobody knows a directory? |
46
+ | πŸ”— **Hidden coupling** | Which files keep changing in the same commits, even though nothing says they're related? |
47
+ | 🧊 **Stale code** | Which big files has nobody touched in a year? |
48
+ | πŸ‘» **Orphaned code** | Which files were mostly written by someone who is no longer active? |
49
+ | πŸ‘₯ **Contributors** | Who did the work in this time range? |
50
+
51
+ ## Usage
52
+
53
+ ```bash
54
+ git xray # whole history of the current repo
55
+ git xray --since "6 months ago" # recent activity only
56
+ git xray src/ lib/ # limit to some paths
57
+ git xray -n 25 # show 25 rows per section
58
+ git xray --depth 2 # bus factor per src/foo instead of src/
59
+ git xray -x "*.generated.ts" # extra excludes (repeatable)
60
+ git xray -C ~/code/other-repo # analyse another repo
61
+ ```
62
+
63
+ ### Output formats
64
+
65
+ ```bash
66
+ git xray --md > XRAY.md # Markdown: paste into a PR, wiki or issue
67
+ git xray --json | jq '.hotspots' # JSON: build your own dashboards or CI checks
68
+ ```
69
+
70
+ <details>
71
+ <summary>All options</summary>
72
+
73
+ ```text
74
+ usage: git-xray [-h] [-C DIR] [--since WHEN] [-n TOP] [--depth DEPTH]
75
+ [--min-coupling N] [--stale-days N] [-x GLOB]
76
+ [--no-default-excludes] [--include-bots] [--json | --md]
77
+ [--color {auto,always,never}] [-V]
78
+ [paths ...]
79
+ ```
80
+
81
+ | Option | Default | Meaning |
82
+ |---|---|---|
83
+ | `--since WHEN` | all history | Only commits newer than `WHEN` (anything `git log --since` accepts) |
84
+ | `-n, --top` | 10 | Rows per section |
85
+ | `--depth` | 1 | Directory depth used for bus-factor grouping |
86
+ | `--min-coupling` | 5 | Minimum shared commits before a pair is reported |
87
+ | `--stale-days` | 365 | Days without change before a file counts as stale / an author as inactive |
88
+ | `-x, --exclude` | | Glob to skip, repeatable |
89
+ | `--no-default-excludes` | | Keep lockfiles, `vendor/`, `dist/`, changelogs, minified files… |
90
+ | `--include-bots` | | Count dependabot, renovate and other bots |
91
+ | `--color` | auto | Respects `NO_COLOR` and `FORCE_COLOR` |
92
+ | `--icons` | auto | `emoji`, `plain` (no emoji) or `ascii`. Also `GIT_XRAY_ICONS` |
93
+
94
+ </details>
95
+
96
+ ## How the numbers are computed
97
+
98
+ - **Hotspot score** = `commits / max_commits Γ— log(loc) / log(max_loc)`. Change frequency
99
+ matters most; size is log-scaled so one giant file does not drown out everything else.
100
+ - **Bus factor** = the smallest number of authors who together wrote more than 50% of the
101
+ changed lines in a directory.
102
+ - **Coupling degree** = `shared_commits / average(commits of A, commits of B)`. Commits
103
+ touching more than 30 files (mass renames, formatting) are ignored.
104
+ - **Orphaned** = the main author wrote at least 50% of the file and has made no commit in
105
+ `--stale-days`.
106
+ - Renames are followed (`git log -M`), so history survives `git mv`. Merge commits are skipped.
107
+ Author identities respect your `.mailmap`.
108
+
109
+ These are heuristics, not verdicts. A hotspot can be a healthy, central module; the
110
+ point is to know *where to look*.
111
+
112
+ ## FAQ
113
+
114
+ **Is it fast on big repos?** It runs `git log` once and parses it in a single pass.
115
+ Most repos take a second or two. On huge monorepos, narrow it down with `--since` or a path.
116
+
117
+ **Does it send my code anywhere?** No. It runs `git` locally and prints to your terminal.
118
+
119
+ **I see boxes, garbled symbols or broken columns.** git-xray picks a glyph set
120
+ from your terminal. In Japanese, Chinese and Korean locales it uses plain ASCII,
121
+ because those terminals draw box and block characters double-wide. Some other
122
+ terminals still can't draw emoji. Use
123
+ `git xray --icons plain` (no emoji) or `--icons ascii`, or set it once with
124
+ `export GIT_XRAY_ICONS=plain` (PowerShell: `$env:GIT_XRAY_ICONS="plain"`).
125
+
126
+ **Why `git xray` and not `git-xray`?** Both work. git treats any `git-<name>`
127
+ executable on your `PATH` as a subcommand.
128
+
129
+ ## Contributing
130
+
131
+ Issues and PRs are welcome! Ideas we would love help with:
132
+ an HTML report, `--fail-on` thresholds for CI, and per-author knowledge maps.
133
+
134
+ ```bash
135
+ git clone https://github.com/ckh0at/git-xray && cd git-xray
136
+ python -m venv .venv && .venv/bin/pip install -e . pytest
137
+ .venv/bin/pytest
138
+ ```
139
+
140
+ ## License
141
+
142
+ MIT
@@ -0,0 +1,37 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "git-xray-tool"
7
+ dynamic = ["version"]
8
+ description = "X-ray any git repo in one command: hotspots, bus factor, hidden coupling, stale code. Zero dependencies."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.9"
12
+ keywords = ["git", "code-quality", "technical-debt", "hotspots", "bus-factor", "cli", "code-analysis"]
13
+ classifiers = [
14
+ "Environment :: Console",
15
+ "Intended Audience :: Developers",
16
+ "Programming Language :: Python :: 3",
17
+ "Topic :: Software Development :: Quality Assurance",
18
+ "Topic :: Software Development :: Version Control :: Git",
19
+ ]
20
+ dependencies = []
21
+
22
+ [project.urls]
23
+ Homepage = "https://github.com/ckh0at/git-xray"
24
+ Source = "https://github.com/ckh0at/git-xray"
25
+ Issues = "https://github.com/ckh0at/git-xray/issues"
26
+
27
+ [project.scripts]
28
+ git-xray = "git_xray.cli:main"
29
+
30
+ [tool.hatch.build.targets.wheel]
31
+ packages = ["src/git_xray"]
32
+
33
+ [tool.hatch.build.targets.sdist]
34
+ include = ["src/", "tests/", "README.md", "LICENSE", "pyproject.toml"]
35
+
36
+ [tool.hatch.version]
37
+ path = "src/git_xray/__init__.py"
@@ -0,0 +1,3 @@
1
+ """git-xray: one-command insight into any git repository's history."""
2
+
3
+ __version__ = "0.1.0"
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())