Your first comparison

This tutorial compares two releases of a window, a user object, a menu and a DataWindow, and then takes the noise out of a comparison. It uses the Order Desk examples installed with pb-diff, so every step can be followed exactly, and it gives the pb-diff-cli command that does the same without a window.

The Order Desk examples

Order Desk is a small made-up order-entry application: a window to enter orders, a customer lookup, a DataWindow of order lines, a menu, and a few non-visual objects for prices, taxes and invoices. It exists in three releases. Release 1.4 is the baseline, release 1.5 changes most of its objects, and release 1.6 is the same application as a PowerBuilder 2025 Solution with one more change.

The files are in the docs\examples\order-desk folder of the installation. They are exports, libraries and Solution sources exactly as PowerBuilder writes them, but you do not need to import them anywhere: they are there to be compared. Every tutorial in this Help says which files to open, shows the window it produces, and gives the equivalent pb-diff-cli command with a link to its result. Run those commands from the docs\examples\order-desk folder, with pb-diff-cli on your PATH or by its full path.

The pictures were taken with the folder copied to C:\pb-diff-demo, the application's default settings and the Light theme, which is why their paths start there. Copy the folder there if you want the same paths, or anywhere else if you do not: the installation folder under Program Files cannot be written to, and some tutorials save files.

Folder	What it holds
`old`, `new`	Release 1.4 and release 1.5 of every object, as exported `.sr*` files
`libraries`	The same two releases as `orders.pbl` libraries
`solution`	Release 1.5 and 1.6 as PowerBuilder 2025 Solutions
`three-way`	`n_pricing` as two developers changed it from one Base
`datawindow`, `whitespace`, `rename`, `temporary`, `formats`	Inputs for one example each
`merge`, `report`, `selection`	What the desktop application saved in the examples
`results`	The JSON each `pb-diff-cli` command in this Help prints

Compare two releases of a window

Start pb-diff and choose Compare ▸ New Comparison (Ctrl+N). Leave it on Two-way comparison.
Give it old/w_order_entry.srw as Old and new/w_order_entry.srw as New, by typing, by browsing, or by dragging them onto the dialog. Old is the reference: results are phrased as what happened to it. The dialog checks the two paths as you give them, so Compare is enabled only when they can be compared.
Choose Compare. A File Compare tab opens: the object's hierarchy on the left, the two versions side by side on the right.

The pb-diff New Comparison dialog over an empty application window. Two-way comparison is selected at the top; the Old box holds w_order_entry.srw from the old folder of the Order Desk examples and the New box the same object from the new folder, each with a Browse button, and a button with two arrows beside them that swaps the two; the Recent list below shows the orders.pbl library pair and the n_order_service pair; Compare and Cancel buttons close the dialog. — The New Comparison dialog with Two-way comparison chosen: release 1.4 of w_order_entry as Old and release 1.5 as New, and two earlier pairs under Recent. Compare is enabled because the dialog has nothing to object to. Select the image to view it at full size.

Select wf_total under Functions. The comparison finds two new items, four modified, one deleted and twelve unchanged. In wf_total the new release refuses a discount outside the new id_max_pct limit, skips cancelled lines, rounds the total instead of truncating it, loses a leftover debug message, and shows the total through the new wf_show_total. The deleted wf_preview and the two new functions are in the same tree, each marked. The twelve unchanged items are not: Only Changed Items is on when a comparison opens, and clearing it brings them back.

Walk the changes with Alt+↓ and Alt+↑: they step through the changes inside the item you are on, then move on to the next changed item. The strip down the right edge is a map of the whole object, with deletions on the left of the strip, modifications in the middle and additions on the right; click it to go there.

pb-diff comparing two versions of the PowerBuilder window w_order_entry. The hierarchy tree on the left, with Only Changed Items on as every comparison opens, lists the changed variables, prototypes, functions and the cb_save control with their change markers, and the function wf_total is selected. The Old and New panes show that function side by side: green added lines that reject an out-of-range discount and skip cancelled order lines, a red deleted debug message line, and yellow modified lines where Truncate becomes Round and the total display moves to a new function. — Two versions of the w_order_entry window compared structurally. The hierarchy on the left opens on the changed items only, and the selected function wf_total is shown Old beside New, with its added, deleted and modified lines marked. Select the image to view it at full size.

Now switch on Only Changed Lines as well, the second tick box in the tool bar. The panes keep the changed lines with a few lines of context around them; the rest folds away behind a line saying how much it hides. Click it to unfold it.

pb-diff showing the w_order_entry comparison with the Only Changed Items and Only Changed Lines filters on. The tree lists only the changed variables, prototypes, functions and the cb_save control, and the panes of wf_total show only the changed lines and a little context around them. — The same comparison with Only Changed Lines switched on as well: the panes keep the changed lines with a few lines of context, as the tree keeps the changed nodes. Select the image to view it at full size.

The same comparison without a window returns exit code 1, which means differences were found (result):

pb-diff-cli compare old/w_order_entry.srw new/w_order_entry.srw --format json

Everything the tab can do is described in File Compare.

A changed signature

Compare old/n_order_service.sru with new/n_order_service.sru and select of_price. Release 1.5 added a quantity parameter, ai_qty, and a volume discount. pb-diff pairs the old and the new signature as one modified function, so the change is read in place; the signature strip under the panes shows both signatures. This is Automatically sync modified function and event names, which is on by default.

