Diff

Generates a PDF with the differences between two PCBs or schematics. Recursive git submodules aren’t supported (submodules inside submodules)

Type: diff

Categories: PCB/docs, Schematic/docs

Parameters:

  • comment : [string=’’] A comment for documentation purposes. It helps to identify the output.

  • dir : [string=’./’] Output directory for the generated files. If it starts with + the rest is concatenated to the default dir.

  • layers : [list(dict)|list(string)|string] [all,selected,copper,technical,user] List of PCB layers to use. When empty all available layers are used. Note that if you want to support adding/removing layers you should specify a list here.

    • Valid keys:

      • description : [string=’’] A description for the layer, for documentation purposes.

      • layer : [string=’’] Name of the layer. As you see it in KiCad.

      • suffix : [string=’’] Suffix used in file names related to this layer. Derived from the name if not specified.

  • name : [string=’’] Used to identify this particular output definition. Avoid using _ as first character. These names are reserved for KiBot.

  • options : [dict] Options for the diff output.

    • Valid keys:

      • output : [string=’%f-%i%I%v.%x’] Filename for the output (%i=diff_pcb/diff_sch, %x=pdf). Affected by global options.

      • add_link_id : [boolean=false] When enabled we create a symlink to the output file with a name that contains the git hashes involved in the comparison. If you plan to compress the output don’t forget to disable the follow_links option.

      • always_fail_if_missing : [boolean=false] Always fail if the old/new file doesn’t exist. Currently we don’t fail if they are from a repo. So if you refer to a repo point where the file wasn’t created KiBot will use an empty file. Enabling this option KiBot will report an error.

      • cache_dir : [string=’’] Directory to cache the intermediate files. Leave it blank to disable the cache.

      • copy_instead_of_link : [boolean=false] Modifies the behavior of add_link_id to create a copy of the file instead of a symlink. Useful for some Windows setups.

      • diff_mode : [string=’red_green’] [red_green,stats] In the red_green mode added stuff is green and red when removed. The stats mode is used to meassure the amount of difference. In this mode all changes are red, but you can abort if the difference is bigger than certain threshold.

      • force_checkout : [boolean=false] When old_type and/or new_type are git KiBot will checkout the indicated point. Before doing it KiBot will stash any change. Under some circumstances git could fail to do a checkout, even after stashing, this option can workaround the problem. Note that using it you could potentially lose modified files. For more information read https://stackoverflow.com/questions/1248029/git-pull-error-entry-foo-not-uptodate-cannot-merge.

      • fuzz : [number=5] [0,100] Color tolerance (fuzzyness) for the stats mode.

      • new : [string|list(string)] The file you want to compare. Leave it blank for the current PCB/SCH. A list is accepted only for the multivar type. Consult the old option for more information.

      • new_type : [string=’current’] [git,file,output,multivar,current] How to interpret the new name. Use git for a git hash, branch, etc. Use current for the currently loaded PCB/Schematic. Use file for a file name. Use output to specify the name of a pcb_variant/sch_variant output. Use multivar to compare a set of variants, in this mode new is the list of outputs for the variants. This is an extension of the output mode. If old is also multivar then it becomes the reference, otherwise we compare using pairs of variants.

      • old : [string=’HEAD’] Reference file. When using git use HEAD to refer to the last commit. Use HEAD~ to refer the previous to the last commit. As HEAD is for the whole repo you can use KIBOT_LAST-n to make reference to the changes in the PCB/SCH. The n value is how many changes in the history you want to go back. A 0 is the same as HEAD, a 1 means the last time the PCB/SCH was changed, etc. Use KIBOT_TAG-n to search for the last tag skipping n tags. Important: when using the checkout GitHub action you just get the last commit. To clone the full repo use fetch-depth: ‘0’.

      • old_type : [string=’git’] [git,file,output,multivar] How to interpret the old name. Use git for a git hash, branch, etc. Use file for a file name. Use output to specify the name of a pcb_variant/sch_variant output. Use multivar to specify a reference file when new_type is also multivar.

      • only_different : [boolean=false] Only include the pages with differences in the output PDF. Note that when no differeces are found we get a page saying No diff.

      • only_first_sch_page : [boolean=false] Compare only the main schematic page (root page).

      • pcb : [boolean=true] Compare the PCB, otherwise compare the schematic.

      • threshold : [number=0] [0,1000000] Error threshold for the stats mode, 0 is no error. When specified a difference bigger than the indicated value will make the diff fail. KiBot will return error level 29 and the diff generation will be aborted.

      • use_file_id : [boolean=false] When creating the link name of an output file related to a variant use the variant file_id instead of its name.

  • type : [string=’’] Type of output.

  • category : [string|list(string)=’’] The category for this output. If not specified an internally defined category is used. Categories looks like file system paths, i.e. PCB/fabrication/gerber. The categories are currently used for navigate_results.

  • disable_run_by_default : [string|boolean] Use it to disable the run_by_default status of other output. Useful when this output extends another and you don’t want to generate the original. Use the boolean true value to disable the output you are extending.

  • extends : [string=’’] Copy the options section from the indicated output. Used to inherit options from another output of the same type.

  • groups : [string|list(string)=’’] One or more groups to add this output. In order to catch typos we recommend to add outputs only to existing groups. You can create an empty group if needed.

  • output_id : [string=’’] Text to use for the %I expansion content. To differentiate variations of this output.

  • priority : [number=50] [0,100] Priority for this output. High priority outputs are created first. Internally we use 10 for low priority, 90 for high priority and 50 for most outputs.

  • run_by_default : [boolean=true] When enabled this output will be created when no specific outputs are requested.