diff

Compares versions of a text-file element or a directory.

The rcleartool diff -g is not supported if you only install the VersionVault Remote Client. You need to install the native VersionVault installation that also includes the VersionVault Local Client.

Applicability

Product

Command type

VersionVault

cleartool subcommand

VersionVault Remote Client

rcleartool subcommand

Platform

UNIX®

Linux®

Windows®

Synopsis

  • Display differences graphically:
    diff –g/raphical [ –tin/y ] [ –hst/ack | –vst/ack ] [ –pre/decessor ]
    [ –opt/ions pass-through-opts ] pname ...
  • On UNIX® or Linux®, display differences nongraphically:
    diff [ –tin/y | –win/dow ] [ –ser/ial_format
    | –dif/f_format | –col/umns n ]

    [ –opt/ions pass-through-opts ] [ –pre/decessor] pname ...

  • On Windows®, display differences nongraphically:
    diff [ –ser/ial_format | –dif/f_format | –col/umns n ]
    [ –opt/ions pass-through-opts ] [ –pre/decessor] pname ...

Description

The diff command calls an element-type-specific program (the compare method for the type) to compare the contents of two or more file elements or two or more directory elements. Typically, the files are versions of the same file element.

You can also use this command to compare ordinary text files.

diff uses the type manager mechanism to determine how to compare the specified objects. For more information, see the type_manager reference page.

Text file comparison report format

Each difference is reported as one or more pairwise differences. For example, if three contributors all differ from the base contributor in a particular section, diff lists the file1-file2 difference, followed by the file1-file3 difference, followed by the file1-file4 difference.

Side-by-side file comparison report style

The default file-comparison report begins with a file summary, which lists all the input files and their assignments as file 1, file 2, and so on. If no differences are detected among the files, this listing is replaced by the message Files are identical.

The remainder of the report is a series of pairwise differences, each of which is preceded by a descriptive header line:

******************************** (file summary)
<<< file 1: util.c@@/main/1
>>> file 2: util.c@@/main/3
********************************
----------[after 15]------|-------[inserted 16]------
(header)
                          | char *s;        (difference)
                                                    |-
---------[changed 18]-----|----[changed to 19-21]----
(header)
return ctime(&clock);     | s = ctime(&clock); (difference)
                       -  | s[ strlen(s)-1 ] = '\0';
                          | return s;
                          |-

The –quiet and –diff_format options suppress the file summary. The –headers_only option suppresses the differences, listing the header lines only.

Header lines. Each header line indicates which text lines in the input files were changed and how they were changed. The words describe the change in terms of how the first file was changed to produce the second file. Header lines can have the following formats, where each of A, B, and so on may be a single line number (for example, 46) or a range (for example, 256–290):

----------[after A]----------|--------[inserted B]---------

Insertion of one or more lines. B indicates where the inserted lines occur in the second file. A indicates the corresponding point in the first file.

---------[deleted C]---------|---------[after D]----------

Deletion of one or more lines. C indicates which lines from the first file were deleted. D indicates the corresponding point in the second file.

--------[deleted/moved C]-----|--------[after D now B]--------

Deletion of one or more lines from the first file, to which there corresponds an insertion of the same lines in the second file. Typically, this indicates that a range of lines was moved from one location to another; see inserted/moved below. C indicates where the lines were deleted from the first file; B indicates where these same lines were inserted in the second file. D indicates the point in the second file that corresponds to C.

---------[changed X]----------|----------[changed to Y]---------

One or more lines changed in place. X indicates which lines in the first file were changed. Y indicates where the replacement lines occur in the second file.

--------[after A was C]--------|--------[inserted/moved B]------

Insertion of one or more lines in the second file, to which there corresponds a deletion of the same lines from the second file. Typically, this indicates that a range of lines was moved from one location to another; see deleted/moved above. B indicates where the lines were inserted in the second file; C indicates where these same lines were deleted from the first file; A indicates the point in the first file that corresponds to B.

Differences. diff can report a difference in several ways. When comparing files, its default behavior is to list corresponding lines side by side, and possibly truncated.

