Skip to content

Commit b8d6e35

Browse files
SimonSchubertSimonSchubert
committed
Add commands
1 parent 99355e4 commit b8d6e35

2 files changed

Lines changed: 164 additions & 0 deletions

File tree

‎assets/commands/codediff.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# TAGLINE
2+
3+
Syntax-aware structural code diff
4+
5+
# TLDR
6+
7+
Open the **interactive viewer** (press **o** to pick files, **?** for keys)
8+
9+
```codediff```
10+
11+
Diff **two files** in the TUI
12+
13+
```codediff [old.rs] [new.rs]```
14+
15+
Print a **plain-text** diff (also used when stdout is not a terminal)
16+
17+
```codediff --headless [old.rs] [new.rs]```
18+
19+
Emit **JSON** for an editor integration
20+
21+
```codediff --mode json [old.rs] [new.rs]```
22+
23+
Configure as **git's difftool** (interactive wizard)
24+
25+
```codediff git configure```
26+
27+
Drive **git diff** / **git log -p** through codediff (always non-interactive)
28+
29+
```GIT_EXTERNAL_DIFF=codediff git diff```
30+
31+
Open on the **git review picker** (unstaged, staged, recent commits)
32+
33+
```codediff --review```
34+
35+
Exit **1** when the files differ (diff(1) convention; headless and JSON only)
36+
37+
```codediff --headless --exit-code [old.rs] [new.rs]```
38+
39+
# SYNOPSIS
40+
41+
**codediff** [_options_] [_before_ _after_]
42+
43+
**codediff** **git** **configure**
44+
45+
**codediff** **jj** **configure**
46+
47+
**codediff** **util** **completions** _shell_
48+
49+
**codediff** **util** **man**
50+
51+
# PARAMETERS
52+
53+
_before_ _after_
54+
> Files to diff. Also accepts git's 7- or 9-argument **GIT_EXTERNAL_DIFF** list (`path old-file old-hex old-mode new-file new-hex new-mode [new-path score]`). With no paths the TUI starts empty.
55+
56+
**--mode** _tui_|_headless_|_json_
57+
> How to show the diff. Default **tui**. **headless** and **json** need two files. **headless** is also chosen when stdout is not a terminal; **json** never is.
58+
59+
**--headless**, **--batch**
60+
> Shorthand for **--mode headless**. Conflicts with **--mode**.
61+
62+
**--minimal**
63+
> Paint only ranges that carry meaning (the TUI **M** panel's Minimal preset). Applies for this run only and is not saved. Conflicts with **--full**.
64+
65+
**--full**
66+
> Paint the fullest reading (the **M** panel's Full preset, except whole-pair updates). This run only.
67+
68+
**--whole-updates**
69+
> Highlight an updated node's matched pair as a whole, not only the part that differs. Combines with **--minimal** / **--full**.
70+
71+
**--paint-reindent-moves**
72+
> Paint a node as moved even when only indentation changed. Turns that **M** panel option on for this run.
73+
74+
**--color** _auto_|_always_|_never_
75+
> When to ANSI-color headless output. Default **auto**: color unless **NO_COLOR** is set (even when stdout is a pipe, so git's pager shows color). **always** and **never** override **NO_COLOR**.
76+
77+
**--exit-code**
78+
> Exit **1** when the files differ (**0** identical, **2** on error). Headless and JSON only. Off by default: version-control tools treat a non-zero exit from a display tool as a failure. Ignored under git's **GIT_EXTERNAL_DIFF** argument form.
79+
80+
**--context** _N_
81+
> Unchanged lines to keep around each change in headless output, like **diff -U**. Default **3**.
82+
83+
**--review**
84+
> Open the TUI on the git review picker for the repository around the current directory. TUI only; takes no file pair. Conflicts with paths, **--headless**, and **--mode**.
85+
86+
**git configure**
87+
> Interactive wizard that writes **difftool.codediff.cmd**, optionally **diff.tool** / **difftool.prompt**, and optionally **diff.external**. Needs a terminal on stdin.
88+
89+
**jj configure**
90+
> Interactive wizard that registers codediff as a jj merge tool with **diff-invocation-mode** **file-by-file**, and optionally sets **ui.diff-formatter**.
91+
92+
**util completions** _shell_
93+
> Print a completion script for **bash**, **zsh**, **fish**, **elvish**, or **powershell** on stdout.
94+
95+
**util man**
96+
> Print a roff man page (section 1) on stdout.
97+
98+
**-h**, **--help**
99+
> Print usage and exit.
100+
101+
**-V**, **--version**
102+
> Print the version and exit.
103+
104+
# DESCRIPTION
105+
106+
**codediff** compares two files by parsing them with tree-sitter and matching their syntax trees, so a change is reported as an insertion, deletion, update, or move rather than as whichever lines happened to align. It is a command-line tool: an interactive two-panel TUI, a numbered plain-text formatter, or a JSON emitter for editors.
107+
108+
Language is taken from the file extension. Twenty-four languages are parsed with a compiled grammar (C, C++, C#, CSS, Go, HTML, Java, JavaScript, JSON, Kotlin, Lua, PHP, Python, R, Ruby, Rust, Scala, Bash, Swift, TSX, TypeScript, Vimscript, XML, YAML). An unknown extension is diffed as plain text. Bazel, Dart, Emacs Lisp, Markdown, Protocol Buffers, and SQL are recognised by extension but still diffed as text.
109+
110+
With no arguments, the TUI starts empty. Press **o** to pick each file, **?** for keybindings, **G** for the git review picker, and **M** for render options. **--review** is the same as **G** at startup. The TUI uses 24-bit color when the terminal sets **COLORTERM=truecolor**, otherwise the nearest 256 colors.
111+
112+
**--headless** (alias **--batch**) prints the diff as text. Headless mode also starts whenever stdout is not a terminal, so `codediff BEFORE AFTER | less` and `GIT_EXTERNAL_DIFF=codediff git diff` work without the flag. Each printed line is prefixed with its line number. Long unchanged runs are collapsed. Each hunk is prefixed with the nearest enclosing function, class, or struct line when that line is not otherwise visible. Binary files print `Binary file <path> differs` and do not fail the rest of a git diff.
113+
114+
**--mode json** prints one JSON object: each side has a path, a detected language, and hunks with an operation (`delete`, `insert`, `update`, `move`) and a 0-indexed range (rows; columns are byte offsets). JSON is never chosen automatically.
115+
116+
Exit **0** on success and **2** on error. Pass **--exit-code** to get **1** when the files differ.
117+
118+
`codediff git configure` sets git to use codediff as **git difftool**. `git diff` and `git log -p` never open the TUI: git pipes through a pager, so codediff always falls back to text there. For the interactive viewer from git, use **git difftool**. `codediff jj configure` registers **jj diff --tool codediff**. jj has no equivalent of git difftool's per-file TUI, so for the full-screen viewer on a jj repo run **codediff** on two files directly.
119+
120+
# CONFIGURATION
121+
122+
**$CODEDIFF_CONFIG**
123+
> If set and non-empty, this file is the only config used.
124+
125+
**.codediff.toml**
126+
> Nearest existing file at or above the current directory. Never created automatically.
127+
128+
**$XDG_CONFIG_HOME/codediff/config.toml**
129+
> User config (or **$HOME/.config/codediff/config.toml**). Holds TUI theme, panel layout, recent pairs, custom palette, syntax theme, node highlight, and render options (the **M** panel). **--minimal** / **--full** override render options for one run and are not saved.
130+
131+
**difftool.codediff.cmd**, **diff.tool**, **diff.external**
132+
> Written by **codediff git configure** (git config, global or local).
133+
134+
**merge-tools.codediff.***, **ui.diff-formatter**
135+
> Written by **codediff jj configure** (jj config, user or repo). **diff-invocation-mode** must be **file-by-file**.
136+
137+
# CAVEATS
138+
139+
Licensed **AGPL-3.0-or-later**. A commercial license is sold separately for organisations that cannot use AGPL software.
140+
141+
A source build (`cargo install --locked codediff`) needs rustc **1.88** or later and a C compiler; the first install compiles every tree-sitter grammar and takes several minutes. The crate's default features include the TUI binary.
142+
143+
The first positional path cannot be a file literally named **git**, **jj**, or **util** (those are subcommands).
144+
145+
**--exit-code** is ignored in the 7-argument **GIT_EXTERNAL_DIFF** form: git treats a non-zero exit there as fatal and aborts the whole diff.
146+
147+
# HISTORY
148+
149+
Written by **Marko Ivankovic**. First user release **0.1.0** (2026-09-25); **0.1.1** (2026-09-27) dropped the bundled browser front end in favour of the separate **codereview** project.
150+
151+
# SEE ALSO
152+
153+
[diff](/man/diff)(1), [git-diff](/man/git-diff)(1), [git-difftool](/man/git-difftool)(1), [git-log](/man/git-log)(1), [jj](/man/jj)(1), [delta](/man/delta)(1), [difft](/man/difft)(1), [colordiff](/man/colordiff)(1)
154+
155+
# RESOURCES
156+
157+
```[Source code](https://github.com/ivankovic/codediff)```
158+
159+
```[Homepage](https://ivankovic.github.io/codediff/showcase/)```
160+
161+
```[Documentation](https://github.com/ivankovic/codediff/blob/main/README.md)```
162+
163+
<!-- verified: 2026-09-30 -->

‎assets/commands/index.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1308,6 +1308,7 @@ codealmanac.md
13081308
codeburn.md
13091309
codecov.md
13101310
codecrafters.md
1311+
codediff.md
13111312
codeflowmap.md
13121313
codeknow.md
13131314
codemod.md

0 commit comments

Comments
 (0)