Skip to content

docs: add multi-file patch guidance #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bmwill merged 1 commit into from
Apr 21, 2026
Merged

docs: add multi-file patch guidance #78

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 85 additions & 6 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,15 @@
//! contents of those files into memory before passing their contents to the
//! apis provided by this library.
//!
//! ## Cargo Feature Flags
//!
//! This crate is `no_std` by default.
//! Enable [Cargo features] as needed:
//!
//! - `std` for writer-based formatting and `std::error::Error` impls

@bmwill bmwill Apr 21, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@weihanglo question for you on this one. We could theoretically bump the msrv up a bit more to:

  • get Error trait from core
  • update hashbrown to latest version
  • fix a few TODOs you have to use chunk apis
  • update to 2024 edition

Does cargo have a requirement for using a lower msrv? otherwise we can likely bump ours to fix the above. I've already checked the other biggest users of diffy on crates.io and they don't seem to be relying on a low msrv

@weihanglo weihanglo Apr 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cargo uses latest stable, so should be fairly fine with any MSRV bumps

@bmwill bmwill Apr 21, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll whip up a PR and put it up to see if it would be worth doing

//! - `color` for ANSI-colored patch formatting
//! - `binary` for applying parsed git binary patches
//!
//! ## UTF-8 and Non-UTF-8
//!
//! This library has support for working with both utf8 and non-utf8 texts.
Expand Down Expand Up @@ -146,6 +155,66 @@
//! assert_eq!(apply(base_image, &patch).unwrap(), expected);
//! ```
//!
//! ## Parsing Multi-File Patches
//!
//! The [`patch_set`] module provides support for parsing unified diffs
//! that contain changes to multiple files,
//! such as `git diff` and `git format-patch` output.
//! [`PatchSet`] is a streaming iterator,
//! so callers can process file patches one at a time.
//!
//! Use [`ParseOptions::gitdiff`] for git-style diffs or
//! [`ParseOptions::unidiff`] for plain unified diffs.
//!
//! ```
//! use diffy::apply;
//! use diffy::patch_set::FileOperation;
//! use diffy::patch_set::ParseOptions;
//! use diffy::patch_set::PatchSet;
//!
//! let input = "\
//! diff --git a/alpha.txt b/alpha.txt
//! index 1111111..2222222 100644
//! --- a/alpha.txt
//! +++ b/alpha.txt
//! @@ -1 +1 @@
//! -alpha
//! +ALPHA
//! diff --git a/beta.txt b/beta.txt
//! new file mode 100644
//! --- /dev/null
//! +++ b/beta.txt
//! @@ -0,0 +1 @@
//! +beta
//! ";
//!
//! let mut patches = PatchSet::parse(input, ParseOptions::gitdiff());
//!
//! let first = patches.next().unwrap().unwrap();
//! let second = patches.next().unwrap().unwrap();
//! assert!(patches.next().is_none());
//!
//! match first.operation().strip_prefix(1) {
//! FileOperation::Modify { original, modified } => {
//! assert_eq!(original, "alpha.txt");
//! assert_eq!(modified, "alpha.txt");
//! }
//! operation => panic!("unexpected operation: {operation:?}"),
//! }
//!
//! let text_patch = first.patch().as_text().unwrap();
//! assert_eq!(apply("alpha\n", text_patch).unwrap(), "ALPHA\n");
//!
//! match second.operation().strip_prefix(1) {
//! FileOperation::Create(path) => assert_eq!(path, "beta.txt"),
//! operation => panic!("unexpected operation: {operation:?}"),
//! }
//! ```
//!
//! With the `binary` Cargo feature enabled,
//! parsed multi-file patches can also contain [`BinaryPatch`] values.
//! You can apply them with [`BinaryPatch::apply`].
//!
//! ## Performing a Three-way Merge
//!
//! Two files `A` and `B` can be merged together given a common ancestor or
Expand Down Expand Up @@ -216,12 +285,22 @@
//! [Mercurial]: https://www.mercurial-scm.org/
//! [Unified Format]: https://en.wikipedia.org/wiki/Diff#Unified_format
//! [diff3]: https://en.wikipedia.org/wiki/Diff3
//!
//! [`Display`]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
//! [`Patch`]: struct.Patch.html
//! [`PatchFormatter`]: struct.PatchFormatter.html
//! [`create_patch`]: fn.create_patch.html
//! [`create_patch_bytes`]: fn.create_patch_bytes.html
//! [Cargo features]: https://doc.rust-lang.org/cargo/reference/features.html
//!
//! [`BinaryPatch`]: crate::binary::BinaryPatch
//! [`BinaryPatch::apply`]: crate::binary::BinaryPatch::apply
//! [`Display`]: core::fmt::Display
//! [`ParseOptions::gitdiff`]: crate::patch_set::ParseOptions::gitdiff
//! [`ParseOptions::unidiff`]: crate::patch_set::ParseOptions::unidiff
//! [`Patch`]: crate::Patch
//! [`PatchFormatter`]: crate::PatchFormatter
//! [`PatchKind::as_binary`]: crate::patch_set::PatchKind::as_binary
//! [`PatchSet`]: crate::patch_set::PatchSet
//! [`PatchSet::parse`]: crate::patch_set::PatchSet::parse
//! [`PatchSet::parse_bytes`]: crate::patch_set::PatchSet::parse_bytes
//! [`create_patch`]: crate::create_patch
//! [`create_patch_bytes`]: crate::create_patch_bytes
//! [`patch_set`]: crate::patch_set

// unconditionally define as no_std to have consistency on the prelude that is auto imported.
#![no_std]
Expand Down