1  import{_ as e,y as o,x as i,W as t}from"./plugin-vue_export-helper.f07d1dea.js";const f='{"title":"Error Handling","description":"","frontmatter":{},"headers":[{"level":2,"title":"Config Validating","slug":"config-validating"},{"level":2,"title":"Sources Expanding","slug":"sources-expanding"},{"level":2,"title":"Syncing","slug":"syncing"}],"relativePath":"config/guide/99-error-handling.md","lastUpdated":1692639959838}',s={},n=t('<h1 id="error-handling" tabindex="-1">Error Handling <a class="header-anchor" href="#error-handling" aria-hidden="true">#</a></h1><p>For an application that works with your daily configuration files, it&#39;s crucial that it handles error in an expectable manner.</p><p><code>dt-cli</code> looks for possible errors in 3 stages throughout its running course, this section describes the checking in details.</p><h2 id="config-validating" tabindex="-1">Config Validating <a class="header-anchor" href="#config-validating" aria-hidden="true">#</a></h2><p>Firstly, after a config file has been successfully loaded into memory, <code>dt-cli</code> validates each field of the config object. Specifically, the following cases are considered invalid:</p><ul><li>Any group that has empty <code>name</code>/<code>base</code>/<code>target</code></li><li>Any group name that contains <code>/</code> (group names are used for subdirectory names under <code>staging</code> directory, so slashes are not allowed)</li><li>Any group that has the same <code>base</code> and <code>target</code></li><li>Any group whose <code>base</code> contains any occurrences of <code>hostname_sep</code></li><li>Any group whose <code>sources</code> contains any item that contains any occurrences of <code>hostname_sep</code></li><li>Any source item that: <ul><li>begins with <code>../</code> (references the parent of base directory)</li><li>begins with <code>~</code> or <code>/</code> (path is absolute)</li><li>is <code>.*</code> (bad globbing pattern, it will expand to parent directory)</li><li>ends with <code>/.*</code> (bad globbing pattern)</li></ul></li></ul><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Checking operations in this step do not touch the filesystem, but only match string patterns. This is for spotting obvious errors as fast as possible.</p></div><h2 id="sources-expanding" tabindex="-1">Sources Expanding <a class="header-anchor" href="#sources-expanding" aria-hidden="true">#</a></h2><p>If the above validating step passed successfully, <code>dt-cli</code> begins to iterate through every group, recursively expand all sources according to their file hierarchy, the <code>base</code>s are also expanded to <a href="/features/01-host-specific.html">host-specific</a> ones wherever possible. The following cases are considered invalid while expanding <code>sources</code> and <code>base</code>:</p><ul><li>The group&#39;s <code>base</code> exists but is not a directory</li><li>The group&#39;s <code>target</code> exists and is not a directory</li><li>The group&#39;s <code>target</code> is non-existent but cannot be created</li><li>When any group uses the <code>Symlink</code> <a href="/config/guide/03-syncing-methods.html">syncing method</a>: <ul><li><code>staging</code> exists but iis not a directory</li><li><code>staging</code> is non-existent but cannot be created</li></ul></li></ul><div class="info custom-block"><p class="custom-block-title">INFO</p><p>Non-existent <code>base</code> will not trigger an error but only a warning that complains about not matching anything.</p></div><div class="info custom-block"><p class="custom-block-title">INFO</p><p>Broken symlinks and item types other than <code>file</code> or <code>directory</code> are ignored and warned during expanding. These items will not cause errors.</p></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>Expanding operations in this step do not create or modify anything, but only query the filesystem to check for existences and permissions.</p></div><h2 id="syncing" tabindex="-1">Syncing <a class="header-anchor" href="#syncing" aria-hidden="true">#</a></h2><p>Finally, if no error could be found, <code>dt-cli</code> carefully (and efficiently) syncs the <strong>expanded</strong> source items to the target directory. During this process, according to the values of <a href="/config/key-references.html#allow-overwrite-1"><code>allow_overwrite</code></a>, different level of logging messages will show up when encountered with existing target items. Any other cases (e.g. a directory changes its permission to readonly for no reason) unhandled by the above 2 steps will cause <code>dt-cli</code> to panic.</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>If you think there&#39;s anything missing here, your contribution is welcome! Start by following the <a href="/contributing.html">contributing guide</a>.</p></div>',16),a=[n];function c(r,d,l,h,g,u){return i(),o("div",null,a)}var y=e(s,[["render",c]]);export{f as __pageData,y as default};