Skip to content

Commit 83f728a

Browse files
bayuagpr-xaltiusbayuagpr-xaltius
committed
docs: add example and demo giff
1 parent d3ac0a5 commit 83f728a

File tree

17 files changed

+823
-8
lines changed

17 files changed

+823
-8
lines changed

‎README.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,12 @@
1010
**Stop squinting at those git provider diff views.**
1111
<br>
1212
Generate beautiful, searchable, IDE-friendly git diffs in markdown format.
13+
<br>
14+
<br>
15+
![Demo GIF showing diff generation](docs/demo-gitloom-diff.gif)
1316
</div>
1417

15-
![Demo GIF showing diff generation]() <!-- Add demo gif -->
18+
<br>
1619

1720
> ⚠️ **Early Stage Project**: GitLoom Diff is currently in active development and not yet production-ready. Expect frequent breaking changes and major updates as we evolve the tool. Use with caution in production environments.
1821

‎docs/demo-gitloom-diff.gif

2.04 MB
Loading

‎example/DIFF_INDEX.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Git Diff Summary
2+
3+
> Comparing current to working tree
4+
5+
## Total Changes Stats
6+
```
7+
7 files changed, 190 insertions(+), 7 deletions(-)
8+
```
9+
10+
## Commit Messages
11+
12+
## Changed Files
13+
14+
- [package.json](./package.json.md) - 1 insertion(+), 1 deletion
15+
- [src/cli/index.js](./src/cli/index.js.md) - No changes
16+
- [src/sdk/GitLoomDiff.js](./src/sdk/GitLoomDiff.js.md) - 59 insertions(+), 2 deletion
17+
- [src/sdk/config/Config.js](./src/sdk/config/Config.js.md) - 21 insertions(+), 1 deletion
18+
- [src/sdk/constants/gitExclusions.js](./src/sdk/constants/gitExclusions.js.md) - 16 insertions(+), 2 deletion
19+
- [src/sdk/utils/fsUtils.js](./src/sdk/utils/fsUtils.js.md) - No changes
20+
- [src/sdk/utils/gitUtils.js](./src/sdk/utils/gitUtils.js.md) - 45 insertions(+), 1 deletion

‎example/package.json.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<!--
2+
<style>
3+
.markdown-body .highlight pre, .markdown-body pre {
4+
background-color: #0d1117;
5+
}
6+
.markdown-body .diff-deletion {
7+
color: #f85149;
8+
background-color: #3c1618;
9+
}
10+
.markdown-body .diff-addition {
11+
color: #56d364;
12+
background-color: #1b4721;
13+
}
14+
</style>
15+
-->
16+
Auto-generated by GitLoom Diff at Tuesday, November 12, 2024 at 6:14:36 PM GMT+8
17+
18+
# Changes in `package.json`
19+
20+
## File Statistics
21+
```
22+
package.json | 2 +-
23+
1 file changed, 1 insertion(+), 1 deletion(-)
24+
25+
```
26+
27+
## Changes
28+
```diff
29+
diff --git a/package.json b/package.json
30+
index f185111..4c6df78 100644
31+
--- a/package.json
32+
+++ b/package.json
33+
@@ -1,6 +1,6 @@
34+
{
35+
"name": "gitloom-diff",
36+
- "version": "0.0.42",
37+
+ "version": "0.0.43",
38+
"description": "Git diff tool that outputs markdown formatted diffs",
39+
"main": "src/sdk/GitLoomDiff.js",
40+
"bin": {
41+
42+
```
43+

‎example/src/cli/index.js.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<!--
2+
<style>
3+
.markdown-body .highlight pre, .markdown-body pre {
4+
background-color: #0d1117;
5+
}
6+
.markdown-body .diff-deletion {
7+
color: #f85149;
8+
background-color: #3c1618;
9+
}
10+
.markdown-body .diff-addition {
11+
color: #56d364;
12+
background-color: #1b4721;
13+
}
14+
</style>
15+
-->
16+
Auto-generated by GitLoom Diff at Tuesday, November 12, 2024 at 6:14:36 PM GMT+8
17+
18+
# Changes in `src/cli/index.js`
19+
20+
## File Statistics
21+
```
22+
src/cli/index.js | 26 ++++++++++++++++++++++++++
23+
1 file changed, 26 insertions(+)
24+
25+
```
26+
27+
## Changes
28+
```diff
29+
diff --git a/src/cli/index.js b/src/cli/index.js
30+
index 34daa02..2fa36fa 100644
31+
--- a/src/cli/index.js
32+
+++ b/src/cli/index.js
33+
@@ -3,6 +3,32 @@
34+
const { program } = require("commander");
35+
const GitLoomDiff = require("../sdk/GitLoomDiff");
36+
37+
+/**
38+
+ * Configures and runs the GitLoomDiff CLI program.
39+
+ *
40+
+ * Command line options:
41+
+ * @param {string} [options.startRef] - Starting git reference (commit/branch/tag) to compare from
42+
+ * @param {string} [options.endRef] - Ending git reference to compare to
43+
+ * @param {string} [options.output=git-diffs] - Directory to output the diff files
44+
+ * @param {string[]} [options.exclude] - File patterns to exclude from the diff
45+
+ * @param {string} [options.format=diff] - Diff format:
46+
+ * - 'diff': Traditional git diff format
47+
+ * - 'unified': Unified diff format
48+
+ * - 'side-by-side': Two column comparison view
49+
+ * @param {boolean} [options.lightMode=false] - Use light mode theme instead of dark
50+
+ *
51+
+ * Default behavior:
52+
+ * - Compares current branch against 'main' if no refs provided
53+
+ * - Outputs to './git-diffs' directory
54+
+ * - Uses dark mode theme
55+
+ * - Shows traditional diff format
56+
+ *
57+
+ * The program generates markdown files containing:
58+
+ * - Syntax highlighted code diffs
59+
+ * - File change statistics
60+
+ * - Commit history between refs
61+
+ * - Navigation links between files
62+
+ */
63+
program
64+
.name("gitloom-diff")
65+
.description("Generate markdown-formatted git diffs")
66+
67+
```
68+

