Framework
ra1028/DifferenceKit avatar
ra1028/DifferenceKit

DifferenceKit splits diffs into stages because batch updates crash

💻 A fast and flexible O(n) difference algorithm framework for Swift collection.

3,668 stars243 forksSwiftApache-2.0

At a glance

What is it?
DifferenceKit computes linear-time diffs for Swift collections and then cuts them into stages, because some combinations of insert, delete, move and update make UIKit crash when applied at once. The algorithm came from a 1978 paper and the staging rule lives in one file.
Who is it for?
DifferenceKit is worth adopting when a list interface needs animated batch updates and the data model can supply a stable identifier per element, since the identifier is what the whole algorithm hangs on. Do not adopt it on the strength of the fastest claim in its feature list, which its own comparison section declines to support.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 145 days ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • ra1028/DifferenceKit3,668 ★ · +0
Star history
Repository2026-09-242026-11-14
ra1028/DifferenceKit3.7k3.7k

0 Stars in the last 51 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A 1978 paper and a stage splitter are the whole design

The algorithm section is short and it credits two things. The diffing algorithm was developed for Carbon, the author's other project, and works standalone, and it is optimized based on Paul Heckel's algorithm, whose paper A technique for isolating differences between files came out in 1978. That paper is what allows all kinds of diffs to be calculated in linear time, and the file notes that RxDataSources and IGListKit are also implemented based on it, so the lineage is shared rather than unique. The part that belongs to this project is the second half of the paragraph. In performBatchUpdates of UITableView or UICollectionView there are combinations of diffs that cause a crash when applied simultaneously, and the approach here is to split the set of diffs at the minimal stages that can be performed with no crashes. The implementation is a single file, Sources/Algorithm.swift.

The feature list says fastest and the comparison disclaims it

The two halves of this README pull in opposite directions. The Features section opens with a bullet calling it the fastest O(n) diffing algorithm optimized for Swift collection, and the Algorithm section supports that only in the sense of linear time. Two sections later, the comparison section states that it does NOT determine superiority or inferiority of the frameworks and that each framework has different benefits, after promising a fair comparison as much as possible in performance and features. So the superlative is asserted once and then declined. The comparison itself is a versioned list: DifferenceKit at master, RxDataSources 4.0.1, FlexibleDiff 0.0.8, IGListKit 3.4.0, DeepDiff 2.2.0, Differ 1.4.3, Dwifft 0.9 and Swift.CollectionDifference at Swift 5.1. Note what DifferenceKit is measured as: master, not a release, which is the one entry in the list without a version number next to it.

The newest tag is 1.3.0 from June 2022

There is a gap between what the repository contains and what is published. The three most recent releases are 1.3.0 on 2022-06-24, 1.2.0 on 2021-06-08 and 1.1.5 on 2020-01-14, a cadence of roughly one release a year that then stops. The default branch is master and its most recent push is dated 2026-06-23, four years after the last tag. So the code being read on master is not the code a Carthage or CocoaPods consumer installs, and the benchmark that produces the performance comparison is run against master while its competitors are pinned to numbered versions. Anyone reproducing those numbers has to decide which side of that gap to stand on. The distribution channels are also three: the podspec for CocoaPods, the Carthage badge, and Swift Package Manager, and the documentation is a separate artifact published from a generated site.

Updating the data source outside the closure crashes the table

One warning in this README is written in capital letters and it is the most common way to break a list screen. The diffs are applied in stages, so the data referenced by the data source has to be updated synchronously with the data passed into the setData closure, and failing to do so is bound to create a crash. The shape is short:

swift
tableView.reload(using: changeset, with: .fade) { data in
    dataSource.data = data
}

The reason follows from the design in the first section. Because the changeset is a sequence of stages rather than one batch, the data source is read again between stages, and if it still describes the old collection while the table has already applied stage one, the indices no longer line up. The animation argument is not incidental here either, since with: .fade is what makes the staged transitions read as one update. Any code that assigns dataSource.data before calling reload, or assigns it after the closure returns, reintroduces exactly the crash the staging exists to prevent.

The interrupt closure is the only way out of a huge batch

There is a second escape hatch and it exists because staging multiplies the work. The file says batch updates using too large an amount of diffs may adversely affect performance, and the remedy is an interrupt closure that returns true to fall back to reloadData:

swift
collectionView.reload(using: changeset, interrupt: { $0.changeCount > 100 }) { data in
    dataSource.data = data
}

So the animation degrades to a full reload once the changeset passes a threshold the caller chooses, and 100 is the example rather than a default, since the option is written as a comparison against changeCount. That is a tuning decision with a visible cost: above the line the user sees a reload instead of a transition, below it the run is slower. It is also the honest admission that the linear-time diff does not remove the cost of applying the result, since the applying is where the linear work turns into thousands of individual row operations. A list that changes wholesale on every keystroke is the case this parameter exists for.

Four manifests describe the same library

