git-hot 0.6__py3-none-win_amd64.whl

git_hot-0.6.data/data/share/man/man1/git-hot.1

@@ -0,0 +1,333 @@
+.\" 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 GIT-HOT 1 "May 2026" "git-hot 0.1" "Git Manual"
+.SH NAME
+git-hot \- report Git file and line lifetime churn
+.SH SYNOPSIS
+.SY git
+.B hot
+.RB [ \-h ]
+.RB [ \-d
+.IR dir ]
+.RB [ \-q ]
+.RB [ \-D
+.IR opts ]
+.RB [ \-\-color
+.BR always | never ]
+.RB [ \-\-color-domain
+.BR churn | age | lifetime ]
+.RB [ \-\-format
+.IR format ]
+.RI [ ref ]
+.RI [[ \-\- ]
+.IR path ]
+.YS
+.SY git-hot
+.RB [ \-h ]
+.RB [ \-d
+.IR dir ]
+.RB [ \-q ]
+.RB [ \-D
+.IR opts ]
+.RB [ \-\-color
+.BR always | never ]
+.RB [ \-\-color-domain
+.BR churn | age | lifetime ]
+.RB [ \-\-format
+.IR format ]
+.RI [ ref ]
+.RI [[ \-\- ]
+.IR path ]
+.YS
+.SH DESCRIPTION
+.B git hot
+is a Git extension that reports how "hot" the current files or lines in a
+repository are, using line lifetime and churn information derived from Git
+history.
+It walks the repository's topologically ordered longest commit path, streams
+zero-context diffs through the code lifetime processor, and reports metrics
+for the files or lines that are alive at the selected revision.
+.PP
+When invoked without
+.IR path ,
+.B git hot
+prints one line per current source file, sorted by path.
+The default columns are the maximum line churn in the file, the median changed
+line lifetime in days, the median live line age in days, and the path.
+.PP
+When
+.I path
+is specified,
+.B git hot
+prints the reconstructed contents of that file, with each line preceded by its
+churn count by default.
+The path form follows Git's usual revision/path convention; use
+.B \-\-
+to disambiguate a path from a revision.
+.PP
+Unless quiet mode is selected,
+.B git hot
+reports progress on standard error.
+When standard output is a terminal, output is sent through the configured Git
+pager.
+.SH OPTIONS
+.TP
+.B \-h, \-\-help
+Show usage information and exit.
+.TP
+.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
+.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
+.B \-q, \-\-quiet
+Suppress progress output.
+.TP
+.BI "\-D " opts ", \-\-debug " opts
+Enable debugging output selected by letters in
+.IR opts .
+Useful flags include
+.B g
+to show Git invocations,
+.B H
+to show commit headers,
+.B D
+to show diff headers,
+.B E
+to show diff extended headers,
+.B L
+to show line-of-code processing,
+.B P
+to show change-set pushes,
+.B C
+to show commit-set changes,
+.B S
+to show splicing operations,
+.B R
+to reconstruct repository contents, and
+.B @
+to show range headers.
+.TP
+.BI "\-\-color " when
+Control ANSI color output.
+.I when
+must be
+.B always
+or
+.BR never .
+When this option is omitted, color is enabled only when standard output is a
+terminal.
+.TP
+.BI "\-\-color-domain " domain
+Choose the metric used for automatic color ranking.
+.I domain
+must be
+.BR churn ,
+.BR age ,
+or
+.BR lifetime .
+The default is
+.BR churn .
+.SH ARGUMENTS
+.TP
+.I ref
+Git revision or reference to analyze.
+If omitted,
+.B git hot
+uses the repository's default revision selection as provided by
+.BR "git log" .
+.TP
+.I path
+Limit analysis to one path and print reconstructed line details for that path.
+At most one path may be specified.
+Use
+.B \-\-
+before the path when the path could be parsed as a revision, or when no
+.I ref
+is supplied.
+.SH OUTPUT
+.SS File Metrics
+The default repository-wide output is equivalent to the format
+.PP
+.EX
+{max(churn):5d} {days(median(changed_lifetime)):5d} {days(median(line_age)):5d} {path}
+.EE
+.PP
+The columns are:
+.TP
+.B max churn
+The maximum number of changes recorded for any live line in the file.
+.TP
+.B median changed lifetime
+The median time, in rounded integer days, between changes of lines in the file.
+.TP
+.B median line age
+The median age, in rounded integer days, of the file's live lines at the
+analyzed revision.
+.TP
+.B path
+The repository path.
+.SS Path Output
+For a selected
+.IR path ,
+the default output is equivalent to:
+.PP
+.EX
+{churn:>{5}d}  {line}
+.EE
+.PP
+Each output line represents one live reconstructed line from the selected file.
+.SH FORMAT STRINGS
+.B git hot
+evaluates
+.B \-\-format
+as a Python f-string with a restricted set of names.
+The same option formats file-metric output when no path is selected, and line
+output when a path is selected.
+.PP
+Common helper names are:
+.BR days ,
+.BR max ,
+.BR min ,
+.BR median ,
+.BR mean ,
+.BR quartile_rank ,
+.BR color ,
+.BR color_reset ,
+.BR list ,
+and
+.BR map .
+.PP
+File-metric format strings may use:
+.BR path ,
+.BR churn ,
+.BR changed_lifetime ,
+.BR change_lifetime ,
+.BR line_age ,
+.BR line_churns ,
+.BR line_change_lifetimes ,
+.BR line_ages ,
+.BR file_line_churns ,
+.BR file_line_change_lifetimes ,
+.BR file_line_ages ,
+.BR repo_line_churns ,
+.BR repo_line_change_lifetimes ,
+and
+.BR repo_line_ages .
+.PP
+Line format strings may use:
+.BR churn ,
+.BR age ,
+.BR hash ,
+.BR change_lifetimes ,
+.BR lifetime_median ,
+.BR lifetime_mean ,
+.BR birthtime ,
+.BR line ,
+.BR file_line_churns ,
+.BR file_line_ages ,
+.BR file_line_change_lifetimes ,
+.BR repo_line_churns ,
+.BR repo_line_ages ,
+and
+.BR repo_line_change_lifetimes .
+.PP
+If the format string calls
+.BR color() ,
+.B git hot
+assumes color is handled explicitly and appends a reset sequence when color is
+enabled.
+Otherwise, enabled color is applied automatically using the selected
+.BR \-\-color-domain .
+.SH EXAMPLES
+.PP
+Show hot files in the current repository:
+.EX
+$ git hot
+.EE
+.PP
+Show hot files at
+.BR HEAD :
+.EX
+$ git hot HEAD
+.EE
+.PP
+Show line churn for one file:
+.EX
+$ git hot -- src/main.py
+.EE
+.PP
+Show line ages and birth commits for one file:
+.EX
+$ git hot -q --format '{days(age)} {hash[:7]} {line}' -- src/main.py
+.EE
+.PP
+Reconstruct all source files with churn prefixes below
+.BR hot-tree :
+.EX
+$ git hot --dir hot-tree HEAD
+.EE
+.SH FILES
+.TP
+.I git-hot
+The executable Git extension.
+When installed on
+.BR PATH ,
+Git can invoke it as
+.BR "git hot" .
+.TP
+.I daglp
+Helper program used to compute the longest path through the repository commit
+DAG.
+.SH NOTES
+.B git hot
+expects to run inside a Git repository and requires
+.B daglp
+to be available on
+.BR PATH .
+It uses Git commands including
+.BR "git log" ,
+.BR "git show" ,
+and
+.BR "git diff" ,
+with rename and copy detection enabled.
+.PP
+Only source-code files are reported in file-metric output.
+Binary files and deleted files are skipped.
+.SH EXIT STATUS
+.TP
+.B 0
+Successful completion.
+.TP
+.B 1
+A processing error occurred, such as an invalid output format or a failed
+helper command.
+.TP
+.B 2
+Command-line usage error reported by the argument parser.
+.SH SEE ALSO
+.BR git (1),
+.BR git-log (1),
+.BR git-diff (1),
+.BR git-show (1),
+.BR less (1)