‎example/src/sdk/GitLoomDiff.js.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
<!--
2+
<style>
3+
.markdown-body .highlight pre, .markdown-body pre {
4+
background-color: #0d1117;
5+
}
6+
.markdown-body .diff-deletion {
7+
color: #f85149;
8+
background-color: #3c1618;
9+
}
10+
.markdown-body .diff-addition {
11+
color: #56d364;
12+
background-color: #1b4721;
13+
}
14+
</style>
15+
-->
16+
Auto-generated by GitLoom Diff at Tuesday, November 12, 2024 at 6:14:36 PM GMT+8
17+
18+
# Changes in `src/sdk/GitLoomDiff.js`
19+
20+
## File Statistics
21+
```
22+
src/sdk/GitLoomDiff.js | 61 ++++++++++++++++++++++++++++++++++++++++++++++++--
23+
1 file changed, 59 insertions(+), 2 deletions(-)
24+
25+
```
26+
27+
## Changes
28+
```diff
29+
diff --git a/src/sdk/GitLoomDiff.js b/src/sdk/GitLoomDiff.js
30+
index 309c756..cbbe85d 100644
31+
--- a/src/sdk/GitLoomDiff.js
32+
+++ b/src/sdk/GitLoomDiff.js
33+
@@ -2,12 +2,30 @@ const gitUtils = require('./utils/gitUtils');
34+
const fsUtils = require('./utils/fsUtils');
35+
const Config = require('./config/Config');
36+
37+
+/**
38+
+ * GitLoomDiff generates markdown-formatted git diffs with syntax highlighting and statistics.
39+
+ * Handles comparing git references (commits/branches/tags) and outputting formatted markdown files.
40+
+ */
41+
class GitLoomDiff {
42+
+ /**
43+
+ * Creates a new GitLoomDiff instance with the provided configuration options.
44+
+ * @param {Object} options - Configuration options
45+
+ * @param {string} [options.outputDir='git-diffs'] - Directory to output the diff files
46+
+ * @param {string[]} [options.exclude=[]] - File patterns to exclude from the diff
47+
+ * @param {string} [options.format='diff'] - Diff format (diff, unified, side-by-side)
48+
+ * @param {boolean} [options.darkMode=true] - Whether to use dark mode theme
49+
+ */
50+
constructor(options = {}) {
51+
this.config = new Config(options);
52+
}
53+
54+
-
55+
+ /**
56+
+ * Runs the diff generation process.
57+
+ * @param {string} startRange - Starting git reference (commit/branch/tag)
58+
+ * @param {string} endRange - Ending git reference to compare against
59+
+ * @returns {Promise<void>}
60+
+ * @throws {Error} If git validation fails or diff generation encounters an error
61+
+ */
62+
async run(startRange, endRange) {
63+
const { default: ora } = await import("ora");
64+
const spinner = ora("Generating markdown diffs...").start();
65+
@@ -36,6 +54,15 @@ class GitLoomDiff {
66+
}
67+
}
68+
69+
+ /**
70+
+ * Processes each changed file to generate diffs and update the index.
71+
+ * @param {string[]} changedFiles - List of files that have changes
72+
+ * @param {string} range - Git range to compare
73+
+ * @param {Object} spinner - Progress spinner instance
74+
+ * @param {string[]} index - Index content array to update
75+
+ * @returns {Promise<void>}
76+
+ * @private
77+
+ */
78+
async #processFiles(changedFiles, range, spinner, index) {
79+
for (let i = 0; i < changedFiles.length; i++) {
80+
const file = changedFiles[i];
81+
@@ -49,10 +76,25 @@ class GitLoomDiff {
82+
}
83+
}
84+
85+
+ /**
86+
+ * Builds a git range string from start and end references.
87+
+ * @param {string} startRange - Starting reference
88+
+ * @param {string} endRange - Ending reference
89+
+ * @returns {string} Formatted git range or empty string if no range provided
90+
+ * @private
91+
+ */
92+
#buildGitRange(startRange, endRange) {
93+
return startRange && endRange ? `${endRange}..${startRange}` : "";
94+
}
95+
96+
+ /**
97+
+ * Builds the content for the index markdown file.
98+
+ * @param {string} startRange - Starting reference
99+
+ * @param {string} endRange - Ending reference
100+
+ * @param {string} totalStats - Total change statistics
101+
+ * @returns {Promise<string[]>} Array of index content lines
102+
+ * @private
103+
+ */
104+
async #buildIndexContent(startRange, endRange, totalStats) {
105+
const index = [
106+
"# Git Diff Summary\n",
107+
@@ -71,12 +113,20 @@ class GitLoomDiff {
108+
return index;
109+
}
110+
111+
+ /**
112+
+ * Generates the markdown content for a single file's diff.
113+
+ * @param {string} file - File path
114+
+ * @param {string} range - Git range to compare
115+
+ * @param {string} fileInfo - File change statistics
116+
+ * @returns {Promise<string>} Generated markdown content
117+
+ * @private
118+
+ */
119+
async #generateFileContent(file, range, fileInfo) {
120+
const diffOutput = await gitUtils.getFileDiff(file, range, this.config.diffFormat);
121+
122+
return [
123+
this.config.getCssStyle(),
124+
- `generated at ${new Date().toLocaleString()} (${Intl.DateTimeFormat().resolvedOptions().timeZone})`,
125+
+ `Auto-generated by GitLoom Diff at ${new Date().toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long', timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone })}`,
126+
"",
127+
`# Changes in \`${file}\``,
128+
"",
129+
@@ -94,6 +144,13 @@ class GitLoomDiff {
130+
].join("\n");
131+
}
132+
133+
+ /**
134+
+ * Updates the index content with a link to a processed file.
135+
+ * @param {string[]} index - Index content array to update
136+
+ * @param {string} file - File path
137+
+ * @param {string} fileInfo - File change statistics
138+
+ * @private
139+
+ */
140+
#updateIndex(index, file, fileInfo) {
141+
const stats = fileInfo.match(/(\d+) insertion.+(\d+) deletion/)?.[0] || "No changes";
142+
index.push(`- [${file}](./${file}.md) - ${stats}`);
143+
144+
```
145+

‎example/src/sdk/config/Config.js.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
<!--
2+
<style>
3+
.markdown-body .highlight pre, .markdown-body pre {
4+
background-color: #0d1117;
5+
}
6+
.markdown-body .diff-deletion {
7+
color: #f85149;
8+
background-color: #3c1618;
9+
}
10+
.markdown-body .diff-addition {
11+
color: #56d364;
12+
background-color: #1b4721;
13+
}
14+
</style>
15+
-->
16+
Auto-generated by GitLoom Diff at Tuesday, November 12, 2024 at 6:14:36 PM GMT+8
17+
18+
# Changes in `src/sdk/config/Config.js`
19+
20+
## File Statistics
21+
```
22+
src/sdk/config/Config.js | 22 +++++++++++++++++++++-
23+
1 file changed, 21 insertions(+), 1 deletion(-)
24+
25+
```
26+
27+
## Changes
28+
```diff
29+
diff --git a/src/sdk/config/Config.js b/src/sdk/config/Config.js
30+
index 6634d45..1035615 100644
31+
--- a/src/sdk/config/Config.js
32+
+++ b/src/sdk/config/Config.js
33+
@@ -1,4 +1,16 @@
34+
+/**
35+
+ * Configuration class for GitLoomDiff that manages output settings and styling
36+
+ * @class
37+
+ */
38+
class Config {
39+
+ /**
40+
+ * Creates a new Config instance with the provided options
41+
+ * @param {Object} options - Configuration options
42+
+ * @param {string} [options.outputDir='git-diffs'] - Directory to output the diff files
43+
+ * @param {string[]} [options.exclusions=[]] - Additional file patterns to exclude from diff
44+
+ * @param {('diff'|'unified'|'side-by-side')} [options.diffFormat='diff'] - Format for git diff output
45+
+ * @param {boolean} [options.darkMode=true] - Whether to use dark mode styling
46+
+ */
47+
constructor(options = {}) {
48+
this.outputDir = options.outputDir || "git-diffs";
49+
this.exclusions = options.exclusions || [];
50+
@@ -6,11 +18,19 @@ class Config {
51+
this.darkMode = options.darkMode ?? true;
52+
}
53+
54+
+ /**
55+
+ * Gets combined list of default and custom file exclusion patterns
56+
+ * @returns {string[]} Array of file patterns to exclude from diff
57+
+ */
58+
getExclusions() {
59+
const defaultExclusions = require('../constants/gitExclusions');
60+
return [...defaultExclusions, ...this.exclusions];
61+
}
62+
63+
+ /**
64+
+ * Gets CSS styles for dark mode markdown styling
65+
+ * @returns {string} CSS style block for dark mode or empty string if dark mode disabled
66+
+ */
67+
getCssStyle() {
68+
if (!this.darkMode) return '';
69+
70+
@@ -32,4 +52,4 @@ class Config {
71+
}
72+
}
73+
74+
-module.exports = Config;
75+
\ No newline at end of file
76+
+module.exports = Config;
77+
\ No newline at end of file
78+
79+
```
80+

0 commit comments

Comments
 (0)