A plus sign (+) at the end of a difference line indicates that it has been truncated in the report. To see more of such lines, you can increase the report widthby using the –columns option (or on UNIX® and Linux®, by using the –tiny option). The minus signs () along the vertical separator line indicate the endpoints of the groups of differing lines. They help to distinguish empty lines in the input files from blank space in command output.

Other file comparison report styles

The –serial_format option causes the differences to be reported as entire lines, in above-and-below format instead of side-by-side format. For example:

-----[after 15 inserted 16]-----
>     char *s;
-----[18 changed to 19-21]-----
<     return ctime(&clock);
---
>   s = ctime(&clock);
>   s[ strlen(s)-1 ] = ' ';
>     return s;

The –diff_format option causes both the headers and differences to be reported in the style of the UNIX® and Linuxdiff utility, writing a list of the changes necessary to convert the first file being compared into the second file, as follows:

  • The first number (or range of numbers in the form n,n) indicates line numbers in the first file being compared.
  • The second value is one of the following: a d c. These indicate whether lines are to be added, deleted, or changed.
  • The second number (or range of numbers) indicates line numbers in the second file being compared.

When diff compares multiple files, it adds file-identification annotations to the diff-style headers.

The –graphical option displays differences graphically.

Directory-comparison algorithm and report format

For a comparison of directory versions, diff uses a directory-element-specific compare method, whose report format is very similar to the one described in the section Side-by-side file comparison report style.

Kinds of directory entries

A version of a VOB directory can contain several types of entries:

  • File elements. Reported by diff as the element's name (in this directory version), the element's creation time, and the user name of the element's creator. For example:

    obj2 2007-08-12T14:00 akp

    Note: Multiple VOB hard links to the same element will have the same creator and creation time, but different names.
  • Directory elements. Reported by diff in the same way as file elements, except that a slash (UNIX® and Linux®) or backslash (Windows®) is appended to the element name. For example:

    sub6/ 2007-08-13T15:00 akp

  • VOB symbolic links. Reported by diff as the link's name (in this directory version), followed by – and the text (contents) of the link; the link's creation time; and the user name of the element's creator. For example:

    doctn -> ..\vob1\doctn 2007-08-13T08:44 akp

How differences are reported

The diff report is a series of differences, each of which focuses on one directory entry. A difference can be a simple addition or deletion; it can also involve the renaming of an existing object or the reuse of an existing name for another object. The following examples illustrate the various possibilities.

------------------------------ |---------------[ added ]-------------
                             - | obj2 2007-08-12T14:00 akp

An object named obj2 was added (mkelem, mkdir, or ln) in the second version of the directory.

---------------[ removed ]---------- | ---------------------------
obj5 2007-08-12T14:00 akp                |-

An object named obj5 was removed (rmname) in the second version of the directory.

---------------[ renamed ]------------ |--------[ renamed to ]-------
obj3 2007-08-12T14:00 akp                  | obj3.new 2007-08-12T14:00 akp

An object named obj3 was renamed (mv) to obj3.new in the second version of the directory.

-------------[ old object ]------------ |--------[ new object ]-------
obj4 2007-08-12T14:04 akp                   | obj4 2007-10-19T17:10 akp

In the second version of the directory, an object named obj4 was removed (rmname) and another object was created with that same name.

----------[ old link text ]---------|------[ new link text ]----
doc -> ../vob1/doc 2007-08-13T08:44 akp | doc -> ../vb/doc 2007-09-19T21:01 akp

(Special case of the preceding example) In the second version of the directory, a VOB symbolic link named doc was removed (rmname) and another VOB symbolic link was created with that same name.

---------------[ renamed ]------------|---[ renamed to ]------------
obj4 2007-08-12T14:01 akp                 | obj1 2007-08-12T14:01 akp
---------------[ removed ]------------|-----------------------------
obj1 2007-08-12T14:00 akp                 |-

These two differences show that in the second version of the directory, an object named obj1 was removed and another object was renamed from obj4 to obj1.

Restrictions

None.

Options and arguments

With the exception of –predecessor and –options, diff options are the same as those of cleardiff.

Reporting differences graphically

