@git-diff-view/cli

中文文档
0.1.11发布于 2026/10/15MITTypeScriptES Module近 30 天下载 2685

@git-diff-view/cli

原始使用文档
文档目录23 节
  1. Features
  2. Installation
  3. Quick Start
  4. Basic Usage
  5. With DiffFile
  6. API Reference
  7. DiffView Props
  8. CodeView Props
  9. DiffData Type
  10. Theme Customization
  11. Available Color Tokens
  12. Scroll API
  13. Shared types
  14. Ref methods ( ScrollViewRef )
  15. Line semantics
  16. Example
  17. Width / mode changes
  18. Extend lines (DiffView)
  19. Implementation details
  20. Use Cases
  21. Examples
  22. Related Packages
  23. License

@git-diff-view/cli

Terminal-based diff viewer with GitHub-style UI for CLI environments

npm version npm downloads

CLI Diff View

Features

  • ✅ Terminal-friendly diff rendering
  • ✅ Split & Unified views in terminal
  • ✅ Syntax highlighting in CLI
  • ✅ Light & Dark themes
  • ✅ Configurable width and display options
  • ✅ Fixed-height viewport scrolling (CodeView & DiffView)
  • ✅ Works with @git-diff-view/core and @git-diff-view/file

Installation

npm install @git-diff-view/cli
# or
pnpm add @git-diff-view/cli
# or
yarn add @git-diff-view/cli

Quick Start

Basic Usage

import { DiffView, DiffModeEnum } from "@git-diff-view/cli";

DiffView({
  data: {
    oldFile: { fileName: "old.ts", content: "...", fileLang: "typescript" },
    newFile: { fileName: "new.ts", content: "...", fileLang: "typescript" },
    hunks: ["..."]
  },
  diffViewMode: DiffModeEnum.Split,
  diffViewTheme: "dark",
  diffViewHighlight: true,
  width: 120  // Terminal width
});

With DiffFile

File Comparison Mode

import { DiffView } from "@git-diff-view/cli";
import { generateDiffFile } from "@git-diff-view/file";

const file = generateDiffFile(
  "old.ts", oldContent,
  "new.ts", newContent,
  "typescript", "typescript"
);
file.init();
file.buildSplitDiffLines();

DiffView({ diffFile: file, width: 120 });

Git Diff Mode

import { DiffView } from "@git-diff-view/cli";
import { DiffFile } from "@git-diff-view/core";

const file = new DiffFile(
  oldFileName, oldContent,
  newFileName, newContent,
  hunks,
  oldFileLang, newFileLang
);
file.init();
file.buildSplitDiffLines();

DiffView({ diffFile: file });

API Reference

DiffView Props

PropTypeDescription
dataDiffDataDiff data with oldFile, newFile, and hunks
diffFileDiffFilePre-processed diff file instance
diffViewModeDiffModeEnumView mode (default: SplitGitHub)
diffViewTheme"light" | "dark"Theme (default: "light")
diffViewHighlightbooleanEnable syntax highlighting
diffViewTabSpacebooleanShow tab/space characters
diffViewTabWidth"small" | "medium" | "large"Tab display width (default: "medium")
diffViewHideOperatorbooleanHide the +/-/ operator column
diffViewNoBGbooleanDisable neutral background colors for transparent terminals
diffViewThemeColorsDiffViewColorThemeCustom color overrides (see Theme Customization)
widthnumberFixed terminal width for rendering
heightnumberViewport height in visual rows; enables scroll mode (see Scroll API)
onScrollChange(state: ScrollState) => voidCalled when scroll state changes
diffViewExtendLineHeightnumberVisual row height for extend lines in scroll layout (default: 1)
extendDataExtendDataAdditional data per line
renderExtendLineFunctionCustom extend line renderer

CodeView Props

