und is the command-line interface to Understand — script project creation, analysis, CodeCheck, metrics, and reports, locally or in CI.

Run Understand from the command line · Headless workflow: create, analyze, check, report

und codecheck

runs CodeCheck

und codecheck [switches] <configuration> <outputDir> [database]

The codecheck command runs codecheck on all the database files printing the log to the screen, and saving the violation information in an output directory. The command takes two arguments: the configuration to use and the output directory. So, the most basic command could look like this:

und codecheck myConfiguration C:\OutputDir

The configuration can be the name of a CodeCheck configuration that already exists in the project, or the path to an exported configuration file. The following switches control the files input to CodeCheck. If more than one of these is given, the filters will be combined in an "AND" relationship. If none of these switches are used CodeCheck will run on all files.

Option	Description
`-gitfiles`	This switch instructs CodeCheck to only inspect uncommitted changed files. Optionally, the git id (first 8 characters, or entire thing) can be passed as a parameter to only inspect files in that specified revision. To only inspect files after that specified revision, include 'after' following the git id. For example: und codecheck -gitfiles 1ff2406b after Sandbox c:\test\output -db c:\test\util.und
`-changedfiles`	This switch instructs CodeCheck to use only files that have changed since the last CodeCheck inspection.
`-arch`	Inspect files in the provided architecture. For example: und codecheck -arch "Directory Structure/src" Sandbox output_dir db.und
`-files`	This takes in a list file with all the files to run codecheck on. The files must be in the project. The list file does not have to start with @. Additionally, a comma delimited list of line numbers and ranges (5,10,12-30) can be specified after the file name to limit the results being shown to just those lines

An inspection produces a file in the output directory called results.sarif which contains all the information about the inspection. The file location can be overridden with the "-sarif" switch:

Option	Description
`-sarif outputFile`	Write the inspection results to the given file instead of the default results.sarif in the output directory.

und codecheck -sarif mysarifname.sarif config outdir project.und

All additional output files are reports generated from the inspection. For full control over the reports, use the report subcommand. For convenience, the "-reports" switch can be used to specify specific reports to run. Running "-reports all" will generate all available reports. Reports are created in csv, pdf, and html formats.

Option	Description
`-reports [name] [name] ...`	Names of reports to output in csv, pdf and html formats. The default, when this switch is not given, is the report named "CodeCheck Results By Table", which produces "CodeCheckResultsByTable.csv" in the output directory. If the only argument is the name "all", then all known reports will be generated.

For example, to generate the compliance report, the command would be:

und codecheck -reports Compliance config outdir project.und

To set report options, the report subcommand must be used. The report subcommand has a -codecheck switch that will use the codecheck results from earlier in the und command if no results filename argument is given. For example, to generate only part of the compliance report:

und -db project.und \
    codecheck config outdir\
    report -codecheck -options "Sections=Summary,Coverage"\
      "Compliance" outdir/Compliance.pdf

To change options for the default CodeCheckResultsByTable report, you can provide the -report switch on the codecheck command with no arguments to suppress the default report and then use the report subcommand to set options. For example, setting the file name format:

und -db project.und \
  codecheck -reports config outdir \
  report -codecheck -options "Report Name Format=short" \
    "CodeCheck Results By Table" outdir/CodeCheckResultsByTable.csv

Comparing Inspections

To compare the results with a previous inspection, similar to the GUI dashboard, the previous inspection to compare against must be given using the -previous switch:

Option	Description
`-previous`	The path to a previous inspection file (.sarif) to compare against.

Providing a previous inspection will create "New" and "Fixed" versions of every report given with the -reports switch. For example

und -db project.und codecheck -previous yesterday/results.sarif \
  configuration outdir

will create the normal "outdir/CodeCheckResultsByTable.csv" and two additional files: "outdir/New_CodeCheckResultsByTable.csv" and "outdir/Fixed_CodeCheckResultsByTable.csv".

Note that the -previous switch does not impact the results sarif file and it is not carried over to the report subcommand. To generate the three files above with the report subcommand, the -codecheck switch of the report subcommand must be given two arguments for the comparison:

und -db project.und\
  codecheck -reports config outdir\
  report -codecheck \
    "CodeCheck Results By Table" outdir/CodeCheckResultsByTable.csv\
  report -codecheck outdir/results.sarif yesterday/results.sarif\
    "CodeCheck Results By Table" outdir/New_CodeCheckResultsByTable.csv\
  report -codecheck yesterday/results.sarif outdir/results.sarif\
    "CodeCheck Results By Table" outdir/Fixed_CodeCheckResultsByTable.csv

Note that the report subcommand can be given multiple times and that the -codecheck switch of the report subcommand can take two arguments to specify the current and previous inspections. To compare the just run inspection, the sarif output file ("outdir/results.sarif" by default) is given.

The exit status switch is still supported:

Option Description

-exitstatus The presence of this switch causes the CodeCheck to return the number of violations as the exit status code. It takes an optional argument of how to count violations. By default, it returns the "remaining" violations which are any violations not ignored or excluded. The argument can be "withexcluded" to include the number of excluded violations. The argument "errors" can be used to return the number of script errors.

Option	Description
`-exitstatus`	The presence of this switch causes the CodeCheck to return the number of violations as the exit status code. It takes an optional argument of how to count violations. By default, it returns the "remaining" violations which are any violations not ignored or excluded. The argument can be "withexcluded" to include the number of excluded violations. The argument "errors" can be used to return the number of script errors.