../_images/logo.png

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
    ";
  }