PropTypeDescription
data{ content: string; fileName?: string; fileLang?: string }Source file data
fileFilePre-processed file instance
codeViewTheme"light" | "dark"Theme (default: "light")
codeViewHighlightbooleanEnable syntax highlighting
codeViewTabSpacebooleanShow tab/space characters
codeViewTabWidth"small" | "medium" | "large"Tab display width (default: "medium")
codeViewNoBGbooleanDisable neutral background colors for transparent terminals
codeViewThemeColorsDiffViewColorThemeCustom color overrides (see Theme Customization)
widthnumberFixed terminal width for rendering
heightnumberViewport height in visual rows; enables scroll mode (see Scroll API)
onScrollChange(state: ScrollState) => voidCalled when scroll state changes

DiffData Type

type DiffData = {
  oldFile?: {
    fileName?: string | null;
    fileLang?: string | null;
    content?: string | null;
  };
  newFile?: {
    fileName?: string | null;
    fileLang?: string | null;
    content?: string | null;
  };
  hunks: string[];
};

Theme Customization

You can override any color token via diffViewThemeColors / codeViewThemeColors. All fields are optional — unset keys fall back to the built-in GitHub-style defaults.

import type { DiffViewColorTheme } from "@git-diff-view/cli";

const myTheme: DiffViewColorTheme = {
  addContent: { light: "#d4edda", dark: "#1b4332" },
  delContent: { light: "#f8d7da", dark: "#3d0f0f" },
  addContentHighlight: { light: "#a3d9a5", dark: "#2d6a4f" },
  delContentHighlight: { light: "#f1aeb5", dark: "#6c1e1e" },
};
<DiffView
  diffFile={file}
  diffViewMode={DiffModeEnum.Unified}
  diffViewTheme="dark"
  diffViewThemeColors={myTheme}
/>

Available Color Tokens

TokenDescription
addContentBackground for added lines
delContentBackground for deleted lines
plainContentBackground for unchanged lines
expandContentBackground for expand/context lines
emptyContentBackground for empty placeholder areas
addLineNumberLine number background for added lines
delLineNumberLine number background for deleted lines
plainLineNumberLine number background for unchanged lines
expandLineNumberLine number background for expand lines
hunkLineNumberHunk header line number background
plainLineNumberColorLine number text color for unchanged lines
expandLineNumberColorLine number text color for expand lines
hunkContentColorHunk header text color
addContentHighlightInline change highlight for added text
delContentHighlightInline change highlight for deleted text
hunkContentHunk header background
borderBorder color
noBGAddContentStronger add background when noBG is enabled
noBGDelContentStronger delete background when noBG is enabled
noBGAddLineNumberStronger add line number background when noBG is enabled
noBGDelLineNumberStronger delete line number background when noBG is enabled
noBGAddContentHighlightStronger add highlight when noBG is enabled
noBGDelContentHighlightStronger delete highlight when noBG is enabled

Each token is { light: string; dark: string } — hex color strings for each theme variant.

Scroll API

Both CodeView and DiffView support a fixed-height viewport with programmatic scrolling. Pass height (in visual rows, after line wrap) to enable scroll mode.

Without height, the full content is rendered (backward compatible). DiffView skips scroll layout calculation in that case.

When height is larger than the content, the viewport shrinks to content height (no trailing blank rows). ScrollState.viewportHeight reports the effective height.

Shared types

import type { ScrollState, ScrollViewRef } from "@git-diff-view/cli";

type ScrollState = {
  totalLines: number;      // logical line count
  totalRows: number;       // visual row count after wrap
  viewportHeight: number;  // min(height, totalRows) when height is set; else totalRows
  scrollOffset: number;    // top visual row (0-based)
  startLine: number;       // first visible logical line (includes partial clips)
  endLine: number;         // last visible logical line (includes partial clips)
  canScrollUp: boolean;
  canScrollDown: boolean;
};

Ref methods (ScrollViewRef)

