From 4aa1c989a5810b2cf12a20b53942ce551ed339b0 Mon Sep 17 00:00:00 2001 From: Andy Stewart Date: Wed, 23 Jun 2010 11:47:56 +0100 Subject: [PATCH] Add info on diffing. --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index 0f1e4cca..00a1a931 100644 --- a/README.md +++ b/README.md @@ -220,6 +220,26 @@ You can also store any information you like from your controller. Just override Remember to add those extra columns to your `versions` table ;) +## Diffing Versions + +When you're storing every version of an object, as PaperTrail lets you do, you're almost certainly going to want to diff those versions against each other. However I haven't built a diff method into PaperTrail because I think diffing is best left to dedicated libraries, and also it's hard to come up with a diff method to suit all the different possible use cases. + +You might be surprised that PaperTrail doesn't use diffs internally anyway. When I designed PaperTrail I wanted simplicity and robustness so I decided to make each version of an object self-contained. A version stores all of its object's data, not a diff from the previous version. + +So instead here are some specialised diffing libraries which you can use on top of PaperTrail. + +For diffing two strings: + +* [htmldiff](http://github.com/myobie/htmldiff): expects but doesn't require HTML input and produces HTML output. Works very well but slows down significantly on large (e.g. 5,000 word) inputs. +* [differ](http://github.com/pvande/differ): expects plain text input and produces plain text/coloured/HTML/any output. Can do character-wise, word-wise, line-wise, or arbitrary-boundary-string-wise diffs. Works very well on non-HTML input. +* [diff-lcs](http://github.com/halostatue/ruwiki/tree/master/diff-lcs/trunk): old-school, line-wise diffs. + +For diffing two ActiveRecord objects: + +* [Jeremy Weiskotten's PaperTrail fork](http://github.com/jeremyw/paper_trail/blob/master/lib/paper_trail/has_paper_trail.rb#L151-156): uses ActiveSupport's diff to return an array of hashes of the changes. +* [activerecord-diff](http://github.com/tim/activerecord-diff): rather like ActiveRecord::Dirty but also allows you to specify which columns to compare. + + ## Turning PaperTrail Off/On Sometimes you don't want to store changes. Perhaps you are only interested in changes made by your users and don't need to store changes you make yourself in, say, a migration -- or when testing your application.