git-hot 0.6__tar.gz → 0.9__tar.gz

git_hot-0.9/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: git-hot
+Version: 0.9
+Summary: Git extension for reporting source code line lifetime and churn
+Author: Diomidis Spinellis
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/dspinellis/code-lifetime
+Project-URL: Issues, https://github.com/dspinellis/code-lifetime/issues
+Keywords: git,churn,software-evolution,repository-mining
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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 :: Rust
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# git-hot
+
+`git-hot` is a Git extension that reports how ``hot'' (often-changing)
+the current lines or files in a repository are.
+It derives line lifetime and churn information from Git history,
+then highlights files and lines that have changed often or recently.
+
+Install the package and run it as either:
+
+```sh
+git hot
+git-hot
+```
+
+The package installs two commands:
+
+- `git-hot`, the Git extension command; [manual page](https://dspinellis.github.io/manview/?src=https%3A%2F%2Fraw.githubusercontent.com%2Fdspinellis%2Fgit-hot%2Frefs%2Fheads%2Fmaster%2Fgit-hot.1&name=git-hot&link=https%3A%2F%2Fgithub.com%2Fdspinellis%2Fgit-hot).
+- `daglp`, a helper, written in Rust, used to compute the longest path
+  through the Git commit DAG; [manual page](https://dspinellis.github.io/manview/?src=https%3A%2F%2Fraw.githubusercontent.com%2Fdspinellis%2Fgit-hot%2Frefs%2Fheads%2Fmaster%2Fdaglp.1&name=daglp&link=https%3A%2F%2Fgithub.com%2Fdspinellis%2Fgit-hot).
+
+
+## Installation
+
+For an isolated command installation:
+
+```sh
+uv tool install git-hot
+```
+
+For installation in an active virtual environment:
+
+```sh
+uv pip install git-hot
+```
+
+With `pip`:
+
+```sh
+python -m pip install git-hot
+```
+
+After installation, ensure the installation's script directory is on `PATH` so
+Git can find `git-hot` and you can invoke it as `git hot`.
+
+## Usage
+
+Show hot files in the current repository:
+
+```sh
+git hot
+```
+
+Show hot files at a specific revision:
+
+```sh
+git hot HEAD
+```
+
+Show line-level churn for one file:
+
+```sh
+git hot -- src/main.py
+```
+
+Show line ages and birth commits for one file:
+
+```sh
+git hot -q --format '{days(age)} {hash[:7]} {line}' -- src/main.py
+```
+
+Reconstruct all source files with churn prefixes below a directory:
+
+```sh
+git hot --dir hot-tree HEAD
+```
+
+## Output
+
+Without a path, `git hot` prints one line per current source file, sorted by
+path.  The default columns are:
+
+- maximum live-line churn in the file
+- median changed-line lifetime in days
+- median live-line age in days
+- repository path
+
+With a path, `git hot` prints the reconstructed contents of that file.  By
+default each line is preceded by its churn count.
+
+Use `--color always` or `--color never` to control color output.  Automatic
+coloring can rank lines by `churn`, `age`, or `lifetime`:
+
+```sh
+git hot --color always --color-domain age -- src/main.py
+```
+
+## Formatting
+
+Use `--format` to customize file or line output with a restricted Python
+f-string expression.  The available fields depend on whether repository-wide
+file metrics or selected-path line output is being produced.
+
+Examples:
+
+```sh
+git hot --format '{max(churn):5d} {days(median(line_age)):5d} {path}'
+git hot --format '{days(age)} {hash[:7]} {line}' -- src/main.py
+```
+
+Common helpers include `days`, `max`, `min`, `median`, `mean`,
+`quartile_rank`, `color`, and `color_reset`.
+
+For the complete list of format fields and options, see:
+
+```sh
+man git-hot
+```
+
+or read the [git-hot manual page](https://dspinellis.github.io/manview/?src=https%3A%2F%2Fraw.githubusercontent.com%2Fdspinellis%2Fgit-hot%2Frefs%2Fheads%2Fmaster%2Fgit-hot.1&name=git-hot&link=https%3A%2F%2Fgithub.com%2Fdspinellis%2Fgit-hot).
+
+## Requirements
+
+`git-hot` expects to run inside a Git repository.
+Alternatively, the Git repository can be passed to the `git` command
+using the `--git-dir` option.
+Internally, it invokes Git commands such
+as `git log`, `git show`, and `git diff`, and uses rename and copy detection.
+
+Binary files and deleted files are skipped in file-metric output.
+
+## Installing From Source
+
+Building from source requires Python 3.10 or later and a Rust toolchain with
+`rustc`, because `daglp` is compiled during installation.
+
+```sh
+uv sync --group dev
+uv pip install -e .
+uv run python -m unittest discover -s . -p 'test*.py'
+uv run --group dev ruff check .
+```
+
+Build a source distribution locally with:
+
+```sh
+uv build --sdist
+```
+
+Platform wheels are built in CI through `cibuildwheel`.
+
+## Research Tools
+
+This repository also contains research-oriented source tools used for
+fine-grained code lifetime analysis, including `lifetime.py`, `difflog.sh`,
+`tokenize.pl`, and the top-level `daglp.rs`.  They are kept in source form for
+reproducibility and experimentation, but the installable package exposes only
+`git-hot` and `daglp`.
+
+For historical and research context, see [lifetime-tools.md](https://github.com/dspinellis/git-hot/blob/master/lifetime-tools.md).
+
+## License
+
+`git-hot` is distributed under the Apache License 2.0.  See `LICENSE`.

git_hot-0.9/README.md

@@ -0,0 +1,163 @@
+# git-hot
+
+`git-hot` is a Git extension that reports how ``hot'' (often-changing)
+the current lines or files in a repository are.
+It derives line lifetime and churn information from Git history,
+then highlights files and lines that have changed often or recently.
+
+Install the package and run it as either:
+
+```sh
+git hot
+git-hot
+```
+
+The package installs two commands:
+
+- `git-hot`, the Git extension command; [manual page](https://dspinellis.github.io/manview/?src=https%3A%2F%2Fraw.githubusercontent.com%2Fdspinellis%2Fgit-hot%2Frefs%2Fheads%2Fmaster%2Fgit-hot.1&name=git-hot&link=https%3A%2F%2Fgithub.com%2Fdspinellis%2Fgit-hot).
+- `daglp`, a helper, written in Rust, used to compute the longest path
+  through the Git commit DAG; [manual page](https://dspinellis.github.io/manview/?src=https%3A%2F%2Fraw.githubusercontent.com%2Fdspinellis%2Fgit-hot%2Frefs%2Fheads%2Fmaster%2Fdaglp.1&name=daglp&link=https%3A%2F%2Fgithub.com%2Fdspinellis%2Fgit-hot).
+
+
+## Installation
+
+For an isolated command installation:
+
+```sh
+uv tool install git-hot
+```
+
+For installation in an active virtual environment:
+
+```sh
+uv pip install git-hot
+```
+
+With `pip`:
+
+```sh
+python -m pip install git-hot
+```
+
+After installation, ensure the installation's script directory is on `PATH` so
+Git can find `git-hot` and you can invoke it as `git hot`.
+
+## Usage
+
+Show hot files in the current repository:
+
+```sh
+git hot
+```
+
+Show hot files at a specific revision:
+
+```sh
+git hot HEAD
+```
+
+Show line-level churn for one file:
+
+```sh
+git hot -- src/main.py
+```
+
+Show line ages and birth commits for one file:
+
+```sh
+git hot -q --format '{days(age)} {hash[:7]} {line}' -- src/main.py
+```
+
+Reconstruct all source files with churn prefixes below a directory:
+
+```sh
+git hot --dir hot-tree HEAD
+```
+
+## Output
+
+Without a path, `git hot` prints one line per current source file, sorted by
+path.  The default columns are:
+
+- maximum live-line churn in the file
+- median changed-line lifetime in days
+- median live-line age in days
+- repository path
+
+With a path, `git hot` prints the reconstructed contents of that file.  By
+default each line is preceded by its churn count.
+
+Use `--color always` or `--color never` to control color output.  Automatic
+coloring can rank lines by `churn`, `age`, or `lifetime`:
+
+```sh
+git hot --color always --color-domain age -- src/main.py
+```
+
+## Formatting
+
+Use `--format` to customize file or line output with a restricted Python
+f-string expression.  The available fields depend on whether repository-wide
+file metrics or selected-path line output is being produced.
+
+Examples:
+
+```sh
+git hot --format '{max(churn):5d} {days(median(line_age)):5d} {path}'
+git hot --format '{days(age)} {hash[:7]} {line}' -- src/main.py
+```
+
+Common helpers include `days`, `max`, `min`, `median`, `mean`,
+`quartile_rank`, `color`, and `color_reset`.
+
+For the complete list of format fields and options, see:
+
+```sh
+man git-hot
+```
+
+or read the [git-hot manual page](https://dspinellis.github.io/manview/?src=https%3A%2F%2Fraw.githubusercontent.com%2Fdspinellis%2Fgit-hot%2Frefs%2Fheads%2Fmaster%2Fgit-hot.1&name=git-hot&link=https%3A%2F%2Fgithub.com%2Fdspinellis%2Fgit-hot).
+
+## Requirements
+
+`git-hot` expects to run inside a Git repository.
+Alternatively, the Git repository can be passed to the `git` command
+using the `--git-dir` option.
+Internally, it invokes Git commands such
+as `git log`, `git show`, and `git diff`, and uses rename and copy detection.
+
+Binary files and deleted files are skipped in file-metric output.
+
+## Installing From Source
+
+Building from source requires Python 3.10 or later and a Rust toolchain with
+`rustc`, because `daglp` is compiled during installation.
+
+```sh
+uv sync --group dev
+uv pip install -e .
+uv run python -m unittest discover -s . -p 'test*.py'
+uv run --group dev ruff check .
+```
+
+Build a source distribution locally with:
+
+```sh
+uv build --sdist
+```
+
+Platform wheels are built in CI through `cibuildwheel`.
+
+## Research Tools
+
+This repository also contains research-oriented source tools used for
+fine-grained code lifetime analysis, including `lifetime.py`, `difflog.sh`,
+`tokenize.pl`, and the top-level `daglp.rs`.  They are kept in source form for
+reproducibility and experimentation, but the installable package exposes only
+`git-hot` and `daglp`.
+
+For historical and research context, see [lifetime-tools.md](https://github.com/dspinellis/git-hot/blob/master/lifetime-tools.md).
+
+## License
+
+`git-hot` is distributed under the Apache License 2.0.  See `LICENSE`.

git_hot-0.9/daglp.1

@@ -0,0 +1,107 @@
+.\" Copyright 1996-2026 Diomidis Spinellis
+.\"
+.\" Licensed under the Apache License, Version 2.0 (the "License");
+.\" you may not use this file except in compliance with the License.
+.\" You may obtain a copy of the License at
+.\"
+.\" http://www.apache.org/licenses/LICENSE-2.0
+.\"
+.\" Unless required by applicable law or agreed to in writing, software
+.\" distributed under the License is distributed on an "AS IS" BASIS,
+.\" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.\" See the License for the specific language governing permissions and
+.\" limitations under the License.
+.\"
+.TH DAGLP 1 "May 2026" "git-hot" "User Commands"
+.SH NAME
+daglp \- print the longest path through a directed acyclic graph
+.SH SYNOPSIS
+.SY daglp
+.RI [ file ]
+.YS
+.SH DESCRIPTION
+.B daglp
+reads a directed acyclic graph whose vertices are listed in topological order
+and prints the longest path from the graph's oldest/root side to its
+newest/end side.
+It is primarily used by
+.BR git-hot (1)
+to simplify Git history to a single path for code lifetime analysis.
+.PP
+Input is read from
+.I file
+when one argument is supplied.
+Otherwise input is read from standard input.
+.PP
+Each non-empty input line has the form:
+.PP
+.EX
+node identifier parent...
+.EE
+.PP
+The first field is the node name.
+The second field is an identifier that is printed with the node in output.
+All remaining fields name parent nodes.
+.PP
+For Git history processing, input is normally produced with:
+.PP
+.EX
+git log --topo-order --pretty=format:'%H %at %P'
+.EE
+.PP
+where the node is the commit hash, the identifier is the commit timestamp, and
+the remaining fields are parent commit hashes.
+.SH INPUT ORDER
+.B daglp
+expects the input to be topologically sorted from newest node to oldest node,
+as produced by
+.BR git-log (1)
+with
+.BR --topo-order .
+The program processes that order in reverse when calculating path lengths, so
+parents are considered before their children without recursion.
+.SH OUTPUT
+.B daglp
+prints the selected longest path one node per line, from oldest to newest.
+Each output line has the form:
+.PP
+.EX
+node identifier
+.EE
+.PP
+When multiple parent choices have the same path length, the first encountered
+choice is retained.
+For Git input this preserves the original first-parent tie behavior.
+.SH EXAMPLES
+.PP
+Print the longest path through the current repository's commit DAG:
+.PP
+.EX
+$ git log --topo-order --pretty=format:'%H %at %P' | daglp
+13af1997c687bb4462f97ab512e51e8c072a2858 1370686723
+d8e85967adc0b188a49117b5db4f10cc6c7c36cb 1370688578
+27a8ec806f16ae66a7eaa8563220f600c99b9ab9 1370688605
+.EE
+.PP
+Read graph input from a file:
+.PP
+.EX
+$ daglp commit-graph.txt
+.EE
+.SH EXIT STATUS
+.TP
+.B 0
+Successful completion.
+.TP
+.B 1
+An input file could not be opened, or an I/O error occurred while reading
+input.
+.SH NOTES
+.B daglp
+does not validate that the input graph is acyclic beyond relying on the
+topological input order.
+.PP
+Empty input produces no output and exits successfully.
+.SH SEE ALSO
+.BR git-hot (1),
+.BR git-log (1)

{git_hot-0.6 → git_hot-0.9}/git-hot.1

@@ -83,26 +83,26 @@ reports progress on standard error.
 When standard output is a terminal, output is sent through the configured Git
 pager.
 .SH OPTIONS
-.TP
+.TP 25
 .B \-h, \-\-help
 Show usage information and exit.
-.TP
+.TP 25
 .BI "\-d " dir ", \-\-dir " dir
 Reconstruct source files below
 .I dir
 with each line preceded by its churn count.
 This option also leaves the normal selected output behavior in effect.
-.TP
+.TP 25
 .BI "\-\-format " format
 Format file or line output using a restricted Python f-string expression.
 The available fields depend on whether
 .B git hot
 is producing file metrics or reconstructed line output; see
 .BR "FORMAT STRINGS" .
-.TP
+.TP 25
 .B \-q, \-\-quiet
 Suppress progress output.
-.TP
+.TP 25
 .BI "\-D " opts ", \-\-debug " opts
 Enable debugging output selected by letters in
 .IR opts .
@@ -127,7 +127,7 @@ to show splicing operations,
 to reconstruct repository contents, and
 .B @
 to show range headers.
-.TP
+.TP 25
 .BI "\-\-color " when
 Control ANSI color output.
 .I when
@@ -137,7 +137,7 @@ or
 .BR never .
 When this option is omitted, color is enabled only when standard output is a
 terminal.
-.TP
+.TP 25
 .BI "\-\-color-domain " domain
 Choose the metric used for automatic color ranking.
 .I domain
@@ -174,20 +174,19 @@ The default repository-wide output is equivalent to the format
 .EE
 .PP
 The columns are:
-.TP
+.TP 30
 .B max churn
 The maximum number of changes recorded for any live line in the file.
-.TP
+.TP 30
 .B median changed lifetime
 The median time, in rounded integer days, between changes of lines in the file.
-.TP
+.TP 30
 .B median line age
 The median age, in rounded integer days, of the file's live lines at the
 analyzed revision.
-.TP
+.TP 30
 .B path
 The repository path.
-.SS Path Output
 For a selected
 .IR path ,
 the default output is equivalent to:

{git_hot-0.6 → git_hot-0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "git-hot"
-version = "0.6"
+version = "0.9"
 description = "Git extension for reporting source code line lifetime and churn"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ license = "Apache-2.0"
 authors = [{ name = "Diomidis Spinellis" }]
 keywords = ["git", "churn", "software-evolution", "repository-mining"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
@@ -48,7 +48,7 @@ where = ["src"]
 git_hot = ["daglp.rs"]
 
 [tool.setuptools.data-files]
-"share/man/man1" = ["git-hot.1"]
+"share/man/man1" = ["git-hot.1", "daglp.1"]
 
 [tool.ruff]
 line-length = 100