MethodDescription
getScrollState()Current scroll snapshot
scrollToTop(line)Align the target logical line's first visual row to the viewport top
scrollToBottom(line)Align the target logical line's last visual row to the viewport bottom
scrollUp({ unit?, step? })Scroll up (unit: "visual" | "logical", default "visual")
scrollDown({ unit?, step? })Scroll down

CodeViewRef adds getFileInstance(). DiffViewRef adds getDiffFileInstance().

Line semantics

Componentline meaning
CodeViewSource file line number (1-based, File.rawFile)
DiffView1-based index in the flattened display sequence: hunk → content → extend per content block. The first content block has no leading hunk line.

Example

import { useRef } from "react";
import { CodeView, DiffView, type CodeViewRef } from "@git-diff-view/cli";

const ref = useRef<CodeViewRef>(null);

<CodeView
  ref={ref}
  file={file}
  height={20}
  width={80}
  onScrollChange={(state) => console.log(state.startLine, state.endLine)}
/>;

ref.current?.scrollToTop(100);
ref.current?.scrollDown({ unit: "logical" });

Width / mode changes

When width changes, scroll offset resets to 0 (wrap counts change). DiffView also resets when switching split ↔ unified.

Extend lines (DiffView)

Custom renderExtendLine content height is estimated via diffViewExtendLineHeight (default 1) for scroll layout. Set it to match your extend UI when using height.

Implementation details

See SCROLL.md for architecture notes. Scroll tests:

pnpm --filter @git-diff-view/cli test:scroll
pnpm --filter @git-diff-view/cli test:scroll:interactive        # CodeView
pnpm --filter @git-diff-view/cli test:scroll:interactive:diffview

Use Cases

  • CLI diff tools
  • Terminal-based code review
  • Git hooks with visual diff
  • CI/CD pipeline diff display
  • SSH remote diff viewing
  • Terminal-based editors

Examples

// Simple diff with custom width
<DiffView data={diffData} width={160} diffViewHighlight={true} />

// Unified view in dark theme
<DiffView
  diffFile={file}
  diffViewMode={DiffModeEnum.Unified}
  diffViewTheme="dark"
/>

// Transparent terminal with no background colors
<DiffView
  data={diffData}
  diffViewNoBG={true}
  diffViewTheme="dark"
/>

// With custom theme colors
<DiffView
  data={diffData}
  diffViewThemeColors={{
    addContent: { light: "#d4edda", dark: "#1b4332" },
    delContent: { light: "#f8d7da", dark: "#3d0f0f" },
  }}
/>

// CodeView for single file rendering
<CodeView
  data={{ content: sourceCode, fileLang: "typescript" }}
  codeViewTheme="dark"
  codeViewHighlight={true}
/>

// Fixed-height scroll viewport
<DiffView
  diffFile={file}
  height={18}
  width={100}
  onScrollChange={console.log}
/>

License

MIT © MrWangJustToDo

版本与发布记录

@git-diff-view/cli 共发布 22 个版本,首次发布于 2025/08/16;过去 12 个月发布了 17 个版本。

版本发布日期距今
0.1.11latest2026/10/151 个月前
0.1.102026/07/144 个月前
0.1.92026/07/134 个月前
0.1.82026/06/234 个月前
0.1.72026/06/224 个月前
0.1.62026/06/214 个月前

关于 @git-diff-view/cli 的常见问题

@git-diff-view/cli 是什么?

@git-diff-view/cli

如何安装 @git-diff-view/cli?

在项目目录运行 npm install @git-diff-view/cli,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:ink(^6.1.0)、react(^19.2.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@git-diff-view/cli 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@git-diff-view/cli 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@git-diff-view/cli 可以商用吗?

@git-diff-view/cli 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@git-diff-view/cli 的下载量有多少?

根据 npm 官方下载统计,@git-diff-view/cli 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,685 次,日均约 90 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@git-diff-view/cli 还在维护吗?

最新版本 0.1.11 发布于 2026/10/15(1 个月前);至今共发布 22 个版本,其中过去 12 个月发布了 17 个;首次发布于 2025/08/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。