|
| 1 | + |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | + |
| 6 | +# :seedling: React Git Log |
| 7 | + |
| 8 | +A flexible and interactive React component for visualising Git commit history. Displays a branching graph alongside commit, branch and tag metadata, with support for customised theming. |
| 9 | + |
| 10 | +# Features |
| 11 | + |
| 12 | +- :seedling: Responsive commit history graph |
| 13 | +- :memo: Table with commit message and date |
| 14 | +- :bookmark: Branch and tagging information |
| 15 | +- :art: Custom theming API |
| 16 | +- :waning_crescent_moon: Dark and light modes |
| 17 | + |
| 18 | +# Using the component |
| 19 | + |
| 20 | +1. Install the package using your preferred package manager. |
| 21 | + |
| 22 | + Using npm |
| 23 | + ```shell |
| 24 | + npm install @tomplum/react-git-log |
| 25 | + ``` |
| 26 | + |
| 27 | + Using yarn |
| 28 | + ```shell |
| 29 | + yarn add @tomplum/react-git-log |
| 30 | + ``` |
| 31 | + |
| 32 | + Using pnpm |
| 33 | + ```shell |
| 34 | + pnpm add @tomplum/react-git-log |
| 35 | + ``` |
| 36 | + |
| 37 | +2. Make sure that `react` and `react-dom` are installed in your project, as they are peer dependencies. |
| 38 | + |
| 39 | + ```shell |
| 40 | + npm install react react-dom |
| 41 | + ``` |
| 42 | + |
| 43 | +3. Render the component in your application. |
| 44 | + |
| 45 | + Below is an example `YourConsumer.tsx` component that is using `GitLog`. See the [required](#required) component props to get started and the [optional](#optional) props for further configuration and theming. |
| 46 | + |
| 47 | + ```typescript jsx |
| 48 | + import { GitLog } from "@tomplum/react-git-log" |
| 49 | + |
| 50 | + const YourConsumer = () => { |
| 51 | + const { entries, currentBranch } = useYourDataSource() |
| 52 | + |
| 53 | + return ( |
| 54 | + <GitLog |
| 55 | + entries={entries} // <-- Pass the git log entry data in |
| 56 | + currentBranch={currentBranch} // <-- Tell it the branch that is checked out |
| 57 | + /> |
| 58 | + ) |
| 59 | + } |
| 60 | + ``` |
| 61 | +
|
| 62 | +# Git Log Data |
| 63 | +
|
| 64 | +The array of `GitLogEntry` objects is the source of data used by the `GitLog` component. It has the following properties: |
| 65 | +
|
| 66 | +| Property | Type | Description | |
| 67 | +|-----------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------| |
| 68 | +| `hash` | `string` | The unique hash identifier of the commit. | |
| 69 | +| `branch` | `string` | The name of the branch this commit belongs to. | |
| 70 | +| `parents` | `string[]` | An array of parent commit hashes. If this is a merge commit, it will have multiple parents. If it's an initial commit, it will have none. | |
| 71 | +| `message` | `string` | The commit message describing the changes made in this commit. | |
| 72 | +| `committerDate` | `string` | The date and time when the commit was applied by the committer. Typically the timestamp when the commit was finalized. | |
| 73 | +| `authorDate` | `string?` | *(Optional)* The date and time when the commit was originally authored. May differ from `committerDate` if the commit was rebased or amended. | |
| 74 | +
|
| 75 | +> [!TIP] |
| 76 | +> Usually you'd be sourcing this data from a backend service like a web-api, but you can extract it from the command line with the following command. |
| 77 | +
|
| 78 | +```bash |
| 79 | +git log --all --pretty=format:'hash:%h,parents:%p,branch:%S,msg:%s,cdate:%cd,adate:%ad' --date=iso >> git-log.txt |
| 80 | +``` |
| 81 | +
|
| 82 | +This will write `git-log.txt` in the directory where you ran the command. It can be passed to the `parseGitLog.ts` function from the library to produce an array of `GitLogEntry`. |
| 83 | +
|
| 84 | +# Component Props |
| 85 | +
|
| 86 | +## Required |
| 87 | +
|
| 88 | +| Prop | Type | Description | |
| 89 | +|-------------------------------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| |
| 90 | +| `entries` | `GitLogEntry[]` | The git log entries to visualize on the graph. | |
| 91 | +| `currentBranch` | `string` | The name of the branch that is currently checked out. | |
| 92 | +
|
| 93 | +## Optional |
| 94 | +
|
| 95 | +| Prop | Type | Description | |
| 96 | +|-------------------------------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| |
| 97 | +| `theme` | `ThemeMode` | The variant of the default color theme to apply to the log. | |
| 98 | +| `colours` | `ThemeColours \| string[]` | An array of colors used to color the log elements such as the graph. If not enough colors are provided, they will loop back from the start. | |
| 99 | +| `nodeTheme` | `NodeTheme` | The theme to apply the commit node elements in the graph. | |
| 100 | +| `showBranchesTags` | `boolean` | Whether to show labels for nodes that are the tips of branches or tags in the graph. | |
| 101 | +| `showTable` | `boolean` | Whether to show a table of commit metadata on the right-hand side of the graph. | |
| 102 | +| `showCommitNodeHashes` | `boolean` | Whether to show the commit hash next to the node in the graph. | |
| 103 | +| `showCommitNodeTooltips` | `boolean` | Whether to show tooltips when hovering over a commit node in the graph. | |
| 104 | +| `showTableHeaders` | `boolean` | Whether to show the names of the elements at the top of the component (e.g., "Graph", "Commit message"). | |
| 105 | +| `enableExperimentalAnimation` | `boolean` | Enables Framer Motion animation for simple fading transitions. Experimental feature. | |
| 106 | +| `enableResize` | `boolean` | Enables the graph's horizontal width to be resized. (Default: `false`) | |
| 107 | +| `rowSpacing` | `number` | The spacing between the rows of the log, affecting all elements across branches, graph, and table. (Default: `0`) | |
| 108 | +| `githubRepositoryUrl` | `string` | A link to the GitHub repository from which the log entries came. Enables links for commits, tags, and PRs. | |
| 109 | +| `defaultGraphContainerWidth` | `number` | The default width of the graph in pixels. (Default: `300`) | |
| 110 | +| `timestampFormat` | `string` | A timestamp format string passed to DayJS to format commit timestamps. (Default: `ISO-8601`) | |
| 111 | +| `onSelectCommit` | `(commit?: Commit) => void` | A callback function invoked when a commit is selected or unselected. | |
| 112 | +| `classes` | `GitLogStylingProps` | CSS classes for various underlying elements for custom styling. | |
| 113 | +| `paging` | `GitLogPaging` | Optional paging information to show a window of the given size from the set of git log entries. | |
| 114 | +
|
| 115 | +### GitLogStylingProps |
| 116 | +
|
| 117 | +| Prop | Type | Description | |
| 118 | +|-------------------|---------------------------------------------------------------------------------------------|---------------------------------------------------------| |
| 119 | +| `containerClass` | `string` | A class name for the wrapping container around the log. | |
| 120 | +| `containerStyles` | `CSSProperties` | A React CSS styling object for the wrapping container. | |
| 121 | +| `logTableClass` | `string` | A class name for the table element in the git log. | |
| 122 | +| `logTableStyles` | `{ table?: CSSProperties; thead?: CSSProperties; tr?: CSSProperties; td?: CSSProperties; }` | A React CSS styling object for the git log table. | |
| 123 | +
|
| 124 | +### GitLogPaging |
| 125 | +
|
| 126 | +| Prop | Type | Description | |
| 127 | +|--------|----------|-------------------------------------------------| |
| 128 | +| `size` | `number` | The number of rows to show per page. | |
| 129 | +| `page` | `number` | The page number to display (first page is `0`). | |
| 130 | +
|
| 131 | +### NodeTheme |
| 132 | +
|
| 133 | +| Prop | Type | Description | |
| 134 | +|-----------|----------|-----------------------------------------------------------------------| |
| 135 | +| `default` | `string` | The default theme where nodes change their style based on their type. | |
| 136 | +| `plain` | `string` | All nodes look the same, except for their colours. | |
0 commit comments