121 lines
10 KiB
ReStructuredText
121 lines
10 KiB
ReStructuredText
.. Automatically generated by KiBot, please don't edit this file
|
|
|
|
.. index::
|
|
pair: Diff; diff
|
|
|
|
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** :index:`: <pair: output - diff; comment>` [string=''] A comment for documentation purposes. It helps to identify the output.
|
|
- **dir** :index:`: <pair: output - diff; dir>` [string='./'] Output directory for the generated files.
|
|
If it starts with `+` the rest is concatenated to the default dir.
|
|
- **layers** :index:`: <pair: output - diff; 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`` :index:`: <pair: output - diff - layers; description>` [string=''] A description for the layer, for documentation purposes.
|
|
A default can be specified using the `layer_defaults` global option.
|
|
- ``layer`` :index:`: <pair: output - diff - layers; layer>` [string=''] Name of the layer. As you see it in KiCad.
|
|
- ``suffix`` :index:`: <pair: output - diff - layers; 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** :index:`: <pair: output - diff; name>` [string=''] Used to identify this particular output definition.
|
|
Avoid using `_` as first character. These names are reserved for KiBot.
|
|
- **options** :index:`: <pair: output - diff; options>` [dict] Options for the `diff` output.
|
|
|
|
- Valid keys:
|
|
|
|
- **output** :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; cache_dir>` [string=''] Directory to cache the intermediate files. Leave it blank to disable the cache.
|
|
- ``color_added`` :index:`: <pair: output - diff - options; color_added>` [string='#00FF00'] Color used for the added stuff in the '2color' mode.
|
|
- ``color_removed`` :index:`: <pair: output - diff - options; color_removed>` [string='#FF0000'] Color used for the removed stuff in the '2color' mode.
|
|
- ``copy_instead_of_link`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; fuzz>` [number=5] [0,100] Color tolerance (fuzzyness) for the `stats` mode.
|
|
- ``new`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; only_first_sch_page>` [boolean=false] Compare only the main schematic page (root page).
|
|
- ``pcb`` :index:`: <pair: output - diff - options; pcb>` [boolean=true] Compare the PCB, otherwise compare the schematic.
|
|
- ``pre_transform`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; 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`` :index:`: <pair: output - diff - options; variant>` [string=''] Board variant to apply.
|
|
- ``zones`` :index:`: <pair: output - diff - options; 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** :index:`: <pair: output - diff; type>` 'diff'
|
|
- ``category`` :index:`: <pair: output - 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`` :index:`: <pair: output - diff; 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`` :index:`: <pair: output - diff; extends>` [string=''] Copy the `options` section from the indicated output.
|
|
Used to inherit options from another output of the same type.
|
|
- ``groups`` :index:`: <pair: output - diff; 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`` :index:`: <pair: output - diff; output_id>` [string=''] Text to use for the %I expansion content. To differentiate variations of this output.
|
|
- ``priority`` :index:`: <pair: output - diff; 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`` :index:`: <pair: output - diff; run_by_default>` [boolean=true] When enabled this output will be created when no specific outputs are requested.
|
|
|