Human-readable patch format

Version:

0.2

This page describes the human-readable patch format generated by "ssdiff --format-human". There is an alternate patch format which is readable as a CSV file (see CSV DTBL diff format), and which is currently better supported and better documented.

General structure

A file consists of a series of blocks separated by blank lines:

block0 line0
block0 line1

block1 line0

block2 line0
block2 line1
block2 line2

First block

The first block must begin at the start of the file, with no initial blank lines, and has the following format:

• The first four characters are "dtbl"
• The first line contains the text "human-readable"
• The first line contains the sequence "version [^ ,]+"
• The remainder of the block is unspecified.

Here's an example of a first block:

dtbl: table difference format version 0.2, human-readable flavor
This format should be considered unstable until 1.0

Remaining blocks

The remaining blocks describe properties and transformations of a table. Transformations assume that the blocks are considered in order from the beginning of the file to the end.

Blocks have a type. The type is specified in the first line of a block. The first line has the following format (perl-style regular expression):

 [^a-zA-Z]*([a-zA-Z ]+)

This part in parentheses identifies the block type. Removing leading and trailing whitespace, normalizing internal whitespace to since spaces, and transforming to lowercase, the type should have one of the following prefixes:

• original column names
• insert column
• delete column
• move column
• column names
• insert row
• delete row
• update row

There may be other text after these prefixes. Here's an example block:

original column names are: [0], [1], [2], [3]

Here's another:

move column: [0]
  before [0] [1] [2] [3]
  after  [1] [0] [2] [3]

original column names

If any "insert/delete/move column" blocks are present in the file, this block will also be present. If present, it will appear before any "insert/delete/move column" blocks. This list gives labels for each column of a reference table. The labels should be treated as arbitrary.

After the first ":" symbol on the first line of this block, there will be a whitespace-separated list of names. This list can be parsed by the following rules:

• Quoting is CSV style.
• Spaces outside of quotes should be ignored.

For example, the block:

original column names are: [0] [1] [2] [3]

implies the list of names "[0]", "[1]", "[2]", and "[3]".

column names

This block is just like the "original column names", but appears after all "insert/delete/move column" blocks (if there are any). It summarizes the column names after all column manipulations have taken place.

move column

This block specifies the movement of a single column. This block has a second and third line, containing whitespace-separated lists after the tags "before" and "after" respectively. For example:

move column: [2]
  before [1] [0] [2] [3]
  after  [1] [0] [3] [2]

Comparing the "after" list with the "before" list shows which column was moved, and where.

insert column

This block specifies the insertion of a single column. It has the same format as the "move column" block. Comparing the "after" list with the "before" list shows which column was inserted, and where. The column will have been assigned a label, which should be treated as arbitrary. Example:

insert column: {2}
  before [1] [0]
  after  [1] [0] {2}

delete column

This block specifies the removal of a single column. It has the same format as the "move column" block. Comparing the "after" list with the "before" list shows which column was removed.

delete column: [2]
  before [0] [1] [2] [3]
  after  [0] [1] [3]

insert row

documentation pending, run ssdiff and guess :-)

delete row

documentation pending, run ssdiff and guess :-)

update row

documentation pending, run ssdiff and guess :-)