From b3c5844cbc7018daa34183d94c030cc9fe781691 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Mon, 2 Jun 2025 06:17:59 +0200 Subject: [PATCH 1/5] Module documentation --- src/config.rs | 8 ++++++++ src/graph.rs | 17 +++++++++++++++++ src/lib.rs | 5 +++++ src/print/unicode.rs | 2 +- src/settings.rs | 12 ++++++++++++ 5 files changed, 43 insertions(+), 1 deletion(-) diff --git a/src/config.rs b/src/config.rs index 3fb14bf..b4fa77d 100644 --- a/src/config.rs +++ b/src/config.rs @@ -1,3 +1,11 @@ +//! Branching model configurations. +//! +//! In this module you will find functions to read and write branching model +//! configurations on disk. +//! +//! The [branching models][BranchSettingsDef] themselves are defined in +//! module [settings][super::settings] + use crate::settings::{BranchSettingsDef, RepoSettings}; use git2::Repository; use std::ffi::OsStr; diff --git a/src/graph.rs b/src/graph.rs index c658756..fecea3f 100644 --- a/src/graph.rs +++ b/src/graph.rs @@ -1,4 +1,21 @@ //! A graph structure representing the history of a Git repository. +//! +//! To generate a graph, call [GitGraph::new()]. +//! +//! ### Visualization of branches +//! git-graph uses the term *branch* a little different from how git uses it. +//! In git-lingo this means "a label on some commit", whereas in git-graph +//! it means "a path in the ancestor graph of a repository". Nodes are +//! commits, edges are directed from a child to its parents. +//! +//! In the text below, the term +//! - *git-branch* is a label on a commit. +//! - *branch* is the visualization of an ancestor path. +//! +//! git-graph visualizes branches as a vertical line. Only +//! the primary parent of a commit can be on the same branch as the +//! commit. Horizontal lines represent forks (multiple children) or +//! merges (multiple parents), and show the remaining parent relations. use crate::print::colors::to_terminal_color; use crate::settings::{BranchOrder, BranchSettings, MergePatterns, Settings}; diff --git a/src/lib.rs b/src/lib.rs index faf85fc..428d5bf 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,6 +1,11 @@ //! git-graph shows clear git graphs arranged for your branching model. //! //! It provides both a library and a command line tool. +//! +//! The main steps are: +//! 1. Read branching model configuration (See [config] and [settings]) +//! 2. Lay out the graph structure according to the branching model (See [graph]) +//! 3. Render the layout to text or SVG (See [mod@print]) use git2::Repository; use std::path::Path; diff --git a/src/print/unicode.rs b/src/print/unicode.rs index 73fd18f..60bca5c 100644 --- a/src/print/unicode.rs +++ b/src/print/unicode.rs @@ -1,4 +1,4 @@ -//! Create graphs in SVG format (Scalable Vector Graphics). +//! Create graphs in Unicode format with ANSI X3.64 / ISO 6429 colour codes use crate::graph::{CommitInfo, GitGraph, HeadInfo}; use crate::print::format::CommitFormat; diff --git a/src/settings.rs b/src/settings.rs index a2ee5ed..b4ef5bf 100644 --- a/src/settings.rs +++ b/src/settings.rs @@ -1,4 +1,16 @@ //! Graph generation settings. +//! +//! The settings control how a branching graph is layed out. +//! They are used in the [print][super::print] module when generating +//! a visualization and persisted to disk in the [config][super::config] module. +//! +//! These are the main structs +//! * [Settings] The main settings object, which contains: +//! * [CommitFormat] Format of the commit summary text to the right of the graph. +//! * [Characters] The symbols to use when rendering a graph as text. +//! * [BranchSettings] Control how a graph is formatted. +//! * [BranchOrder] Determines the left-to-right order of branches. +//! * [MergePatterns] Regex that extract branch names from a merge commit. use crate::print::format::CommitFormat; use regex::{Error, Regex}; From 0c51d0adc84e3c08a8d23ab11555643581d00c84 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Mon, 2 Jun 2025 07:06:48 +0200 Subject: [PATCH 2/5] Publish UnicodeGraphInfo --- src/print/unicode.rs | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/src/print/unicode.rs b/src/print/unicode.rs index 60bca5c..f45750f 100644 --- a/src/print/unicode.rs +++ b/src/print/unicode.rs @@ -33,7 +33,27 @@ const WHITE: u8 = 7; const HEAD_COLOR: u8 = 14; const HASH_COLOR: u8 = 11; -type UnicodeGraphInfo = (Vec, Vec, Vec); +/** +UnicodeGraphInfo is a type alias for a tuple containing three elements: +graph-lines, text-lines, start-row + +1. graph_lines: `Vec` - This represents the lines of the generated text-based graph + visualization. Each `String` in this vector corresponds to a single row of + the graph output, containing characters that form the visual representation + of the commit history (like lines, dots, and branch intersections). + +2. text_lines: `Vec`: This represents the lines of the commit messages or other + textual information associated with each commit in the graph. Each `String` + in this vector corresponds to a line of text that is displayed alongside + the graph. This can include commit hashes, author information, commit + messages, branch names, and tags, depending on the formatting settings. + Some entries in this vector might be empty strings or correspond to + inserted blank lines for visual spacing. + +3. start_row: `Vec`: Starting row for commit in the `graph.commits` vector. +*/ +pub type UnicodeGraphInfo = (Vec, Vec, Vec); + /// Creates a text-based visual representation of a graph. pub fn print_unicode(graph: &GitGraph, settings: &Settings) -> Result { From b225ad657dc38a7b7f166dcbecbf7cc2d6b88284 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Thu, 29 May 2025 07:01:18 +0200 Subject: [PATCH 3/5] Occ Struct documentation --- src/print/unicode.rs | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/src/print/unicode.rs b/src/print/unicode.rs index f45750f..377b33c 100644 --- a/src/print/unicode.rs +++ b/src/print/unicode.rs @@ -672,8 +672,19 @@ pub fn format_branches( /// Occupied row ranges enum Occ { - Commit(usize, usize), - Range(usize, usize, usize, usize), + /// Horizontal position of commit markers + // First field (usize): The index of a commit within the graph.commits vector. + // Second field (usize): The visual column in the grid where this commit is located. This column is determined by the branch the commit belongs to. + // Purpose: This variant of Occ signifies that a specific row in the grid is occupied by a commit marker (dot or circle) at a particular column. + Commit(usize, usize), // index in Graph.commits, column + + /// Horizontal line connecting two commits + // First field (usize): The index of the starting commit of a visual connection (usually the child commit). + // Second field (usize): The index of the ending commit of a visual connection (usually the parent commit). + // Third field (usize): The starting visual column of the range occupied by the connection line between the two commits. This is the minimum of the columns of the two connected commits. + // Fourth field (usize): The ending visual column of the range occupied by the connection line between the two commits. This is the maximum of the columns of the two connected commits. + // Purpose: This variant of Occ signifies that a range of columns in a particular row is occupied by a horizontal line segment connecting a commit to one of its parents. The range spans from the visual column of one commit to the visual column of the other. + Range(usize, usize, usize, usize), // ?child index, parent index, leftmost column, rightmost column } impl Occ { From ee3efdc5feff2e06a727fc8485e133a1255faecd Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Thu, 29 May 2025 07:01:18 +0200 Subject: [PATCH 4/5] Grid Struct documentation --- src/print/unicode.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/print/unicode.rs b/src/print/unicode.rs index 377b33c..f90e588 100644 --- a/src/print/unicode.rs +++ b/src/print/unicode.rs @@ -705,11 +705,17 @@ fn sorted(v1: usize, v2: usize) -> (usize, usize) { } } -/// Two-dimensional grid with 3 layers, used to produce the graph representation. +/// Two-dimensional grid used to produce the graph representation. #[allow(dead_code)] struct Grid { width: usize, height: usize, + + /// Grid cells are stored in the data vector, layout row wise. + /// For each cell in the grid, three values are stored: + /// - Character (symbol) + /// - Colour + /// - Persistence level (z-order, lower numbers take preceedence) data: Vec<[u8; 3]>, } @@ -725,6 +731,7 @@ impl Grid { pub fn reverse(&mut self) { self.data.reverse(); } + /// Turn a 2D coordinate into an index of Grid.data pub fn index(&self, x: usize, y: usize) -> usize { y * self.width + x } From e1737a728333488d885b20bfc372593596e67e21 Mon Sep 17 00:00:00 2001 From: Peer Sommerlund Date: Sat, 13 Sep 2025 15:29:29 +0200 Subject: [PATCH 5/5] Fix rust 1.89.0 warnings --- src/graph.rs | 2 +- src/print/unicode.rs | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/src/graph.rs b/src/graph.rs index fecea3f..f0b7727 100644 --- a/src/graph.rs +++ b/src/graph.rs @@ -187,7 +187,7 @@ impl GitGraph { self.repository } - pub fn commit(&self, id: Oid) -> Result { + pub fn commit(&self, id: Oid) -> Result, Error> { self.repository.find_commit(id) } } diff --git a/src/print/unicode.rs b/src/print/unicode.rs index f90e588..77757d0 100644 --- a/src/print/unicode.rs +++ b/src/print/unicode.rs @@ -54,7 +54,6 @@ graph-lines, text-lines, start-row */ pub type UnicodeGraphInfo = (Vec, Vec, Vec); - /// Creates a text-based visual representation of a graph. pub fn print_unicode(graph: &GitGraph, settings: &Settings) -> Result { if graph.all_branches.is_empty() {