dover

dover (diff overview) is a CLI tool for summarizing git diffs of Rust code. dover diffs provide a semantic, high-level overview of the changes tracked by git.

Note

While usable, this project is very prototype-y, both in terms of output format and implementation. Updates are made regularly, but it's still in the early stages. See the roadmap for planned features and changes.

Installation

If you're building from source or using cargo, you'll need a recent version of Rust, which you can get here.

Using cargo

cargo install dover

Building from source

1. Clone the repository

git clone git@github.com:bferris413/dover.git

2. Build the application

cd dover && cargo build --release

Usage

The main entry point is the diff subcommand, meant to emulate the behavior of git diff:

# like git diff [c1 [c2]]
dover diff [c1 [c2]]

If present, c1 and c2 must be valid commit SHAs. Support is planned for branch names, refnames like HEAD, and selections like HEAD~2.

See dover --help for all supported commands.

✅ TODO

• structs
• enums
• traits
  • signatures
  • functions
  • const
  • macro
  • type declarations
• functions - standalone
• modules
• use statements
• impl blocks
  • functions
  • const
  • macro
  • type declarations
• attributes
• user config (dover.toml)

FAQ

Q: What's the intended use case?

A: dover works nicely when you're looking for a high-level overview of the changes between two commits, or when you want to summarize a set of changes before getting into the nitty-gritty of a full diff (like when reviewing a large PR).

Q: Does dover replace git?

A: No, dover doesn't do any versioning or source control. It's an optional supplement to reading large git diffs.

Q: How does it work?

A: dover has two major dependencies: git2 for reading git repositories and syn for parsing Rust source files. For each added, modified, or removed file in a git diff, dover uses syn to parse the source and collect an opinionated subset (the "overview") of the AST. The overview ASTs are then compared and the resulting diff is printed.

Q: Why don't you include <this language feature> in diffs?

A: I probably just haven't gotten to that feature yet. As of 3397ad3a5a80c32b5ab9d29d955af5b1e77163b3, dover supports most parts of structs, enums, traits, function signatures, use statements, and impl blocks. See the roadmap for missing-but-planned items.

Q: Rust only?

A: Correct, no other languages are planned, for a couple reasons:

• This project is for me: my daily driver at work (and home) is Rust,
• This project is about exploring the idea of a "diff overview" rather than providing a general purpose implementation.

If you're interested in implementing the idea and want multi-language support, consider using tree-sitter for the parser.

Q: Don't semantic diffing tools already exist?

A: They sure do. While tools like difftastic, SemanticDiff, and DiffLens will provide a semantic diff of your code, dover's goal is to explore the idea of providing an opinionated, configurable overview of changes so you can get a glimpse of what's coming before diving into the full diff.