pb-diff comparing two versions of the user object n_order_service. The function of_price is selected and marked modified; the signature strip below the panes shows the old signature with one decimal argument and the new one with an added integer quantity, and the panes show the new volume-discount line. — of_price gained a quantity parameter. pb-diff pairs the old and new signatures as one modified function, so the change is read in place rather than as a deletion and an addition. Select the image to view it at full size.

pb-diff-cli compare old/n_order_service.sru new/n_order_service.sru --format json

The result reports the function as modified, not as one deleted and one new.

Compare old/m_order_desk.srm with new/m_order_desk.srm. Release 1.5 replaced the Print preview item with Export invoices. Each menu item is a node with its properties and its scripts, so the tree shows m_printpreview deleted and m_exportinvoices new, and the item's clicked script can be read on its own.

pb-diff comparing two versions of the menu m_order_desk. The tree shows the menu items under m_orders: m_printpreview marked deleted and m_exportinvoices marked new, and the clicked script of the new item is selected, shown in green in the New pane. — In the m_order_desk menu, the Print preview item was removed and an Export invoices item added. Each item is a node with its own properties and scripts. Select the image to view it at full size.

pb-diff-cli compare old/m_order_desk.srm new/m_order_desk.srm --format json

(result)

A DataWindow

Compare old/d_order_lines.srd with new/d_order_lines.srd. Under the Table properties, select retrieve: the retrieve SQL is its own node, and the one added line, AND status <> 'X', leaves cancelled order lines out. The SQL is displayed, not executed.

pb-diff comparing two versions of the DataWindow d_order_lines. The tree shows only the changed parts of the DataWindow, its overview, the detail band and the data source, and the retrieve property of the table is selected: the query is shown on both sides, with one added line that filters out cancelled order lines. — The retrieve SQL of the d_order_lines DataWindow is a node of its own. The new version excludes cancelled lines, and the added condition is the only highlighted line. Select the image to view it at full size.

Then expand the line_amount column and select its format property. The display format gained a red section for negative amounts, and that is the only difference in the column.

pb-diff comparing two versions of the DataWindow d_order_lines with the format property of the line_amount column selected: the old format and the new format with a red negative section are shown side by side, and the tree holds only the parts of the DataWindow that changed: this format and the retrieve of its data source. — Every DataWindow attribute is its own node. Of the line_amount column only the display format changed, to show negative amounts in red, and that one property is selected. Select the image to view it at full size.

A line like that one can run to three hundred characters. Press Ctrl+L on it to send the pair to a Line Compare tab, which stacks the two versions and shades only what changed.

pb-diff-cli compare old/d_order_lines.srd new/d_order_lines.srd --format json

(result)

Take the noise out

Some differences are artefacts rather than edits. Three options that suppress this noise are on by default. If you see one of these symptoms, check whether its option has been turned off, in Tools ▸ Options:

What you are seeing	What to change
Indentation-only or trailing-space differences	Ignore whitespace, which is off by default
A DataWindow full of attribute differences after a PowerBuilder upgrade	Normalise DataWindow attribute name case and Normalise DataWindow unquoted attribute case, both on by default
A function reported as deleted plus added after a parameter was added	Automatically sync modified function and event names, on by default
Two unrelated lines shown as a modification of one another	Raise the Resync distance threshold
A long run of lines shown as one deletion and one addition where a modification would read better	Lower the Resync distance threshold
XML differing only in attribute order, namespace prefixes or comments	The XML ignores
Indentation that does not line up the way it does in PowerBuilder	Tab size, on the Text settings page

An ignore affects the comparison only. The text shown for each side is always what is in the file, and text that was excluded from the comparison is shaded so you can see it was not compared.

Try one. Compare whitespace/old/n_tax.sru with whitespace/new/n_tax.sru and select of_vat. The second file indents with spaces instead of tabs and has trailing blanks; its code is otherwise unchanged. With Ignore whitespace off, the function is modified.

pb-diff comparing two versions of n_tax whose only change is indentation and trailing spaces: the function of_vat is marked modified and several lines are highlighted. — n_tax was re-indented with spaces and gained trailing blanks. With Ignore whitespace off, those lines are differences. Select the image to view it at full size.

Choose Tools ▸ Options, select Text compare in the list on the left, tick Ignore whitespace and press OK.

The pb-diff Options dialog over the n_tax comparison. The list of option groups is on the left with Text compare selected; the page on the right shows the text compare options, with Ignore whitespace ticked, and OK and Cancel buttons at the bottom. — The Options dialog on its Text compare page, with Ignore whitespace ticked. Pressing OK compares the open n_tax comparison again. Select the image to view it at full size.

The open comparison compares again at once and is now identical. The panes still show the original text, and they shade the differences that were excluded from the comparison.

pb-diff comparing the same two versions of n_tax with Ignore whitespace on: the comparison is identical, the tree shows no changes, and the panes show the original indentation with the ignored differences shaded. — With Ignore whitespace on, the same comparison is identical. The panes still show the original text, and the ignored differences are shaded. Select the image to view it at full size.

These commands return exit codes 1 and 0 (before, ignored):

pb-diff-cli compare whitespace/old/n_tax.sru whitespace/new/n_tax.sru --format json
pb-diff-cli compare whitespace/old/n_tax.sru whitespace/new/n_tax.sru --ignore-whitespace --format json

Neither command rewrites the input files. Ignoring a difference changes the comparison, not the source that you copy or save.