[IPython-dev] Heads-up for notebook users: on-disk format changes for version-control friendliness

[Fernando Perez]

Hi all,

in light of the recent discussion [1] on using notebooks in
version-controlled environments, we've made three changes to the
on-disk format that should help a lot:

1. The most important one: text fields like cell inputs or printed
outputs that were multi-line are now saved as separate lines in the
JSON file.  This means that when you change one line in a 10 line
cell, the diff will now show only that line changed, instead of a
change in the entire cell (which before, was stored as  a big string
with embedded \n characters).

2. Fields are always sorted now, so no more spurious diffs due to
field reordering.

3. Each json level only indents one space instead of 4, which makes
the files actually much more readable (json introduces new indentation
levels a lot, so 4 spaces per level was pushing the actual content far
to the right of the file).


These changes should help a lot anyone sharing notebooks with
colleagues over git or other version control system, but it means that
if you update to master, you should also tell your colleagues to
update.  The changes are applied transparently when you first save
your notebooks, but if your colleague doesn't have the updated
version, he or she won't be able to read the files anymore.

Sorry for the hassle this may introduce, but we think the benefits are
significant enough to warrant this.  And that's why they call it the
bleeding edge, we still haven't officially released :)

Anyone interested in the details can see the pull request [2] where we
discussed the changes.

Cheers,

f

[1] http://mail.scipy.org/pipermail/ipython-dev/2011-November/008351.html
[2] https://github.com/ipython/ipython/pull/981