The tree carries more than one way to declare the package. Package.swift is the modern SwiftPM manifest, [email protected] is a version-specific manifest for older toolchains, and DifferenceKit.podspec is the CocoaPods one, which means the same sources are described for three package managers. A fourth declaration sits in a nested directory: the Makefile runs swift-mod through a package under Packages with swift run -c release --package-path ./Packages swift-mod, and a companion mod-check target passes --check. So the repository contains a Swift package whose job is to manage dependencies of the library package. The tooling around all of this is Ruby: Gemfile and Gemfile.lock are present, and the docs target runs bundle exec jazzy --config .jazzy.yaml to generate the API site, while lib-lint runs pod lib lint before a release.

Linux tests run in a swift:latest container

The Linux path is a Makefile target and it is pinned to nothing:

code
docker run -v `pwd`:`pwd` -w `pwd` --rm swift:latest swift test

The image tag is latest, so the Swift version used to run the Linux test suite is whatever that tag currently points at, which is the opposite of how a library that still ships [email protected] is usually pinned. Alongside it, generate-linuxmain runs swift test --generate-linuxmain and LinuxMain.swift sits at the repository root, which is the older SwiftPM convention where the Linux test entry point is a separate file rather than something discovered automatically. A .swift-version file and .swiftlint.yml are also present, so the project records a preferred local version and a lint configuration even though the container that runs its Linux tests follows a floating tag. The same mismatch shows in the local Swift toolchain: the file is generated by a command whose name still carries the word generate.

Hound, jazzy, SwiftLint and a podspec share one repository

The root directory lists the services a small Swift library of this vintage tends to accumulate. .hound.yml configures Hound, the hosted review bot, and .swiftlint.yml configures SwiftLint for local linting. .jazzy.yaml drives the documentation generator invoked by the docs-gen target. .swift-mod.yml sits next to Package.swift for the dependency tool, and the Gemfile exists to install that Ruby tooling with bundle config path vendor/bundle and bundle install --jobs 4 --retry 3. Examples/ holds three application targets, Example-iOS, Example-macOS and Example-tvOS, and there is a DifferenceKit.playground directory whose Contents.swift is linked as the playground entry. That is a repository carrying its examples, its benchmarks, its documentation generator, three package manifests and a Linux container harness for one algorithm file, which says as much about the project's shape as the algorithm does.

Editorial conclusion

DifferenceKit is worth adopting when a list interface needs animated batch updates and the data model can supply a stable identifier per element, since the identifier is what the whole algorithm hangs on. Do not adopt it on the strength of the fastest claim in its feature list, which its own comparison section declines to support. Before wiring it in, read three things: the setData closure, because assigning the new data anywhere else crashes the table; the interrupt threshold, because a large changeset degrades into a full reload; and the release history, where the newest tag is 1.3.0 from June 2022 while the default branch has moved since.

Frequently asked questions

How does the DifferenceKit diff algorithm work?

It is optimized based on Paul Heckel's algorithm, whose paper A technique for isolating differences between files was released in 1978, which allows all kinds of diffs to be calculated in linear time. DifferenceKit then splits that set of diffs into the minimal stages that can be applied with no crashes, and the implementation is in Sources/Algorithm.swift.

What must a type conform to for DifferenceKit to diff it?

The Differentiable protocol, which requires a differenceIdentifier whose type is a generic associated type and an isContentEqual method. Default implementations exist for Equatable and Hashable types, so a line like extension String: Differentiable is enough.

How do you apply a DifferenceKit changeset to a table view?

Create a StagedChangeset from the source and target collections and pass it to reload, assigning the new data inside the closure passed to reload. The README warns that the data source must be updated synchronously with the data in that closure, because the diffs are applied in stages and failing to do so creates a crash.

What does the interrupt closure in DifferenceKit do?

It decides when to give up on animated batch updates. Returning true falls back to reloadData, and the example compares changeCount against 100. The README notes that batch updates using too large an amount of diffs may adversely affect performance.

Which versions of other diff frameworks does DifferenceKit compare against?

RxDataSources 4.0.1 through its Differentiator, FlexibleDiff 0.0.8, IGListKit 3.4.0, DeepDiff 2.2.0, Differ 1.4.3 through Diff.swift, Dwifft 0.9 and Swift.CollectionDifference at Swift 5.1, with DifferenceKit itself measured at master rather than at a release.

How are DifferenceKit tests run on Linux?

Through a Makefile target that runs swift test inside a swift:latest Docker container with the working directory mounted. A separate generate-linuxmain target produces LinuxMain.swift, which sits at the repository root, and a .swift-version file records the preferred local toolchain.

Official sources

  1. License: Apache-2.0
  2. Project website
  3. ra1028/DifferenceKit on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/ra1028-differencekit.svg)](https://hysenlabs.com/projects/ra1028-differencekit)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/ra1028-differencekit.svg)](https://hysenlabs.com/projects/ra1028-differencekit)

Was this useful?