Skip to content

Commit 15a6854

Browse files
MrWangJustToDoMrWangJustToDo
committed
doc by ai
1 parent 692fbc5 commit 15a6854

File tree

15 files changed

+1540
-660
lines changed

15 files changed

+1540
-660
lines changed

‎README.md‎

Lines changed: 140 additions & 154 deletions
Large diffs are not rendered by default.

‎packages/cli/readme.md‎

Lines changed: 143 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,69 +1,162 @@
1-
## A Cli DiffView Component like GitHub, Easy to use and feature complete.
1+
# @git-diff-view/cli
22

3-
### Usage
3+
> Terminal-based diff viewer with GitHub-style UI for CLI environments
44
5-
#### There are two ways to use this component:
5+
[![npm version](https://img.shields.io/npm/v/@git-diff-view/cli)](https://www.npmjs.com/package/@git-diff-view/cli)
6+
[![npm downloads](https://img.shields.io/npm/dm/@git-diff-view/cli)](https://www.npmjs.com/package/@git-diff-view/cli)
67

7-
1. Use the `DiffView` component directly.
8+
## Features
89

9-
```tsx
10-
import { DiffView, DiffModeEnum } from "@git-diff-view/cli";
10+
- ✅ Terminal-friendly diff rendering
11+
- ✅ Split & Unified views in terminal
12+
- ✅ Syntax highlighting in CLI
13+
- ✅ Light & Dark themes
14+
- ✅ Configurable width and display options
15+
- ✅ Works with @git-diff-view/core and @git-diff-view/file
16+
17+
## Installation
18+
19+
```bash
20+
npm install @git-diff-view/cli
21+
# or
22+
pnpm add @git-diff-view/cli
23+
# or
24+
yarn add @git-diff-view/cli
25+
```
1126

12-
<DiffView<string>
13-
// use data
14-
data={{
15-
oldFile?: { fileName?: string | null; fileLang?: string | null; content?: string | null };
16-
newFile?: { fileName?: string | null; fileLang?: string | null; content?: string | null };
17-
hunks: string[];
18-
}}
19-
width={number}
20-
extendData={{oldFile: {10: {data: 'foo'}}, newFile: {20: {data: 'bar'}}}}
21-
renderExtendLine={({ data }) => ReactNode}
22-
diffViewHighlight={boolean}
23-
diffViewTabSpace={boolean}
24-
diffViewTabWidth={"small" | "medium" | "large"}
25-
diffViewMode={DiffModeEnum.Split | DiffModeEnum.Unified}
26-
diffViewTheme={'light' | 'dark'}
27-
/>
27+
## Quick Start
2828

29+
### Basic Usage
30+
31+
```typescript
32+
import { DiffView, DiffModeEnum } from "@git-diff-view/cli";
33+
34+
DiffView({
35+
data: {
36+
oldFile: { fileName: "old.ts", content: "...", fileLang: "typescript" },
37+
newFile: { fileName: "new.ts", content: "...", fileLang: "typescript" },
38+
hunks: ["..."]
39+
},
40+
diffViewMode: DiffModeEnum.Split,
41+
diffViewTheme: "dark",
42+
diffViewHighlight: true,
43+
width: 120 // Terminal width
44+
});
2945
```
3046

31-
2. Use the `DiffView` component with `@git-diff-view/core` or `@git-diff-view/file`
47+
### With DiffFile
48+
49+
**File Comparison Mode**
50+
51+
```typescript
52+
import { DiffView } from "@git-diff-view/cli";
53+
import { generateDiffFile } from "@git-diff-view/file";
3254

33-
```tsx
34-
// with @git-diff-view/file
35-
import { DiffFile, generateDiffFile } from "@git-diff-view/file";
3655
const file = generateDiffFile(
37-
data?.oldFile?.fileName || "",
38-
data?.oldFile?.content || "",
39-
data?.newFile?.fileName || "",
40-
data?.newFile?.content || "",
41-
data?.oldFile?.fileLang || "",
42-
data?.newFile?.fileLang || ""
56+
"old.ts", oldContent,
57+
"new.ts", newContent,
58+
"typescript", "typescript"
4359
);
4460
file.init();
4561
file.buildSplitDiffLines();
46-
file.buildUnifiedDiffLines();
4762

48-
// with @git-diff-view/core
63+
DiffView({ diffFile: file, width: 120 });
64+
```
65+
66+
**Git Diff Mode**
67+
68+
```typescript
69+
import { DiffView } from "@git-diff-view/cli";
4970
import { DiffFile } from "@git-diff-view/core";
71+
5072
const file = new DiffFile(
51-
data?.oldFile?.fileName || "",
52-
data?.oldFile?.content || "",
53-
data?.newFile?.fileName || "",
54-
data?.newFile?.content || "",
55-
data?.hunks || [],
56-
data?.oldFile?.fileLang || "",
57-
data?.newFile?.fileLang || ""
73+
oldFileName, oldContent,
74+
newFileName, newContent,
75+
hunks,
76+
oldFileLang, newFileLang
5877
);
5978
file.init();
6079
file.buildSplitDiffLines();
61-
file.buildUnifiedDiffLines();
62-
63-
// use current data to render
64-
<DiffView diffFile={file} {...props} />;
65-
// or use the bundle data to render, eg: postMessage/httpRequest
66-
const bundle = file.getBundle();
67-
const diffFile = DiffFile.createInstance(data || {}, bundle);
68-
<DiffView diffFile={diffFile} {...props} />;
69-
```
80+
81+
DiffView({ diffFile: file });
82+
```
83+
84+
## API Reference
85+
86+
### DiffView Options
87+
88+
| Option | Type | Description |
89+
|--------|------|-------------|
90+
| `data` | `DiffData` | Diff data with `oldFile`, `newFile`, and `hunks` |
91+
| `diffFile` | `DiffFile` | Pre-processed diff file instance |
92+
| `diffViewMode` | `Split \| Unified` | View mode (default: `Split`) |
93+
| `diffViewTheme` | `light \| dark` | Theme (default: `light`) |
94+
| `diffViewHighlight` | `boolean` | Enable syntax highlighting |
95+
| `diffViewTabSpace` | `boolean` | Show tab characters |
96+
| `diffViewTabWidth` | `small \| medium \| large` | Tab display width |
97+
| `width` | `number` | Terminal width for rendering |
98+
| `extendData` | `ExtendData` | Additional data per line |
99+
| `renderExtendLine` | `Function` | Custom extend line renderer |
100+
101+
### DiffData Type
102+
103+
```typescript
104+
type DiffData = {
105+
oldFile?: {
106+
fileName?: string | null;
107+
fileLang?: string | null;
108+
content?: string | null;
109+
};
110+
newFile?: {
111+
fileName?: string | null;
112+
fileLang?: string | null;
113+
content?: string | null;
114+
};
115+
hunks: string[];
116+
};
117+
```
118+
119+
## Use Cases
120+
121+
- CLI diff tools
122+
- Terminal-based code review
123+
- Git hooks with visual diff
124+
- CI/CD pipeline diff display
125+
- SSH remote diff viewing
126+
- Terminal-based editors
127+
128+
## Examples
129+
130+
```typescript
131+
// Simple diff with custom width
132+
DiffView({
133+
data: diffData,
134+
width: 160,
135+
diffViewHighlight: true
136+
});
137+
138+
// Unified view in dark theme
139+
DiffView({
140+
diffFile: file,
141+
diffViewMode: DiffModeEnum.Unified,
142+
diffViewTheme: "dark"
143+
});
144+
145+
// With tab configuration
146+
DiffView({
147+
data: diffData,
148+
diffViewTabSpace: true,
149+
diffViewTabWidth: "medium"
150+
});
151+
```
152+
153+
## Related Packages
154+
155+
- [@git-diff-view/core](https://www.npmjs.com/package/@git-diff-view/core) - Core diff engine
156+
- [@git-diff-view/file](https://www.npmjs.com/package/@git-diff-view/file) - File comparison
157+
- [@git-diff-view/react](https://www.npmjs.com/package/@git-diff-view/react) - React UI components
158+
- [@git-diff-view/vue](https://www.npmjs.com/package/@git-diff-view/vue) - Vue UI components
159+
160+
## License
161+
162+
MIT © [MrWangJustToDo](https://github.com/MrWangJustToDo)

‎packages/core/readme.md‎

Lines changed: 124 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,143 @@
1-
## `git diff` for @git-diff-view Component
1+
# @git-diff-view/core
2+
3+
> Core diff engine for git diff processing with syntax highlighting
4+
5+
[![npm version](https://img.shields.io/npm/v/@git-diff-view/core)](https://www.npmjs.com/package/@git-diff-view/core)
6+
[![npm downloads](https://img.shields.io/npm/dm/@git-diff-view/core)](https://www.npmjs.com/package/@git-diff-view/core)
7+
8+
## Features
9+
10+
- ✅ Git diff parsing and processing
11+
- ✅ Syntax highlighting with HAST AST
12+
- ✅ Split & Unified view data generation
13+
- ✅ Web Worker / Node.js compatible
14+
- ✅ Bundle-based data transfer
15+
- ✅ Theme support (light/dark)
16+
17+
## Installation
18+
19+
```bash
20+
npm install @git-diff-view/core
21+
# or
22+
pnpm add @git-diff-view/core
23+
# or
24+
yarn add @git-diff-view/core
25+
```
226

327
## Usage
428

5-
```tsx
6-
// ==== step1: generate diff view data, this part can be used in the worker/server environment for better performance ==== //
29+
### Basic Usage
30+
31+
```typescript
732
import { DiffFile } from "@git-diff-view/core";
33+
34+
// Create diff file instance
835
const file = new DiffFile(
9-
data?.oldFile?.fileName || "",
10-
data?.oldFile?.content || "",
11-
data?.newFile?.fileName || "",
12-
data?.newFile?.content || "",
13-
data?.hunks || [],
14-
data?.oldFile?.fileLang || "",
15-
data?.newFile?.fileLang || ""
16-
);
17-
// light / dark theme, base on current highlight engine
18-
// default is light
19-
file.initTheme(xxx);
20-
// init
36+
oldFileName,
37+
oldContent,
38+
newFileName,
39+
newContent,
40+
hunks, // git diff hunks
41+
oldFileLang, // e.g., "typescript"
42+
newFileLang
43+
);
44+
45+
// Initialize theme (optional, default: light)
46+
file.initTheme('dark');
47+
48+
// Initialize diff data
2149
file.init();
22-
// or you can use below method to init
23-
file.initRaw();
24-
file.initSyntax(); // if you do not want syntax highlight, you can skip this step
2550

26-
// build the `Split View` data;
51+
// Build view data
52+
file.buildSplitDiffLines(); // For split view
53+
file.buildUnifiedDiffLines(); // For unified view
54+
```
55+
56+
### Advanced: Separate Initialization
57+
58+
```typescript
59+
// For more control over initialization
60+
file.initRaw(); // Parse git diff
61+
file.initSyntax(); // Apply syntax highlighting (optional)
62+
2763
file.buildSplitDiffLines();
64+
file.buildUnifiedDiffLines();
65+
```
2866

29-
// build the `Unified View` data;
67+
### Worker/Server Pattern
68+
69+
Process diff data in a separate thread or server for better performance:
70+
71+
```typescript
72+
// Worker/Server side - generate bundle
73+
const file = new DiffFile(/* ... */);
74+
file.initTheme('dark');
75+
file.init();
76+
file.buildSplitDiffLines();
3077
file.buildUnifiedDiffLines();
3178

32-
// get All the diff data bundle, you can safely to send this data to the client side
3379
const bundle = file.getBundle();
80+
// Send bundle to main thread/client
3481

35-
// ==== step2: render the @git-diff-view component ==== //
82+
// Main thread/Client side - reconstruct
83+
import { DiffFile } from "@git-diff-view/core";
3684

37-
// merge bundle
38-
const mergeFile = DiffFile.createInstance(data || {}, bundle);
85+
const mergedFile = DiffFile.createInstance(data, bundle);
3986

40-
// used for @git-diff-view/react and @git-diff-view/vue
41-
<DiffView diffFile={mergeFile} />
87+
// Use with UI components
88+
<DiffView diffFile={mergedFile} />
89+
```
90+
91+
## API Reference
4292

43-
<DiffView :diffFile="mergeFile" />
93+
### DiffFile Class
4494

95+
#### Constructor
96+
97+
```typescript
98+
new DiffFile(
99+
oldFileName: string,
100+
oldContent: string,
101+
newFileName: string,
102+
newContent: string,
103+
hunks: string[],
104+
oldFileLang?: string,
105+
newFileLang?: string
106+
)
45107
```
46-
## Screen Shot
47108

48-
![Screenshot](https://raw.githubusercontent.com/MrWangJustToDo/git-diff-view/aa2e918498270f737d28e7531eab08fa3f1b8831/1.png)
49-
![Screenshot](https://raw.githubusercontent.com/MrWangJustToDo/git-diff-view/69c801e5eb5fcabc9c9655825eb1228f18dc1e0c/5.png)
50-
![Screenshot](https://raw.githubusercontent.com/MrWangJustToDo/git-diff-view/aa2e918498270f737d28e7531eab08fa3f1b8831/theme.png)
51-
![Screenshot](https://raw.githubusercontent.com/MrWangJustToDo/git-diff-view/aa2e918498270f737d28e7531eab08fa3f1b8831/2.png)
52-
![Screenshot](https://raw.githubusercontent.com/MrWangJustToDo/git-diff-view/aa2e918498270f737d28e7531eab08fa3f1b8831/3.png)
109+
#### Methods
110+
111+
| Method | Description |
112+
|--------|-------------|
113+
| `initTheme(theme)` | Set theme ('light' or 'dark') |
114+
| `init()` | Initialize diff data (calls initRaw + initSyntax) |
115+
| `initRaw()` | Parse git diff without syntax highlighting |
116+
| `initSyntax()` | Apply syntax highlighting |
117+
| `buildSplitDiffLines()` | Generate split view data |
118+
| `buildUnifiedDiffLines()` | Generate unified view data |
119+
| `getBundle()` | Export data for transfer |
120+
121+
#### Static Methods
122+
123+
| Method | Description |
124+
|--------|-------------|
125+
| `createInstance(data, bundle)` | Reconstruct DiffFile from bundle |
126+
127+
## Use Cases
128+
129+
- **Client-side**: Direct rendering with UI frameworks
130+
- **Worker pattern**: Offload processing to Web Worker
131+
- **Server-side**: Pre-process diffs in Node.js, send to client
132+
- **Hybrid**: Mix of client and server processing
133+
134+
## Related Packages
135+
136+
- [@git-diff-view/react](https://www.npmjs.com/package/@git-diff-view/react) - React components
137+
- [@git-diff-view/vue](https://www.npmjs.com/package/@git-diff-view/vue) - Vue components
138+
- [@git-diff-view/file](https://www.npmjs.com/package/@git-diff-view/file) - File comparison mode
139+
- [@git-diff-view/lowlight](https://www.npmjs.com/package/@git-diff-view/lowlight) - Syntax highlighter
140+
141+
## License
142+
143+
MIT © [MrWangJustToDo](https://github.com/MrWangJustToDo)

0 commit comments

Comments
 (0)