@git-diff-view/cli

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

@git-diff-view/cli (英语)

中文使用文档
文档目录23 节
  1. 特征
  2. 安装
  3. 快速启动
  4. 基本用途
  5. 用 DiffFile 键
  6. API 参考
  7. DiffView 道具
  8. 代码视频道具
  9. 数据类型
  10. 主题自定义
  11. 可用的颜色托盘
  12. 滚动 API
  13. 共享类型
  14. 反证方法( ScrollViewRef (中文(简体) )
  15. 行语义
  16. 示例
  17. 宽度/ 模式变化
  18. 扩展行 (DiffView)
  19. 执行详情
  20. 使用大小写
  21. 实例
  22. 相关软件包
  23. 许可证

@git-diff-view/cli (英语)

基于终端的 diff 查看器, 用于 CLI 环境的 GitHub 风格 UI

npm version npm downloads

CLI Diff View

特征

  • * 终端方便的 diff 渲染
  • 在终端中分割和统一视图
  • CLI 语法突出显示
  • & 黑暗主题
  • QQ 可配置宽度并显示选项
  • * 固定高度取景口滚动(CodeView 打开 DiffView(中文(简体) )
  • 工作与 @git-diff-view/core 和 @git-diff-view/ file 相关

安装

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

快速启动

基本用途

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
});

用 DiffFile 键

文件比较模式

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 模式

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 参考

DiffView 道具

Prop类型说明
dataDiffData向导数据 oldFile, (中文(简体) ), newFile,以及 hunks
diffFileDiffFile预处理的 diff 文件实例
diffViewModeDiffModeEnum查看模式( 默认 ): SplitGitHub(中文(简体) )
diffViewTheme"light" | "dark"主题( 默认 ): "light"(中文(简体) )
diffViewHighlightboolean启用语法加亮
diffViewTabSpaceboolean显示标签/ 空格字符
diffViewTabWidth"small" | "medium" | "large"标签显示宽度( 默认值 : "medium"(中文(简体) )
diffViewHideOperatorboolean隐藏 +编号 :-编号 : 操作栏
diffViewNoBGboolean禁用透明终端的中性背景颜色
diffViewThemeColorsDiffViewColorTheme自定义色彩覆盖( 见 主题自定义(中文(简体) )
widthnumber用于渲染的固定终端宽度
heightnumber在可视行查看端口高度; 启用滚动模式( 见 滚动 API(中文(简体) )
onScrollChange(state: ScrollState) => void滚动状态改变时调用
diffViewExtendLineHeightnumber滚动布局中延伸行的可视行高( 默认 ): 1(中文(简体) )
extendDataExtendData每行增加数据
renderExtendLineFunction自定义延伸线渲染器

代码视频道具

Prop类型说明
data{ content: string; fileName?: string; fileLang?: string }源文件数据
fileFile预处理的文件实例
codeViewTheme"light" | "dark"主题( 默认 ): "light"(中文(简体) )
codeViewHighlightboolean启用语法加亮
codeViewTabSpaceboolean显示标签/ 空格字符
codeViewTabWidth"small" | "medium" | "large"标签显示宽度( 默认值 : "medium"(中文(简体) )
codeViewNoBGboolean禁用透明终端的中性背景颜色
codeViewThemeColorsDiffViewColorTheme自定义色彩覆盖( 见 主题自定义(中文(简体) )
widthnumber用于渲染的固定终端宽度
heightnumber在可视行查看端口高度; 启用滚动模式( 见 滚动 API(中文(简体) )
onScrollChange(state: ScrollState) => void滚动状态改变时调用

数据类型

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

主题自定义

您可以通过 diffViewThemeColors 编号 : codeViewThemeColors。所有字段都是可选的——未设置的密钥会倒回内置的 GitHub 风格默认.

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}
/>

可用的颜色托盘

脚本说明
addContent添加行的背景
delContent删除行的背景
plainContent不变行的背景
expandContent扩展/文本行的背景
emptyContent空占位符区域的背景
addLineNumber添加行的行号背景
delLineNumber删除行的行号背景
plainLineNumber不变行的行号背景
expandLineNumber扩展行的行号背景
hunkLineNumberHunk 页眉编号背景
plainLineNumberColor不变行的行号文字颜色
expandLineNumberColor扩展行的行号文字颜色
hunkContentColorHunk 页眉文本颜色
addContentHighlight添加文本的内嵌更改亮点
delContentHighlight对已删除的文本进行线性修改
hunkContentHunk 页眉背景
border边框颜色
noBGAddContent增强背景 noBG 已启用
noBGDelContent强烈删除背景当 noBG 已启用
noBGAddLineNumber强加行号背景 noBG 已启用
noBGDelLineNumber更强烈的删除行号背景 noBG 已启用
noBGAddContentHighlight强加亮度 noBG 已启用
noBGDelContentHighlight更强烈的删除亮度 noBG 已启用

每个符号是 { light: string; dark: string } ——每个主题变体的十六进制颜色字符串.

滚动 API

两者 CodeView 财务报告和审定财务报表 DiffView 支持带有程序滚动的有固定高度的视图。 过 height (单位:千美元) 视觉行,以启用滚动模式.

无 height,则全部内容变为(后向兼容). DiffView 在此情况下跳过滚动布局计算.

何时 height 大于内容, 视图 缩小到内容高度 (没有后面的空白行). ScrollState.viewportHeight 报告有效高度.

共享类型

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;
};

反证方法(ScrollViewRef(中文(简体) )

方法说明
getScrollState()当前滚动快照
scrollToTop(line)将目标逻辑行的第一个可视行与视图端口对齐
scrollToBottom(line)将目标逻辑行的最后一个可视行与视图端对齐
scrollUp({ unit?, step? })向上滚动( N)unit数字 : "visual" | "logical"默认值 "visual"(中文(简体) )
scrollDown({ unit?, step? })向下滚动

CodeViewRef 添加 getFileInstance()。 。 。 . DiffViewRef 添加 getDiffFileInstance()。 。 。 .

行语义

构成部分line 含义
代码查看源文件行号 (基于 1 ,), File.rawFile(中文(简体) )
DiffView (英语)平面显示序列中基于 1 的索引: hunk → 内容 → 每个内容块扩展. 第一个内容块有 没有 领先洪克线.

示例

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 更改、滚动回移到 0 (包装计数变化). DiffView 当切换分拆 qq 统一时, 也会重排 .

扩展行 (DiffView)

自定义 renderExtendLine 内容高度通过 diffViewExtendLineHeight (默认) 1)用于卷轴布局. 使用时设定它以匹配您的扩展 UI height。 。 。 .

执行详情

见 缩略语.md 用于建筑笔记。 滚动测试 :

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

使用大小写

  • CLI diff 工具
  • 基于终端的代码审查
  • 带有视觉 diff 的 Git 钩
  • CI/CD 管道 diff 显示
  • SSH 远程 diff 查看
  • 基于终端的编辑器

实例

// 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}
/>

许可证

麻省理工学院 万正东先生

版本与发布记录

@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 和提交记录判断。