YumaPro yangdiff-pro Manual¶

../_images/yangdiff_components_02-02-2022.png

yangdiff-pro Introduction¶

The yangdiff-pro program is used to compare two revisions of the same YANG file.

yangdiff-pro Features¶

The yangdiff-pro program has the following features:

The conceptual YANG object trees are compared, not the actual YANG statements.
Two separate subtrees of modules can be compared, not just 1 file at a time.
The differences report format for differences is easy to read, and can be configured with 2 different levels of verbosity.
A YANG revision statement can be automatically generated instead of a list of differences. This will include an English text summary of the differences found.

Starting yangdiff-pro¶

The current working directory in use when yangdiff-pro is invoked is important. It is most convenient to run yangdiff-pro from a work directory, rather than the installation directory or within the module library.

The yangdiff-pro program can be invoked several ways:

To get the current version and exit:
```
> yangdiff-pro --version
```

To get program help and exit:

> yangdiff-pro --help
> yangdiff-pro --help --brief
> yangdiff-pro --help --full

To compare a new YANG module named 'foo', with an old version named foo.2008-09-01.yang, the following command line can be used
```
> yangdiff-pro --old=foo.2008-09-01.yang --new=foo
```
To get all the configuration parameters from a text file named '~/yangdiff-pro-project1.conf':
```
> yangdiff-pro --config=~/yangdiff-pro-project1.conf
```
To generate a terse differences report called ~/project-X-diffs.log for the old files in the '/public/project-X/modules' with the new modules in the '~/work' directory:
```
> yangdiff-pro --difftype=terse --output=~/project-X-diffs.log \
   --old=/public/project-X/modules --new=/work
```
To generate a revision statement differences to ~/foo-projectX-revision.txt for the '~/work/foo.yang' module, with the old version in the in the '/public/project-X/modules':
```
> yangdiff-pro --difftype=revision --output=~/foo-project-X-revision.txt \
   --old=/public/project-X/modules --new=/work/foo.yang
```

Stopping yangdiff-pro¶

There is no interactive mode for yangdiff-pro, so there is no need for a command to exit the program.

The Control C character sequence can be used to cancel the yangdiff-pro processing in progress. However, this will leave any partially completed output files in place.

yangdiff-pro Configuration Parameter List¶

The following configuration parameters are used by yangdiff-pro. Refer to the CLI Reference for more details.

yangdiff-pro CLI Parameters

:header-rows:1¶
Parameter	Description
--config	Specifies the configuration file to use for parameters.
--datapath	Sets the data file search path.
--difftype	Specifies the type of differences report that should be output.
--feature-disable	Leaf list of features to disable
--feature-enable	Specifies a feature that should be enabled
--feature-enable-default	Specifies if a feature should be enabled or disabled by default
--header	Specifies whether the module header data should be compared or not.
--help	Get context-sensitive help, then exit.
--help-mode	Adjust the help output (--brief, or --full).
--home	Override $HOME environment variable
--indent	Specifies the indent count to use when writing data.
--log	Specifies the log file to use instead of STDOUT.
--log-append	Controls whether a log file will be reused or overwritten.
--log-level	Specifies verbosity level of log message output
--modpath	Sets the module search path.
--new	Specifies the location of the new revision to compare.
--no-config	Specifies that the default config file should not be loaded
--old	Specifies the location of the old revision to compare.
--output	Specifies where output files should be generated.
--runpath	Sets the executable file search path.
--subdirs	Controls whether sub-directories are searched for YANG files.
--version	Prints the program version and then exit.
--warn-idlen	Controls how identifier lengths are checked.
--warn-error	Treat all warnings as errors
--warn-linelen	Controls how line lengths are checked.
--warn-off	Suppresses the specified warning number.
--warn-up	Elevates the specified warning number to an error
--yumapro-home	Specifies the $YUMAPRO_HOME project root to use when searching for files.

Comparing YANG Modules¶

The yangdiff-pro program compares YANG files in the following manner:

The cooked object trees are compared, not the actual YANG statements.
Whitespace differences are ignored.
Non-semantic changes are ignored:
- A uses-stmt can replace a set of objects if the grouping is identical to the old objects.
- Refine statements are combined into the cooked objects, and not compared directly.
- A typedef statement can replace an inline type statement
- Changes to YANG comments are ignored.
- Sub-statement order is ignored, however object order with a container or list is not ignored.
- Objects can be moved to submodules, and include statements instead.

If the --old parameter is missing, then the module search path will be used to find the specified module with the same name. If the --old parameter contains just a module name, then the module search path will be used to find a module with the new name.

The --new parameter is required. It can represent one YANG file or a directory of new YANG modules.

The --difftype parameter is optional. The 'normal' report mode is used if this parameter is missing.

The --output parameter will be used for the report file, if it is specified.

Symbol	Description
A	Definition has been added.
M	Definition has been modified.
D	Definition has been deleted.

Diff Reports¶

This section uses the example module below (test/pass/test3a.yang) to demonstrate the different report formats available. The old module revision is test/pass/test3.yang.

The following command is used in all 3 examples, except the value of the --difftype parameter is changed each time. The <enum> is explained below.

> yangdiff-pro --old=test3a --new=test3 --difftype=<enum>

Terse Report¶

If --difftype=terse is selected, then a brief summary of all changes will be listed. There will be no indentation, and only the change (Add, Modify, Delete), and the top-level definition is identified.

// old: test3a (2009-09-09) test3a.yang
// new: test3 (2008-10-19) test3.yang

M module from 'test3a' to 'test3'
M namespace
D revision '2009-09-09'
A revision '2008-10-19'
D feature X
D identity testbase
D identity testbase1
M typedef C
M container test33
A container test-D1
A leaf test-D

Normal Report¶

If --difftype=normal is selected, then a complete summary of all changes will be listed.

If a change line is indented, it indicates a sub-statement of the object in the previous line has been changed.

// old: test3a (2009-09-09) test3a.yang
// new: test3 (2008-10-19) test3.yang

M module from 'test3a' to 'test3'
M namespace
D revision '2009-09-09'
A revision '2008-10-19'
D feature X
D identity testbase
D identity testbase1
M typedef C
  M type
    M range from 'min .. 41' to 'min .. 41 | 45'
M container test33
  A presence 'not a top-level mand...'
  M choice f
    M case f1
      M leaf f1
        D if-feature 'X'
A container test-D1
A leaf test-D

Revision Statement¶

If --difftype=revision is selected, then a complete summary of all changes will be printed in the form of a YANG revision statement. The current date will be used for the revision-date field of the revision statement.

// old: test3a (2009-09-09) test3a.yang
// new: test3 (2008-10-19) test3.yang

  revision 2022-01-06 {
    description "
      - Changed module from 'test3a' to 'test3'
      - Changed namespace
      - Removed revision '2009-09-09'
      - Added revision '2008-10-19'
      - Removed feature X
      - Removed identity testbase
      - Removed identity testbase1
      - Changed typedef C
        - Changed type
          - Changed range from 'min .. 41' to 'min .. 41 | 45'
      - Changed container test33
        - Added presence 'not a top-level mand...'
        - Changed choice f
          - Changed case f1
            - Changed leaf f1
              - Removed if-feature 'X'
      - Added container test-D1
      - Added leaf test-D
    ";
  }