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,inners,outers] 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. A default can be specified using the layer_defaults global option.

      • 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. A default can be specified using the layer_defaults global option.

  • 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.

      • color_added : [string=’#00FF00’] Color used for the added stuff in the ‘2color’ mode.

      • color_removed : [string=’#FF0000’] Color used for the removed stuff in the ‘2color’ mode.

      • 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,2color] In the red_green mode added stuff is green and red when removed. The stats mode is used to measure the amount of difference. In this mode all changes are red, but you can abort if the difference is bigger than certain threshold. The ‘2color’ mode is like ‘red_green’, but you can customize the colors.

      • dnf_filter : [string|list(string)=’_none’] Name of the filter to mark components as not fitted. A short-cut to use for simple cases where a variant is an overkill.

      • 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 differences 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.

      • pre_transform : [string|list(string)=’_none’] Name of the filter to transform fields before applying other filters. A short-cut to use for simple cases where a variant is an overkill.

      • 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.

      • variant : [string=’’] Board variant to apply.

      • zones : [string=’global’] [global,fill,unfill,none] How to handle PCB zones. The default is global and means that we fill zones if the check_zone_fills preflight is enabled. The fill option always forces a refill, unfill forces a zone removal and none lets the zones unchanged. Be careful with the cache when changing this setting.

  • type : ‘diff’

  • 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.