translate part of the manual into chinese

pull/370/head
Yeegsing 2022-09-10 17:55:41 +07:00
parent 44712123d3
commit 013a4ecdb7
12 changed files with 142 additions and 137 deletions

@ -1,4 +1,4 @@
# Summary
# Summary总结
- [Introduction](./introduction.md)
- [Installation](./installation.md)

@ -1,5 +1,5 @@
# Alternative Projects
# Alternative Projects其它项目
Many different tools exist for diffing files. This section of the
manual discusses the design of other tools that have influenced
difftastic.
difftastic.有许多不同的工具可以比较文件。本说明书的这一个部分讨论了其他影响到Difftastic的工具。

@ -2,7 +2,7 @@
Git [supports external diff
tools](https://git-scm.com/docs/diff-config#Documentation/diff-config.txt-diffexternal). You
can use `GIT_EXTERNAL_DIFF` for a one-off git command.
can use `GIT_EXTERNAL_DIFF` for a one-off git command.Git[支持使用外部的diff工具](https://git-scm.com/docs/diff-config#Documentation/diff-config.txt-diffexternal)。你可以使用`GIT_EXTERNEL_DIFF`来进行一键git命令。
```
$ GIT_EXTERNAL_DIFF=difft git diff
@ -10,7 +10,7 @@ $ GIT_EXTERNAL_DIFF=difft git log -p --ext-diff
$ GIT_EXTERNAL_DIFF=difft git show e96a7241760319 --ext-diff
```
If you want to use difftastic by default, use `git config`.
If you want to use difftastic by default, use `git config`.如果你想要默认使用Difftastic可以使用`git config`。
```
# Set git configuration for the current repository.
@ -22,7 +22,7 @@ $ git config --global diff.external difft
After running `git config`, `git diff` will use `difft`
automatically. Other git commands require `--ext-diff` to use
`diff.external`.
`diff.external`.在运行`git config`后,`git diff`命令将会自动使用`difft`。其他情况则需要使用`--ext-diff`来使用`diff.externel`。
```
$ git diff
@ -34,10 +34,10 @@ $ git show e96a7241760319 --ext-diff
[git difftool](https://git-scm.com/docs/git-difftool) is a git command
for viewing the current changes with a different diff tool. It's
useful if you want to use difftastic occasionally.
useful if you want to use difftastic occasionally.[git difftool](https://git-scm.com/docs/git-difftool) 是一款使用不同diff工具来查看当前修改的git命令。如果你想要偶尔使用Difftastic的话这将会非常有用。
Add the
following to your `.gitconfig` to use difftastic as your difftool.
following to your `.gitconfig` to use difftastic as your difftool.添加下列内容到你的`.gitconfig`中就会让Difftastic作为你的difftool工具。
```ini
[diff]
@ -50,14 +50,14 @@ following to your `.gitconfig` to use difftastic as your difftool.
cmd = difft "$LOCAL" "$REMOTE"
```
You can then run `git difftool` to see current changes with difftastic.
You can then run `git difftool` to see current changes with difftastic.然后你可以使用`git difftool`来用Difftastic查看当前修改。
```
$ git difftool
```
We also recommend the following settings to get the best difftool
experience.
experience.我们还推荐使用下列设置来获得最好的difftool体验。
```ini
# Use a pager for large output, just like other git commands.

@ -1,33 +1,34 @@
# Glossary
# Glossary词典
**Atom**: An atom is an item in difftastic's syntax tree structure
**Atom原子**: An atom is an item in difftastic's syntax tree structure
that has no children. It represents things like literals, variable
names, and comments. See also 'list'.
names, and comments. See also 'list'.原子是Difftastic语法树结构中的一个项目没有子项。它代表着字面量、变量名以及注释。 另见'list'。
**Delimiter**: A paired piece of syntax. A list has an open delimiter
**Delimiter分隔符**: A paired piece of syntax. A list has an open delimiter
and a close delimiter, such as `[` and `]`. Delimiters may not be
punctuation (e.g. `begin` and `end`) and may be empty strings (e.g. infix
syntax converted to difftastic's syntax tree).
syntax converted to difftastic's syntax tree).即一个成对的语法。一个列表有一个开放定界符和一个封闭定界符,例如`[`和`]`。分隔符不可以是标点符号(例如,`begin`和`end`以及空字符串例如infix语法转换为Difftastic的语法树
**LHS**: Left-hand side. Difftastic compares two items, and LHS refers
to the first item. See also 'RHS'.
to the first item. See also 'RHS'.即Left-hand side。Difftastic会对比两个文件而LHS是指第一个文件。另见'RHS'。
**List**: A list is an item in difftastic's syntax tree structure that
**List列表**: A list is an item in difftastic's syntax tree structure that
has an open delimiter, children, and a close delimiter. It represents
things like expressions and function definitions. See also 'atom'.
things like expressions and function definitions. See also 'atom'.列表是Difftastic语法树结构中的一个项目它有一个开放定界符、子项和一个封闭定界符。它代表表达式和函数定义等东西。另见'atom'。
**Novel**: An addition or a removal. Syntax is novel if it occurs
in only one of the two items being compared.
**Novel注意项**: An addition or a removal. Syntax is novel if it occurs
in only one of the two items being compared.一个增加或一个减少。如果语法只出现在被比较的两个项目中的一个,那么它就是一个注意项。
**RHS**: Right-hand side. Difftastic compares two items, and RHS
refers to the second item. See also 'LHS'.
refers to the second item. See also 'LHS'.即Right-hand side。Difftastic会对比两个文件而RHS是指第一个文件。另见'LHS'。
**Root**: A syntax tree without a parent node. Roots represent
**Root**: A syntax tree without a parent node. Roots represent
top-level definitions in the file being diffed.
**Syntax node**: An item in difftastic's syntax tree structure. Either
an atom or a list.
an atom or a list.一个没有父节点的语法树。根代表被差异的文件中的顶级定义。
**Token**: A small piece of syntax tracked by difftastic (e.g. `$x`,
**字符**: A small piece of syntax tracked by difftastic (e.g. `$x`,
`function` or `]`), for highlighting and aligned display. This is
either an atom or a non-empty delimiter.
either an atom or a non-empty delimiter.一小段由Difftastic跟踪的语法例如`$x`,
`function``]`),用于高亮显示和对齐显示。它是原子或者是一个非空的分隔符。

@ -1,41 +1,42 @@
# Installation
# Installation安装
## Installing a binary
## Installing a binary从二进制安装
Difftastic [provides GitHub
releases](https://github.com/Wilfred/difftastic/releases) with
prebuilt binaries.
prebuilt binaries.Difftastic以预先编译好的二进制的形式[提供Github realease](https://github.com/Wilfred/difftastic/releases) 。
Packages are also available on the following platforms.
Packages are also available on the following platforms.在以下平台上也可以使用软件包。
[![Packaging status](https://repology.org/badge/vertical-allrepos/difftastic.svg)](https://repology.org/project/difftastic/versions)
## Installing via homebrew (on macOS or Linux)
## Installing via homebrew (on macOS or Linux)通过homebrew安装在macos或者Linux平台
Difftastic can be installed with [Homebrew](https://formulae.brew.sh/formula/difftastic) on macOS or Linux.
Difftastic can be installed with [Homebrew](https://formulae.brew.sh/formula/difftastic) on macOS or Linux.Difftastic可以用[Homebrew](https://formulae.brew.sh/formula/difftastic)安装在macOS或Linux上。
```
$ brew install difftastic
```
## Installing from source
## Installing from source从源码安装
### Build Requirements
### Build Requirements编译要求
Difftastic is written in Rust, so you will need Rust installed. I
recommend [rustup](https://rustup.rs/) to install Rust. Difftastic
requires Rust version 1.57 or later.
requires Rust version 1.57 or later.Difftasitc是使用Rust编写的所以你需要安装Rust。我推荐使用[rustup](https://rustup.rs/)来安装Rust。
You will also need a C++ compiler that supports C++14. If you're using
GCC, you need at least version 8.
GCC, you need at least version 8.同时你也需要一个支持C++14的C++编译器。如果你正在使用GCC则GCC版本至少为8。
### Build
### Build编译
You can download and build [difftastic on
crates.io](https://crates.io/crates/difftastic) with Cargo (which is
part of Rust).
part of Rust).你可以下载并通过Cargo它是Rust的一部分来编译[difftastic on
crates.io](https://crates.io/crates/difftastic) 。
```
$ cargo install difftastic
@ -44,20 +45,21 @@ $ cargo install difftastic
Difftastic uses the `cc` crate for building C/C++ dependencies. This
allows you to use environment variables `CC` and `CXX` to control the
compiler used (see [the cc
docs](https://github.com/alexcrichton/cc-rs#external-configuration-via-environment-variables)).
docs](https://github.com/alexcrichton/cc-rs#external-configuration-via-environment-variables)). Difftastic使用`cc`程序箱来构建C/C++的依赖关系。这使得你可以通过环境变量`CC`和`CXX`来控制使用的编译器参照see [the cc
docs](https://github.com/alexcrichton/cc-rs#external-configuration-via-environment-variables))。
See [contributing](./contributing.md) for instructions on debug
builds.
builds.参考[contributing](./contributing.md)来查看有关构建的说明。
## (Optional) Install MIME Database
## (Optional) Install MIME Database可选安装MINE数据库
If a MIME database is available, difftastic will use it to detect
binary files more accurately. This is the same database used by the
`file` command, so you probably already have it.
`file` command, so you probably already have it.如果有一个MIME数据库Difftastic将使用它来更准确地检测二进制文件。这个也是使用`file`命令时所调用的同一个数据库,你可能已经安装了它。
The MIME database path is [specified in the XDG
specification](https://specifications.freedesktop.org/shared-mime-info-spec/0.11/ar01s03.html). The
database should be at one of the following paths:
database should be at one of the following paths:MIME数据库的路径[是在XDG的规定下](https://specifications.freedesktop.org/shared-mime-info-spec/0.11/ar01s03.html)
* `/usr/share/mime/magic`
* `/usr/local/share/mime/magic`

@ -1,20 +1,20 @@
# Introduction
# Introduction简介
Difftastic is a structural diff tool that understands syntax. It
supports [over 20 programming languages](./languages_supported.html)
and when it works, it's *fantastic*.
and when it works, it's *fantastic*. Difftastic是一个根据文件的语法的结构化比较工具。它支持[超过20款编程语言](./languages_supported.html),当使用它的时候,就会知道它有多么的*棒*。
Difftastic is open source software (MIT license) and [available on
GitHub](https://github.com/wilfred/difftastic).
GitHub](https://github.com/wilfred/difftastic). Difftastic是一款开源软件使用MIT许可证并且可以[在Github上获得](https://github.com/wilfred/difftastic)。
This copy of the manual describes version DFT_VERSION_HERE. The
[changelog](https://github.com/Wilfred/difftastic/blob/master/CHANGELOG.md)
records which features and bug fixes are in each version.
records which features and bug fixes are in each version. 该说明书会表明当前版本DFT_VERSION_HERE。[变更记录](https://github.com/Wilfred/difftastic/blob/master/CHANGELOG.md)会记录每个版本的特性增加和bug的修复。
## Syntactic Diffing
## 语法差异分析
Difftastic [detects the language](./usage.html#language-detection), parses the code, and then
compares the syntax trees. Let's look at an example.
compares the syntax trees. Let's look at an example. Difftastic会[检测编程语言](./usage.html#language-detection),爬取代码,随后比较句法树。见例子:
```
// old.rs
@ -36,9 +36,9 @@ let ts_lang = language_override
</pre>
Notice how difftastic recognises that `.map` is unchanged, even though
it's now on a new line with whitespace.
it's now on a new line with whitespace. 注意Difftastic是如何识别`.map`那段没有发生变化的,尽管它是在新的一行上以空格开头的。
A line-oriented diff does a much worse job here.
A line-oriented diff does a much worse job here.如果是以前那种面对行的差异分析表现会不理想。
<pre><code style="display:block">$ diff -u old.rs new.rs
@ -53,12 +53,12 @@ A line-oriented diff does a much worse job here.
Some textual diff tools also highlight word changes (e.g. GitHub or
git's `--word-diff`). They still don't understand the code
though. Difftastic will always find matched delimiters: you can see
the closing `)` from `or_else` has been highlighted.
the closing `)` from `or_else` has been highlighted. 一些文本差异分析工具也会突出单词的变化例如GitHub或者是git的`--word-diff`但是它们无法做到理解代码本身。Difftastic永远会找到匹配的定界符你可以看到`or_else`结尾出的`)`已经被突出显示。
## Fallback Textual Diffing
## 另一种文本差异分析
If input files are not in a format that difftastic understands, it
uses a conventional line-oriented text diff with word highlighting.
uses a conventional line-oriented text diff with word highlighting.如果输入的文件格式Difftastic无法理解他就会使用传统的以行为单位的文本差异分析并且会将单词高亮显示。
Difftastic will also use textual diffing when given extremely large
inputs.
inputs.同时当输入的文件较大时Difftastic也会使用以行为单位的文本差异分析。

@ -2,11 +2,11 @@
This page lists all the languages supported by difftastic. You can
also view the languages supported in your current installed version
with `difft --list-languages`.
with `difft --list-languages`.本页列出了 difftastic 支持的所有语言。你也可以用`difft --list-languages`查看你当前安装的版本所支持的语言。
## Programming Languages
## Programming Languages编程语言
| Language | Parser Used |
| Language语言 | Parser Used使用的解析器 |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Bash | [tree-sitter/tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash) |
| C | [tree-sitter/tree-sitter-c](https://github.com/tree-sitter/tree-sitter-c) |
@ -44,9 +44,9 @@ with `difft --list-languages`.
| TypeScript, TSX | [tree-sitter/tree-sitter-typescript](https://github.com/tree-sitter/tree-sitter-typescript) |
| Zig | [maxxnino/tree-sitter-zig](https://github.com/maxxnino/tree-sitter-zig) |
## Structured Text Formats
## Structured Text Formats结构化文本格式
| Language | Parser Used |
| Language语言 | Parser Used使用的解析器 |
|----------|-----------------------------------------------------------------------------------|
| CSS | [tree-sitter/tree-sitter-css](https://github.com/tree-sitter/tree-sitter-css) |
| HCL | [MichaHoffmann/tree-sitter-hcl](https://github.com/MichaHoffmann/tree-sitter-hcl) |

@ -3,7 +3,7 @@
Mercurial [supports external diff
tools](https://www.mercurial-scm.org/wiki/ExtdiffExtension) with the
Extdiff extension. Enable it by adding an entry to `extensions` in
your `.hgrc`.
your `.hgrc`.Mercurial[支持另外的diff工具](https://www.mercurial-scm.org/wiki/ExtdiffExtension)与Extdiff扩展。通过在你的`.hgrc`中添加`extensions`条目来启用它。
```
[extensions]
@ -11,10 +11,10 @@ extdiff =
```
You can then run `hg extdiff -p difft` (assumes the `difft` binary is
on your `$PATH`).
on your `$PATH`).然后你可以运行`hg extdiff -p difft`命令(假定`difft`二进制文件存放在你的`$PATH`中。
You can also define an alias to run difftastic with hg. Add the
following to your `.hgrc` to run difftastic with `hg dft`.
following to your `.hgrc` to run difftastic with `hg dft`.你也可以为带有hg的difftastic的语句定义一个别名。在你的`.hgrc`中添加以下内容,以便用`hg dft`运行Difftastic。
```
[extdiff]
@ -25,14 +25,14 @@ opts.dft = --missing-as-empty
## hg log -p
Mercurial does not have a way of changing the default diff tool, at
least to the author's knowledge.
least to the author's knowledge. Mercurial没有办法改变默认的差异工具至少就作者所知。
If you just want to view the diff of the most recent commit, you can
use the following.
use the following.如果你只想查看最近的一次提交的差异,你可以使用下面的方法。
```
GIT_PAGER_IN_USE=1 hg dft -r .^ -r . | less
```
This is equivalent to `hg log -l 1 -p`, although it does not show the
commit message.
commit message.这就等同于`hg log -l 1 -p`,尽管它不显示提交信息。

@ -4,19 +4,19 @@
Tree-sitter parsers are sometimes packaged on npm, sometimes packaged
on crates.io, and have different release frequencies. Difftastic uses
git subtrees (not git submodules) to track parsers.
git subtrees (not git submodules) to track parsers.Tree-sitter有时被打包在npm上有时被打包在crates.io上并且它们的发布频率不一样。Difftastic使用git subtrees而不是git submodules来追踪解析器。
## Updating a parser
## Updating a parser升级解析器
To update a parser, pull commits from the upstream git repository. For
example, the following command will update the Java parser:
example, the following command will update the Java parser:如果要更新解析器可以从上游的git仓库拉取提交。例如下面的命令将更新Java解析器
```
$ git subtree pull --prefix=vendor/tree-sitter-java git@github.com:tree-sitter/tree-sitter-java.git master
```
To see when each parser was last updated, use the following shell
command:
command:如果要查看每个解析器最后一次更新的时间请使用以下的Shell命令。
```
$ for d in $(git log | grep git-subtree-dir | tr -d ' ' | cut -d ":" -f2 | sort); do echo "$d"; git log --pretty=" %cs" -n 1 $d; done

@ -1,15 +1,15 @@
# Parsing
# 解析代码
Difftastic uses
[tree-sitter](https://tree-sitter.github.io/tree-sitter/) to build a
parse tree. The parse tree is then converted to a simpler tree which
can be diffed.
can be diffed.Difftastic会使用[tree-sitter](https://tree-sitter.github.io/tree-sitter/) 来建立一个语法树。然后,该语法树被转换为一个可以用来对比差异的简化版语法树。
## Parsing with Tree-sitter
Difftastic relies on tree-sitter to understand syntax. You can view
the parse tree that tree-sitter produces using the `--dump-ts`
flag.
flag.Difftastic依靠tree-sitter来理解语法。你可以使用`--dump-ts`来查看tree-sitter的语法树。
```
$ difft --dump-ts sample_files/javascript_simple_before.js | head
@ -25,16 +25,16 @@ program (0, 0) - (7, 0)
expression_statement (2, 0) - (2, 6)
```
## Simplified Syntax
## 简化的语法
Difftastic converts the tree-sitter parse tree to a simplified syntax
tree. The syntax tree is a uniform representation where everything is
either an atom (e.g. integer literals, comments, variable names) or a
list (consisting of the open delimiter, children and the close
delimiter).
delimiter).Difftastic将tree-sitter语法树转换为简化版的语法树。语法树是一种统一的表示方式其中所有东西都是原子例如整数、注释、变量名或者是一个列表由开放分界符、子句和关闭分界符组成以及分隔符。
The flag `--dump-syntax` will display the syntax tree generated for a
file.
file.`--dump-syntax`将显示出当前文件所对应的语法树。
```
$ difft --dump-syntax sample_files/before.js
@ -50,24 +50,24 @@ $ difft --dump-syntax sample_files/before.js
...
```
### Conversion Process
### Conversion Process转换过程
The simple representation of the difftastic parse tree makes diffing
much easier. Converting the detailed tree-sitter parse tree is a
recursive tree walk, treating tree-sitter leaf nodes as atoms. There
are two exceptions.
are two exceptions.Difftastic语法树的简单表达方式使得差异分析变得更加容易。Difftastic是通过一种递归树的行走方式来将tree-sitter树进行简化将tree-sitter的节点视作原子来处理。但有两个例外。
(1) Tree-sitter parse trees sometimes include unwanted structure. Some
grammars consider string literals to be a single token, whereas others
treat strings as a complex structure where the delimiters are
separate.
separate.Tree-sitter语法树有时会包括不需要的一些结构有些语法会认为字符串是一种单一的字符而有些则会将字符串视作为复杂的结构此时的分隔符就会将字符串分割开。
`tree_sitter_parser.rs` uses `atom_nodes` to mark specific tree-sitter
node names as flat atoms even if the node has children.
node names as flat atoms even if the node has children.`tree-sitter_parser.rs`使用`atom_nodes`来标记特定的tree-sitter节点为平原子即使该节点存在子节点。
(2) Tree-sitter parse trees include open and closing delimiters as
tokens. A list `[1]` will have a parse tree that includes `[` and `]`
as nodes.
as nodes.Tree-sitter分析树包括开放和关闭定界符作为其代码。列表`[1]`将有一个包括`[`和`]`的节点的语法树。
```
$ echo '[1]' > example.js
@ -82,16 +82,16 @@ program (0, 0) - (1, 0)
`tree_sitter_parser.rs` uses `open_delimiter_tokens` to ensure that
`[` and `]` are used as delimiter content in the enclosing list,
rather than converitng them to atoms.
rather than converitng them to atoms.`tree_sitter_parser.rs`使用`open_delimiter_tokens`来确保`[`和`]`被用作包围列表内容的分隔符,而不会将其转换为原子。
Difftastic can match up atoms that occur in different parts of the
simplified syntax tree. If e.g. a `[` is treated as an atom,
difftastic might match it with another `[` elsewhere. The resulting
diff would be unbalanced, highlighting different numbers of open and
close delimiters.
close delimiters.Difftastic可以将出现简化语法树中不同部分的原子进行匹配。例如如果一个`[`被当作一个原子Difftastic可能会在其他地方将其与另一个`]`进行匹配。如果开放和关闭分界符的数量不同,最终的差异分析结果将会是不平衡的。
### Lossy Syntax Trees
The simplified syntax tree only stores node content and node
position. It does not store whitespace between nodes, and position is
largely ignored during diffing.
largely ignored during diffing. 简化的语法树只存储节点内容与节点的位置,不会存储节点之间的空白,而且在差异分析的过程中,空格将会被忽略。

@ -1,120 +1,123 @@
# Tree Diffing
This page summarises some of the other tree diffing tools available.
This page summarises some of the other tree diffing tools available.本页总结了一些其他可用的树形差异分析工具。
If you're in a hurry, start by looking at Autochrome. It's extremely
capable, and has an excellent description of the design.
capable, and has an excellent description of the design.如果你很着急可以先看看Autochrome。它的能力很强并且对设计有着很好的描述。
If you're interested in a summary of the academic literature, [this
blog
post](http://useless-factor.blogspot.com/2008/01/matching-diffing-and-merging-xml.html)
(and its [accompanying
paper](http://useless-factor.blogspot.com/2008/01/matching-diffing-and-merging-xml.html)
-- mirrored under a CC BY-NC license) are great resources.
-- mirrored under a CC BY-NC license) are great resources. 如果你对学术文献的摘要感兴趣,[这个帖子](http://useless-factor.blogspot.com/2008/01/matching-diffing-and-merging-xml.html)(和它[附带的论文](http://useless-factor.blogspot.com/2008/01/matching-diffing-and-merging-xml.html)--在CC BY-NC的许可下可以被复制将是一个很好的资源。
## json-diff (2012)
Languages: JSON
Algorithm: Pairwise comparison
Output: CLI colours
Languages: JSON 语言JSON
Algorithm: Pairwise comparison 算法Pairwise comparison
Output: CLI colours 输出CLI colours
[json-diff](https://github.com/andreyvit/json-diff) performs a
structural diff of JSON files. It considers subtrees to be different
if they don't match exactly, so e.g. `"foo"` and `["foo"]` are
entirely different.
entirely different.[json-diff](https://github.com/andreyvit/json-diff)展示了JSON文件的结构层面的差异分析。如果两者是不完全匹配的那么它们的子树将是完全不同。例如`"foo"`和`["foo"]`是完全不同的。
json-diff is also noteworthy for its extremely readable display of
results.
results.可以注意的是json-diff的结果显示十分方便查看。
## GumTree (2014)
Languages: [~10 programming
languages](https://github.com/GumTreeDiff/gumtree/wiki/Languages)
Parser: Several, including [srcML](https://www.srcml.org/)
Algorithm: Top-down, then bottom-up
Ouput: HTML, Swing GUI, or text
languages](https://github.com/GumTreeDiff/gumtree/wiki/Languages) 语言:[约有10种编程语言](https://github.com/GumTreeDiff/gumtree/wiki/Languages)
Parser: Several, including [srcML](https://www.srcml.org/) 分析器:多种,包括 [srcML](https://www.srcml.org/)
Algorithm: Top-down, then bottom-up 算法Top-down随后bottom-up
Ouput: HTML, Swing GUI, or text 输出HTMLSwing GUI或者text
[GumTree](https://github.com/GumTreeDiff/gumtree) can parse several
programming languages and then performs a tree-based diff, outputting
an HTML display.
an HTML display.[GumTree](https://github.com/GumTreeDiff/gumtree)可以分析多种编程语言并且进行基于树结构的差异分析输出一个HTML的结果界面。
The GumTree algorithm is described in the associated paper
'Fine-grained and accurate source code differencing' by Falleri et al
([DOI](http://doi.acm.org/10.1145/2642937.2642982),
[PDF](https://hal.archives-ouvertes.fr/hal-01054552/document)). It
performs a greedy top-down search for identical subtrees, then
performs a bottom-up search to match up the rest.
performs a bottom-up search to match up the rest.GumTree算法在Falleri等人的相关论文《细粒度源码差异分析》中有所描述[DOI](http://doi.acm.org/10.1145/2642937.2642982),
[PDF](https://hal.archives-ouvertes.fr/hal-01054552/document))。它对相同的子树进行贪婪的自下而上的搜索,随后进行自下而上的搜索来匹配其余的子树。
## Tree Diff (2017)
Languages: S-expression data format
Algorithm: A* search
Output: Merged s-expression file
Languages: S-expression data format 语言S-表达式数据格式
Algorithm: A* search 算法A*搜索
Output: Merged s-expression file 输出合并后的S-表达式文件
Tristan Hume wrote a tree diffing algorithm during his 2017 internship
and Jane Street. The source code is not available, but [he has a blog
post](https://thume.ca/2017/06/17/tree-diffing/) discussing the design
in depth.
in depth. Tristan Hume在他2017年实习期间和在Jane Street期间写了一个树状差分算法。源代码是不可以用的但是[他写了一篇博客](https://thume.ca/2017/06/17/tree-diffing/)来对该设计进行了深入讨论。
This project finds minimal diffs between s-expression files used as
configuration by Jane Street. It uses A* search to find the minimal
diff between them, and builds a new s-expression with a section marked
with `:date-switch` for the differing parts.
with `:date-switch` for the differing parts. 该项目找到了Jane Street用作配置文件的s-表达式文件之间的最小差异。它使用了A*搜索来找到他们之间最小的差异,兵建立一个具有`:date-switch`进行标记差异的新的s-表达式文件。
(Jane Street also has patdiff, but that seems to be a line-oriented
diff with some whitespace/integer display polish. It doesn't
understand that e.g. whitespace in `"foo "` is meaningful).
understand that e.g. whitespace in `"foo "` is meaningful). Jane Street一样有patdiff但那似乎是一个面向行的差异分析并不带着一些空格及整数差异显示。这个工具它并不理解在`"foo "`中的空格是具有意义的。)
## Autochrome (2017)
Languages: Clojure
Parser: Custom, preserves comments
Algorithm: Dijkstra (previously A* search)
Output: HTML
Languages: Clojure 语言Clojure
Parser: Custom, preserves comments 分析器Custom并保留注释
Algorithm: Dijkstra (previously A* search) 算法Dijkstra算法A*搜索的先前版本)
Output: HTML 输出HTML
[Autochrome](https://fazzone.github.io/autochrome.html) parses Clojure
with a custom parser that preserves comments. Autochrome uses
Dijkstra's algorithm to compare syntax trees.
Dijkstra's algorithm to compare syntax trees.[Autochrome](https://fazzone.github.io/autochrome.html)使用了一个定制的、保留注释的解析器来分析Clojure。Autochrome使用Dijkstra算法来比较语法树之间的差异。
Autochrome's webpage includes worked examples of the algorithm and a
discussion of design tradeoffs. It's a really great resource for
understanding tree diffing techniques in general.
understanding tree diffing techniques in general. Auto chrome的网页包括该算法的工作实例以及对该设计权衡的讨论。这是一个用来了解树形差异分析的重要资源。
## graphtage (2020)
Languages: JSON, XML, HTML, YAML, plist, and CSS
Parser: json5, pyYAML, ignores comments
Algorithm: Levenshtein distance
Output: CLI colours
Languages: JSON, XML, HTML, YAML, plist, and CSS 语言JSON, XML, HTML, YAML, plist, and CSS
Parser: json5, pyYAML, ignores comments 解析器json5, pyYAML, ignores comments
Algorithm: Levenshtein distance 算法Levenshtein距离
Output: CLI colours 输出CLI colours
[graphtage](https://blog.trailofbits.com/2020/08/28/graphtage/)
compares structured data by parsing into a generic file format, then
displaying a diff. It even allows things like diffing JSON against
YAML.
YAML. [graphtage](https://blog.trailofbits.com/2020/08/28/graphtage/)通过将结构化数据解析为通用文件格式随后进行差异分析。它甚至允许比较JSON文件和YAML文件之间的区别。
As with json-diff, it does not consider `["foo"]` and `"foo"` to have
any similarities.
any similarities.与json-diff一样它不认为 `["foo"]`和`"foo"`之间有任何相似之处。
## Diffsitter (2020)
Parser: [Tree-sitter](https://tree-sitter.github.io/tree-sitter/)
Algorithm: Longest-common-subsequence
Output: CLI colours
Parser: [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) 解析器:[Tree-sitter](https://tree-sitter.github.io/tree-sitter/)
Algorithm: Longest-common-subsequence 算法LCSLongest-common-subsequence
Output: CLI colours 输出CLI colours
[Diffsitter](https://github.com/afnanenayet/diffsitter) is another
tree-sitter based diff tool. It uses [LCS diffing on the leaves of the
syntax
tree](https://github.com/afnanenayet/diffsitter/blob/b0fd72612c6fcfdb8c061d3afa3bea2b0b754f33/src/ast.rs#L310-L313).
tree](https://github.com/afnanenayet/diffsitter/blob/b0fd72612c6fcfdb8c061d3afa3bea2b0b754f33/src/ast.rs#L310-L313).[Diffsitter](https://github.com/afnanenayet/diffsitter)是另一个使用了tree-sitter解析器的差异分析工具。它使用了[LCS分析语法树中的子树](https://github.com/afnanenayet/diffsitter/blob/b0fd72612c6fcfdb8c061d3afa3bea2b0b754f33/src/ast.rs#L310-L313)。
## sdiff (2021)
Languages: Scheme
Parser: Scheme's built-in `read`, ignores comments
Algorithm: MH-Diff from the Chawathe paper
Output: CLI colours
Languages: Scheme 语言Scheme
Parser: Scheme's built-in `read`, ignores comments 解析器Scheme内置的`read`,并忽略注释
Algorithm: MH-Diff from the Chawathe paper算法Chawathe论文中的MH-Diff
Output: CLI colours 输出CLI colours
[Semantically meaningful S-expression diff: Tree-diff for lisp source
code](https://archive.fosdem.org/2021/schedule/event/sexpressiondiff/)
was presented at FOSDEM 2021.
was presented at FOSDEM 2021.[Semantically meaningful S-expression diff: Tree-diff for lisp source
code](https://archive.fosdem.org/2021/schedule/event/sexpressiondiff/)
在FOSDEM 2021中被发表。

@ -1,45 +1,44 @@
# Usage
# Usage使用方法
## Diffing Files
## Diffing Files差异比较文件
```
$ difft sample_files/before.js sample_files/after.js
```
## Diffing Directories
## Diffing Directories差异比较文件夹
```
$ difft sample_files/dir_before/ sample_files/dir_after/
```
Difftastic will recursively walk the two directories, diffing files
with the same name.
with the same name.Difftastic会递归地浏览这两个文件对同名的文件进行差异分析。
The `--skip-unchanged` option is useful when diffing directories that
contain many unchanged files.
contain many unchanged files.当对比的文件夹之间许多未改变的文件时,`--skip-unchanged`选项将会十分有用。
## Language Detection
## Language Detection语言检测
Difftastic guesses the language used based on the file extension, file
name, and the contents of the first lines.
name, and the contents of the first lines.Difftastic根据文件的扩展名、文件名和第一行的内容来猜测所使用的语言。
You can override the language detection by passing the `--language`
option. Difftastic will treat input files as if they had that
extension, and ignore other language detection heuristics.
extension, and ignore other language detection heuristics.你可以通过`--language`选项来覆盖语言检测。如果输入的文件有所设定的后缀Difftastic将会处理它们并且忽略其他语言。
```
$ difft --language cpp before.c after.c
```
## Options
## Options选项
Difftastic includes a range of configuration CLI options, see `difft
--help` for the full list.
Difftastic includes a range of configuration CLI options, see `difft --help` for the full list.Difftastic包括一系列的命令行选项见`difft --help`获得完整列表。
Difftastic can also be configured with environment variables. These
are also visible in `--help`.
are also visible in `--help`.Difftastic也可以用环境变量进行配置。这些可以在`--help`中看到。
For example, `DFT_BACKGROUND=light` is equivalent to
`--background=light`. This is useful when using VCS tools like git,
where you are not invoking the `difft` binary directly.
where you are not invoking the `difft` binary directly.例如,`DFT_BACKGROUND=light`就相当于`--background=light`。这在使用VCS工具例如git的时候会很有用因为此时无法直接调用`difft`二进制文件。