KiBot/docs/build/html/configuration/outputs/diff.html

296 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Diff &mdash; KiBot 1.6.4 documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/underscore.js"></script>
<script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/sphinx_highlight.js"></script>
<script src="../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Datasheets downloader" href="download_datasheets.html" />
<link rel="prev" title="Files copier" href="copy_files.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../index.html" class="icon icon-home">
KiBot
<img src="../../_static/kibot_370x200.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../installation.html">Installation</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../configuration.html">Configuration</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../quick_start.html">Quick start</a></li>
<li class="toctree-l2"><a class="reference internal" href="../section_order.html">Section order</a></li>
<li class="toctree-l2"><a class="reference internal" href="../header.html">The header</a></li>
<li class="toctree-l2"><a class="reference internal" href="../preflight.html">The <em>preflight</em> section</a></li>
<li class="toctree-l2"><a class="reference internal" href="../global.html">Default global options</a></li>
<li class="toctree-l2"><a class="reference internal" href="../filters.html">Filters and variants</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../outputs.html">The <em>outputs</em> section</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../outputs.html#specifying-the-layers">Specifying the layers</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../outputs.html#supported-outputs">Supported outputs</a><ul class="current">
<li class="toctree-l4"><a class="reference internal" href="blender_export.html">Blender Export <strong>Experimental</strong></a></li>
<li class="toctree-l4"><a class="reference internal" href="boardview.html">BoardView</a></li>
<li class="toctree-l4"><a class="reference internal" href="bom.html">BoM (Bill of Materials)</a></li>
<li class="toctree-l4"><a class="reference internal" href="compress.html">Archiver (files compressor)</a></li>
<li class="toctree-l4"><a class="reference internal" href="copy_files.html">Files copier</a></li>
<li class="toctree-l4 current"><a class="current reference internal" href="#">Diff</a></li>
<li class="toctree-l4"><a class="reference internal" href="download_datasheets.html">Datasheets downloader</a></li>
<li class="toctree-l4"><a class="reference internal" href="dxf.html">DXF (Drawing Exchange Format)</a></li>
<li class="toctree-l4"><a class="reference internal" href="dxf_sch_print.html">DXF Schematic Print (Drawing Exchange Format)</a></li>
<li class="toctree-l4"><a class="reference internal" href="excellon.html">Excellon drill format</a></li>
<li class="toctree-l4"><a class="reference internal" href="gencad.html">GenCAD</a></li>
<li class="toctree-l4"><a class="reference internal" href="gerb_drill.html">Gerber drill format</a></li>
<li class="toctree-l4"><a class="reference internal" href="gerber.html">Gerber format</a></li>
<li class="toctree-l4"><a class="reference internal" href="hpgl.html">HPGL (Hewlett &amp; Packard Graphics Language)</a></li>
<li class="toctree-l4"><a class="reference internal" href="hpgl_sch_print.html">HPGL Schematic Print (Hewlett &amp; Packard Graphics Language)</a></li>
<li class="toctree-l4"><a class="reference internal" href="ibom.html">IBoM (Interactive HTML BoM)</a></li>
<li class="toctree-l4"><a class="reference internal" href="info.html">Info</a></li>
<li class="toctree-l4"><a class="reference internal" href="kibom.html">KiBoM (KiCad Bill of Materials)</a></li>
<li class="toctree-l4"><a class="reference internal" href="kicost.html">KiCost (KiCad Cost calculator)</a></li>
<li class="toctree-l4"><a class="reference internal" href="kikit_present.html">KiKits Present - Project Presentation</a></li>
<li class="toctree-l4"><a class="reference internal" href="navigate_results.html">Navigate Results</a></li>
<li class="toctree-l4"><a class="reference internal" href="netlist.html">Netlist</a></li>
<li class="toctree-l4"><a class="reference internal" href="panelize.html">Panelize</a></li>
<li class="toctree-l4"><a class="reference internal" href="pcb2blender_tools.html">PCB2Blender Tools</a></li>
<li class="toctree-l4"><a class="reference internal" href="pcb_print.html">PCB Print</a></li>
<li class="toctree-l4"><a class="reference internal" href="pcb_variant.html">PCB with variant generator</a></li>
<li class="toctree-l4"><a class="reference internal" href="pcbdraw.html">PcbDraw - Beautiful 2D PCB render</a></li>
<li class="toctree-l4"><a class="reference internal" href="pdf.html">PDF (Portable Document Format)</a></li>
<li class="toctree-l4"><a class="reference internal" href="pdf_pcb_print.html">PDF PCB Print (Portable Document Format) <em>Deprecated</em></a></li>
<li class="toctree-l4"><a class="reference internal" href="pdf_sch_print.html">PDF Schematic Print (Portable Document Format)</a></li>
<li class="toctree-l4"><a class="reference internal" href="pdfunite.html">PDF joiner</a></li>
<li class="toctree-l4"><a class="reference internal" href="populate.html">Populate - Assembly instructions builder</a></li>
<li class="toctree-l4"><a class="reference internal" href="position.html">Pick &amp; place</a></li>
<li class="toctree-l4"><a class="reference internal" href="ps.html">PS (Postscript)</a></li>
<li class="toctree-l4"><a class="reference internal" href="ps_sch_print.html">PS Schematic Print (Postscript)</a></li>
<li class="toctree-l4"><a class="reference internal" href="qr_lib.html">QR_Lib</a></li>
<li class="toctree-l4"><a class="reference internal" href="render_3d.html">3D render of the PCB</a></li>
<li class="toctree-l4"><a class="reference internal" href="report.html">Design report</a></li>
<li class="toctree-l4"><a class="reference internal" href="sch_variant.html">Schematic with variant generator</a></li>
<li class="toctree-l4"><a class="reference internal" href="stencil_3d.html">3D Printed Stencils</a></li>
<li class="toctree-l4"><a class="reference internal" href="stencil_for_jig.html">Steel Stencils for Alignment Jig</a></li>
<li class="toctree-l4"><a class="reference internal" href="step.html">STEP (ISO 10303-21 Clear Text Encoding of the Exchange Structure)</a></li>
<li class="toctree-l4"><a class="reference internal" href="svg.html">SVG (Scalable Vector Graphics)</a></li>
<li class="toctree-l4"><a class="reference internal" href="svg_pcb_print.html">SVG PCB Print (Scalable Vector Graphics) <em>Deprecated</em></a></li>
<li class="toctree-l4"><a class="reference internal" href="svg_sch_print.html">SVG Schematic Print</a></li>
<li class="toctree-l4"><a class="reference internal" href="vrml.html">VRML (Virtual Reality Modeling Language)</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../outputs.html#consolidating-boms">Consolidating BoMs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../outputs.html#importing-outputs-from-another-file">Importing outputs from another file</a></li>
<li class="toctree-l3"><a class="reference internal" href="../outputs.html#importing-other-stuff-from-another-file">Importing other stuff from another file</a></li>
<li class="toctree-l3"><a class="reference internal" href="../outputs.html#parametrizable-imports">Parametrizable imports</a></li>
<li class="toctree-l3"><a class="reference internal" href="../outputs.html#importing-internal-templates">Importing internal templates</a></li>
<li class="toctree-l3"><a class="reference internal" href="../outputs.html#using-other-output-as-base-for-a-new-one">Using other output as base for a new one</a></li>
<li class="toctree-l3"><a class="reference internal" href="../outputs.html#grouping-outputs">Grouping outputs</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../substitution.html">Doing YAML substitution or preprocessing</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../usage.html">Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../usage_with_ci_cd.html">Usage for CI/CD</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Notes and extra information:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../notes_gerber.html">Notes about Gerber format</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../notes_position.html">Notes about the position file</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../notes_3d.html">Notes about 3D models</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../propose.html">Proposed advanced KiCad usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../KiPlotYAML.html">KiPlot YAML</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Final notes:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../contributing.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../credits.html">Credits</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Indices and tables:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../genindex.html">Index</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">KiBot</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../../configuration.html">Configuration</a></li>
<li class="breadcrumb-item"><a href="../outputs.html">The <em>outputs</em> section</a></li>
<li class="breadcrumb-item active">Diff</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="diff">
<span id="index-0"></span><h1>Diff<a class="headerlink" href="#diff" title="Permalink to this heading"></a></h1>
<p>Generates a PDF with the differences between two PCBs or schematics.
Recursive git submodules arent supported (submodules inside submodules)</p>
<p>Type: <code class="docutils literal notranslate"><span class="pre">diff</span></code></p>
<p>Categories: <strong>PCB/docs</strong>, <strong>Schematic/docs</strong></p>
<p>Parameters:</p>
<ul class="simple">
<li><p><strong>comment</strong> <span class="target" id="index-1"></span>: [string=] A comment for documentation purposes. It helps to identify the output.</p></li>
<li><p><strong>dir</strong> <span class="target" id="index-2"></span>: [string=./] Output directory for the generated files.
If it starts with <cite>+</cite> the rest is concatenated to the default dir.</p></li>
<li><p><strong>layers</strong> <span class="target" id="index-3"></span>: [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.</p>
<ul>
<li><p>Valid keys:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">description</span></code> <span class="target" id="index-4"></span>: [string=] A description for the layer, for documentation purposes.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">layer</span></code> <span class="target" id="index-5"></span>: [string=] Name of the layer. As you see it in KiCad.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">suffix</span></code> <span class="target" id="index-6"></span>: [string=] Suffix used in file names related to this layer. Derived from the name if not specified.</p></li>
</ul>
</li>
</ul>
</li>
<li><p><strong>name</strong> <span class="target" id="index-7"></span>: [string=] Used to identify this particular output definition.
Avoid using <cite>_</cite> as first character. These names are reserved for KiBot.</p></li>
<li><p><strong>options</strong> <span class="target" id="index-8"></span>: [dict] Options for the <cite>diff</cite> output.</p>
<ul>
<li><p>Valid keys:</p>
<ul>
<li><p><strong>output</strong> <span class="target" id="index-9"></span>: [string=%f-%i%I%v.%x] Filename for the output (%i=diff_pcb/diff_sch, %x=pdf). Affected by global options.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">add_link_id</span></code> <span class="target" id="index-10"></span>: [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 dont
forget to disable the <cite>follow_links</cite> option.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">always_fail_if_missing</span></code> <span class="target" id="index-11"></span>: [boolean=false] Always fail if the old/new file doesnt exist. Currently we dont fail if they are from a repo.
So if you refer to a repo point where the file wasnt created KiBot will use an empty file.
Enabling this option KiBot will report an error.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cache_dir</span></code> <span class="target" id="index-12"></span>: [string=] Directory to cache the intermediate files. Leave it blank to disable the cache.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">copy_instead_of_link</span></code> <span class="target" id="index-13"></span>: [boolean=false] Modifies the behavior of <cite>add_link_id</cite> to create a copy of the file instead of a
symlink. Useful for some Windows setups.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">diff_mode</span></code> <span class="target" id="index-14"></span>: [string=red_green] [red_green,stats] In the <cite>red_green</cite> mode added stuff is green and red when removed.
The <cite>stats</cite> 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.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">force_checkout</span></code> <span class="target" id="index-15"></span>: [boolean=false] When <cite>old_type</cite> and/or <cite>new_type</cite> are <cite>git</cite> 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 <a class="reference external" href="https://stackoverflow.com/questions/1248029/git-pull-error-entry-foo-not-uptodate-cannot-merge">https://stackoverflow.com/questions/1248029/git-pull-error-entry-foo-not-uptodate-cannot-merge</a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fuzz</span></code> <span class="target" id="index-16"></span>: [number=5] [0,100] Color tolerance (fuzzyness) for the <cite>stats</cite> mode.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">new</span></code> <span class="target" id="index-17"></span>: [string|list(string)] The file you want to compare. Leave it blank for the current PCB/SCH.
A list is accepted only for the <cite>multivar</cite> type. Consult the <cite>old</cite> option for more information.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">new_type</span></code> <span class="target" id="index-18"></span>: [string=current] [git,file,output,multivar,current] How to interpret the <cite>new</cite> name. Use <cite>git</cite> for a git hash, branch, etc.
Use <cite>current</cite> for the currently loaded PCB/Schematic.
Use <cite>file</cite> for a file name. Use <cite>output</cite> to specify the name of a <cite>pcb_variant</cite>/<cite>sch_variant</cite> output.
Use <cite>multivar</cite> to compare a set of variants, in this mode <cite>new</cite> is the list of outputs for the variants.
This is an extension of the <cite>output</cite> mode.
If <cite>old</cite> is also <cite>multivar</cite> then it becomes the reference, otherwise we compare using pairs of variants.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">old</span></code> <span class="target" id="index-19"></span>: [string=HEAD] Reference file. When using git use <cite>HEAD</cite> to refer to the last commit.
Use <cite>HEAD~</cite> to refer the previous to the last commit.
As <cite>HEAD</cite> is for the whole repo you can use <cite>KIBOT_LAST-n</cite> to make
reference to the changes in the PCB/SCH. The <cite>n</cite> value is how many
changes in the history you want to go back. A 0 is the same as <cite>HEAD</cite>,
a 1 means the last time the PCB/SCH was changed, etc.
Use <cite>KIBOT_TAG-n</cite> to search for the last tag skipping <cite>n</cite> tags.
Important: when using the <cite>checkout</cite> GitHub action you just get the
last commit. To clone the full repo use <cite>fetch-depth: 0</cite>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">old_type</span></code> <span class="target" id="index-20"></span>: [string=git] [git,file,output,multivar] How to interpret the <cite>old</cite> name. Use <cite>git</cite> for a git hash, branch, etc.
Use <cite>file</cite> for a file name. Use <cite>output</cite> to specify the name of a <cite>pcb_variant</cite>/<cite>sch_variant</cite> output.
Use <cite>multivar</cite> to specify a reference file when <cite>new_type</cite> is also <cite>multivar</cite>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">only_different</span></code> <span class="target" id="index-21"></span>: [boolean=false] Only include the pages with differences in the output PDF.
Note that when no differeces are found we get a page saying <em>No diff</em>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">only_first_sch_page</span></code> <span class="target" id="index-22"></span>: [boolean=false] Compare only the main schematic page (root page).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pcb</span></code> <span class="target" id="index-23"></span>: [boolean=true] Compare the PCB, otherwise compare the schematic.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">threshold</span></code> <span class="target" id="index-24"></span>: [number=0] [0,1000000] Error threshold for the <cite>stats</cite> 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.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">use_file_id</span></code> <span class="target" id="index-25"></span>: [boolean=false] When creating the link name of an output file related to a variant use the variant
<cite>file_id</cite> instead of its name.</p></li>
</ul>
</li>
</ul>
</li>
<li><p><strong>type</strong> <span class="target" id="index-26"></span>: [string=] Type of output.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">category</span></code> <span class="target" id="index-27"></span>: [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. <strong>PCB/fabrication/gerber</strong>.
The categories are currently used for <cite>navigate_results</cite>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">disable_run_by_default</span></code> <span class="target" id="index-28"></span>: [string|boolean] Use it to disable the <cite>run_by_default</cite> status of other output.
Useful when this output extends another and you dont want to generate the original.
Use the boolean true value to disable the output you are extending.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">extends</span></code> <span class="target" id="index-29"></span>: [string=] Copy the <cite>options</cite> section from the indicated output.
Used to inherit options from another output of the same type.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">groups</span></code> <span class="target" id="index-30"></span>: [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.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">output_id</span></code> <span class="target" id="index-31"></span>: [string=] Text to use for the %I expansion content. To differentiate variations of this output.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">priority</span></code> <span class="target" id="index-32"></span>: [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.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">run_by_default</span></code> <span class="target" id="index-33"></span>: [boolean=true] When enabled this output will be created when no specific outputs are requested.</p></li>
</ul>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="copy_files.html" class="btn btn-neutral float-left" title="Files copier" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="download_datasheets.html" class="btn btn-neutral float-right" title="Datasheets downloader" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018-2023, Salvador E. Tropea/INTI/John Beard.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>