Default
Reports differences in nongraphical form and uses the default display font.
–g/raphical [–tin/y]
Displays differences graphically. With –tiny, a smaller font is used to increase the amount of text displayed in each display pane.
Note: When comparing files of type html on UNIX® and Linux® systems, if the machine on which you execute diff –graphical is not the machine on which you run your HTML browser, your browser may not be able to find the pathname to the files being compared.

Using a separate window

Default
Sends output to the current window.
–tin/y
Same as –window, but uses a smaller font in a 165-character difference window.
–win/dow
Displays output in a separate difference window, formatted as with columns 120. Type an operating system interrupt character (typically, Ctrl+C) in the difference window to close it. The diff command returns immediately, not waiting for the difference window to be closed.

Contributor pane stacking

Default
Each of the two or more contributors being compared or merged is displayed in a separate subwindow, or contributor pane. By default, these panes are displayed, or stacked, horizontally (side by side), with the base contributor on the left.
–hst/ack
Displays the contributor panes horizontally (the default behavior).
–vst/ack
Stacks the contributor panes vertically, with the base contributor at the top.

Output format

Default
Reports differences in the format described in the section How differences are reported.
–ser/ial_format
Reports differences with each line containing output from a single file, instead of in a side-by-side format.
–dif/f_format
Reports both headers and differences in the same style as the UNIX® and Linux® diff utility (see the section Other file comparison report styles), and suppresses the file summary from the beginning of the report.
–col/umns n
Establishes the overall width of a side-by-side report. The default width is 80; only the first 40 or so characters of corresponding difference lines appear. If n does not exceed the default width, this option is ignored.

Comparison of a version with its predecessor

Default
None.
–pre/decessor
Effectively converts the first pname argument into two names: (1) the predecessor version of pname in the version tree; (2) pname itself. If pname specifies a checked-out version, the predecessor is the version from which it was checked out.

An error occurs if the pname does not specify a version:

cleartool: Error: Not a vob object: "myfile.c".

Passing through options to the compare method

Default
Does not pass any special options to the underlying compare method (typically, the cleardiff program).
–opt/ions pass-through-opts
Specifies one or more compare method options that are not directly supported by diff.

Use quotes if you are specifying more than one pass-through option; diff must see them as a single command-line argument. For example, this command passes through the –quiet and –blank_ignore options:

cmd-context  diff –options "–qui –b" –pred util.c

For descriptions of the valid options, see the cleardiff reference page.

Specifying the data to be compared

Default
None.
pname ...
One or more path names, indicating the objects to be compared: versions of file elements, versions of directory elements, or any other files. If you do not use –predecessor or –view, you must specify at least two pname arguments.

Examples

The UNIX system and Linux examples in this section are written for use in csh. If you use another shell, you may need to use different quoting and escaping conventions.

The Windows examples that include wildcards or quoting are written for use in cleartool interactive mode. If you use cleartool single-command mode, you may need to change the wildcards and quoting to make your command interpreter process the command appropriately.

In cleartool single-command mode, cmd-context represents the UNIX system and Linux shells or Windows command interpreter prompt, followed by the cleartool command. In cleartool interactive mode, cmd-context represents the interactive cleartool prompt.

  • Compare the version of a file element in the current view with the version in another view.

    cmd-context diff util.c /view/jackson_old/usr/hw/src/util.c

  • Compare the version of foo.c in the current view with its predecessor version.

    cmd-context diff –predecessor foo.c

  • Compare your unreserved checkout of hello.c with the latest checked-in version on the main branch.

    cmd-context diff hello.c hello.c@@\main\LATEST

  • On a UNIX® or Linux® system, compare three files: the version of msg.c selected by the current view, its predecessor version, and msg.SAVE in your home directory.

    cmd-context diff –pre msg.c $HOME/msg.SAVE

  • In a separate 132-column window, compare the version of util.c in the current view with a version on the rel2_bugfix branch.

    cmd-context diff –window –columns 132 util.c
    util.c@@/main/rel2_bugfix/LATEST

  • Start the Diff Merge Tool to compare the version of util.c in the current view with a version on the rel2_bugfix branch.

    cmd-context diff –graphical util.c util.c@@\main\rel2_bugfix\LATEST