git_hot-0.6.data/purelib/git_hot/__init__.py

@@ -0,0 +1,5 @@
+"""Git extension for reporting source code line lifetime and churn."""
+
+from .lifetime import VERSION
+
+__all__ = ["VERSION"]

git_hot-0.6.data/purelib/git_hot/__main__.py

@@ -0,0 +1,8 @@
+"""Run the lifetime command as a module."""
+
+import sys
+
+from .lifetime import main
+
+if __name__ == "__main__":
+    sys.exit(main())

git_hot-0.6.data/purelib/git_hot/daglp.rs

@@ -0,0 +1,226 @@
+/*
+ * 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.
+ *
+ *
+ * Given as input a topologically sorted list of each commit's parents,
+ * output the longest path of the DAG from the beginning (the oldest commit)
+ * to the end (the newest one).
+ * See https://en.wikipedia.org/wiki/Longest_path_problem#Acyclic_graphs_and_critical_paths
+ * The input should come from
+ * git log --topo-order --pretty=format:'%H %at %P'
+ * The output is "SHA identifier" lines.
+ *
+ */
+
+use std::collections::HashMap;
+use std::env;
+use std::fs::File;
+use std::io::{self, BufRead, BufReader};
+use std::process;
+
+const DEBUG: bool = false;
+
+#[derive(Default)]
+struct Vertex {
+    name: String,
+    // Author/commit time, SHA, bug ids, or any other tracked commit element.
+    identifier: String,
+    // Longest path ending here; None means it has not yet been calculated.
+    max_length: Option<i32>,
+    // Parent commits of this commit.
+    edges: Vec<String>,
+    // The next vertex in the recorded longest path.
+    lp_from: Option<String>,
+}
+
+impl Vertex {
+    fn new(name: &str, identifier: &str) -> Self {
+        Self {
+            name: name.to_string(),
+            identifier: identifier.to_string(),
+            max_length: None,
+            edges: Vec::new(),
+            lp_from: None,
+        }
+    }
+}
+
+fn get_vertex<'a>(
+    vertices: &'a mut HashMap<String, Vertex>,
+    name: &str,
+    identifier: &str,
+) -> &'a mut Vertex {
+    // Return a node by name, adding it to the map if needed.
+    let vertex = vertices
+        .entry(name.to_string())
+        .or_insert_with(|| Vertex::new(name, identifier));
+    if !identifier.is_empty() {
+        vertex.identifier = identifier.to_string();
+    }
+    vertex
+}
+
+fn reader_from_args() -> Box<dyn BufRead> {
+    let args: Vec<String> = env::args().collect();
+    if args.len() == 2 {
+        match File::open(&args[1]) {
+            Ok(file) => Box::new(BufReader::new(file)),
+            Err(error) => {
+                eprintln!("{}: {error}", args[1]);
+                process::exit(1);
+            }
+        }
+    } else {
+        Box::new(BufReader::new(io::stdin()))
+    }
+}
+
+fn read_graph(
+    reader: Box<dyn BufRead>,
+) -> io::Result<(HashMap<String, Vertex>, Vec<String>, Option<String>)> {
+    let mut vertices = HashMap::new();
+    let mut order = Vec::new();
+    let mut end = None;
+
+    for line in reader.lines() {
+        let line = line?;
+        let mut parts = line.split_whitespace();
+        let Some(node_name) = parts.next() else {
+            continue;
+        };
+        let identifier = parts.next().unwrap_or("");
+
+        // Read node, adding it to the map if needed.
+        get_vertex(&mut vertices, node_name, identifier);
+        order.push(node_name.to_string());
+        if end.is_none() {
+            end = Some(node_name.to_string());
+        }
+
+        // Create edges from this commit to its parents.
+        for parent_name in parts {
+            if DEBUG {
+                eprintln!("{parent_name} parent of {node_name}");
+            }
+            get_vertex(&mut vertices, parent_name, "");
+            vertices
+                .get_mut(node_name)
+                .expect("current vertex exists")
+                .edges
+                .push(parent_name.to_string());
+        }
+    }
+
+    Ok((vertices, order, end))
+}
+
+fn calculate_max_lengths(vertices: &mut HashMap<String, Vertex>, order: &[String]) {
+    // Parent vertices that do not appear as full input lines are roots.
+    for vertex in vertices.values_mut() {
+        vertex.max_length = Some(0);
+    }
+
+    // Record the maximum path associated with each vertex.  The input is
+    // topologically sorted newest to oldest, so reverse order gives parents
+    // before children and avoids recursion over long commit histories.
+    for name in order.iter().rev() {
+        let edges = vertices
+            .get(name)
+            .map(|vertex| vertex.edges.clone())
+            .unwrap_or_default();
+        let max_path = edges
+            .iter()
+            .filter_map(|edge| vertices.get(edge).and_then(|vertex| vertex.max_length))
+            .max()
+            .unwrap_or(-1);
+        let length = max_path + 1;
+        if DEBUG {
+            eprintln!("max_length({name}) = {length}");
+        }
+        if let Some(vertex) = vertices.get_mut(name) {
+            vertex.max_length = Some(length);
+        }
+    }
+}
+
+fn mark_longest_path(
+    vertices: &mut HashMap<String, Vertex>,
+    order: &[String],
+    end: &str,
+) -> Option<String> {
+    // Calculate the maximum paths of all vertices.
+    calculate_max_lengths(vertices, order);
+
+    // Obtain and record the longest path.  The strict comparison preserves
+    // the original first-parent tie behavior.
+    let mut current = Some(end.to_string());
+    let mut start = Some(end.to_string());
+    while let Some(name) = current {
+        let edges = vertices
+            .get(&name)
+            .map(|vertex| vertex.edges.clone())
+            .unwrap_or_default();
+        let mut longest = None;
+        let mut longest_length = None;
+        for edge in edges {
+            let length = vertices.get(&edge).and_then(|vertex| vertex.max_length);
+            if longest.is_none() || length > longest_length {
+                longest = Some(edge);
+                longest_length = length;
+            }
+        }
+
+        if let Some(parent) = longest {
+            if let Some(vertex) = vertices.get_mut(&parent) {
+                vertex.lp_from = Some(name);
+            }
+            start = Some(parent.clone());
+            current = Some(parent);
+        } else {
+            current = None;
+        }
+    }
+
+    start
+}
+
+fn print_longest_path(vertices: &HashMap<String, Vertex>, start: Option<String>) {
+    // Display the longest path.
+    let mut current = start;
+    while let Some(name) = current {
+        let vertex = vertices.get(&name).expect("path vertex exists");
+        println!("{} {}", vertex.name, vertex.identifier);
+        current = vertex.lp_from.clone();
+    }
+}
+
+fn run() -> io::Result<()> {
+    let reader = reader_from_args();
+    let (mut vertices, order, end) = read_graph(reader)?;
+    let Some(end) = end else {
+        return Ok(());
+    };
+
+    let start = mark_longest_path(&mut vertices, &order, &end);
+    print_longest_path(&vertices, start);
+    Ok(())
+}
+
+fn main() {
+    if let Err(error) = run() {
+        eprintln!("{error}");
+        process::exit(1);
+    }
+}