config_guide_06-filename-manipulating.md.aba8fc76.js
1 import{_ as e,y as a,x as n,W as t}from"./plugin-vue_export-helper.f07d1dea.js";const g='{"title":"Filename Manipulating","description":"","frontmatter":{},"headers":[{"level":2,"title":"Basics","slug":"basics"},{"level":2,"title":"Per-group Rules","slug":"per-group-rules"},{"level":2,"title":"Capturing Groups","slug":"capturing-groups-as-in-regular-expressions"},{"level":3,"title":"Example:","slug":"example-repeating-the-extension-of-an-item"}],"relativePath":"config/guide/06-filename-manipulating.md","lastUpdated":1692639959838}',s={},o=t(`<h1 id="filename-manipulating" tabindex="-1">Filename Manipulating <a class="header-anchor" href="#filename-manipulating" aria-hidden="true">#</a></h1><p>To this point, our source items must be named as their destination requires, most "dotfiles" begin their names with a literal dot (<code>.</code>), which is sometimes annoying when managing them (like with <a href="https://git-scm.com/doc" target="_blank" rel="noopener noreferrer"><code>git</code></a>). In the meantime, for items that have names not feasible to be altered --- like items from your system directory (e.g. a wallpaper image which is provided as part of a system-wide installed package) --- according to the previous sections, there seem to be no good way to have them tracked by <code>dt-cli</code>.</p><h2 id="basics" tabindex="-1">Basics <a class="header-anchor" href="#basics" aria-hidden="true">#</a></h2><p>To manipulate filename of items, <code>dt-cli</code> provides a configurable <code>rename</code> option in the config file. It is an array of renaming rules, each of them constitutes of a <em>pattern</em> and a <em>substitution rule</em>. A simple renaming rule to rename all items with a "dot-" prefix (like <code>dot-config</code>) to a "dotfile" (like <code>.config</code>, in this case) can be specified in the <code>[global]</code> section as:</p><div class="language-toml"><pre><code><span class="token punctuation">[</span><span class="token table class-name">global</span><span class="token punctuation">]</span> 2 <span class="token key property">rename</span> <span class="token punctuation">=</span> <span class="token punctuation">[</span> 3 <span class="token punctuation">[</span> 4 <span class="token string">"^dot-"</span><span class="token punctuation">,</span> <span class="token comment"># "pattern", must be a valid regular expression</span> 5 <span class="token string">"."</span><span class="token punctuation">,</span> <span class="token comment"># "substitution rule"</span> 6 <span class="token punctuation">]</span><span class="token punctuation">,</span> 7 <span class="token comment"># Multiple renaming rules are applied sequentially, with the previous rule's</span> 8 <span class="token comment"># output being the input of the current rule.</span> 9 <span class="token punctuation">]</span> 10 </code></pre></div><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>Note that only the path components that appear after a group's <code>target</code> will be altered by <code>dt-cli</code>. For example, with the above renaming rule added to your <code>[global]</code> section, a group with <code>target</code> set to <code>/some/path/dot-target</code> will have all its items populated to the exact path <code>/some/path/dot-target</code>, instead of <code>/some/path/.target</code>.</p></div><h2 id="per-group-rules" tabindex="-1">Per-group Rules <a class="header-anchor" href="#per-group-rules" aria-hidden="true">#</a></h2><p>You might have guessed it: <code>rename</code> rules can also be specified on a per-group basis. The way this works is that <code>dt-cli</code> processes renaming rules in the <code>rename</code> array one by one, first <a href="/config/key-references.html#rename"><code>global.rename</code></a>, then <a href="/config/key-references.html#rename-1">the group's <code>rename</code></a> if any.</p><p>For example, to revert the above renaming operation for a single group, you can add a rule to this group:</p><div class="language-toml"><pre><code><span class="token punctuation">[</span><span class="token punctuation">[</span><span class="token table class-name">local</span><span class="token punctuation">]</span><span class="token punctuation">]</span> 11 <span class="token key property">name</span> <span class="token punctuation">=</span> <span class="token string">"Group from which items must have a 'dot-' prefix after syncing"</span> 12 <span class="token comment"># [...omitted...]</span> 13 <span class="token key property">rename</span> <span class="token punctuation">=</span> <span class="token punctuation">[</span> 14 <span class="token punctuation">[</span> 15 <span class="token string">"^."</span><span class="token punctuation">,</span> <span class="token comment"># "pattern", matches prefixing dot</span> 16 <span class="token string">"dot-"</span><span class="token punctuation">,</span> <span class="token comment"># "substitution rule", replace the matched string into "dot-"</span> 17 <span class="token punctuation">]</span><span class="token punctuation">,</span> 18 <span class="token punctuation">]</span> 19 </code></pre></div><p>Apparently, this rule "undo"s the renaming rule in the global section which we previously defined. Items that have names prefixed with <code>dot-</code> in this group will first be renamed to have a <code>.</code> prefix, then the <code>.</code> prefix is renamed back to <code>dot-</code>.</p><h2 id="capturing-groups-as-in-regular-expressions" tabindex="-1">Capturing Groups <sub>(as in regular expressions)</sub> <a class="header-anchor" href="#capturing-groups-as-in-regular-expressions" aria-hidden="true">#</a></h2><p>Since this functionality is powered by <a href="https://docs.rs/regex/latest/regex/" target="_blank" rel="noopener noreferrer">the Rust crate <code>regex</code></a>, substitution rules are supported to the extent which this crate allows. A powerful capability it provides is defining <a href="https://www.regular-expressions.info/refcapture.html" target="_blank" rel="noopener noreferrer">capturing groups</a>. Capturing groups can either be <a href="https://www.regular-expressions.info/named.html" target="_blank" rel="noopener noreferrer">named</a> or <a href="https://www.regular-expressions.info/brackets.html" target="_blank" rel="noopener noreferrer">numbered</a>, which allows arbitrary manipulation to be applied to any synced items.</p><h3 id="example-repeating-the-extension-of-an-item" tabindex="-1">Example: <sub>Repeating the Extension of an Item</sub> <a class="header-anchor" href="#example-repeating-the-extension-of-an-item" aria-hidden="true">#</a></h3><p>To illustrate how capturing groups work, we try to have the destination items to repeat the extension name of their corresponding source items, via capturing groups. With numbered capturing group, this rule can be written as:</p><div class="language-toml"><pre><code><span class="token punctuation">[</span><span class="token table class-name">global</span><span class="token punctuation">]</span> 20 <span class="token key property">rename</span> <span class="token punctuation">=</span> <span class="token punctuation">[</span> 21 <span class="token punctuation">[</span> 22 <span class="token string">"(.*)\\\\.(\\\\w+)"</span><span class="token punctuation">,</span> 23 <span class="token string">"\${1}.\${2}.\${2}"</span><span class="token punctuation">,</span> 24 <span class="token punctuation">]</span> 25 <span class="token punctuation">]</span> 26 </code></pre></div><p>Or, with named capturing group:</p><div class="language-toml"><pre><code><span class="token punctuation">[</span><span class="token table class-name">global</span><span class="token punctuation">]</span> 27 <span class="token key property">rename</span> <span class="token punctuation">=</span> <span class="token punctuation">[</span> 28 <span class="token punctuation">[</span> 29 <span class="token string">"(?P<actual_name>.*)\\\\.(?P<extension>\\\\w+)"</span><span class="token punctuation">,</span> 30 <span class="token string">"\${actual_name}.\${extension}.\${extension}"</span><span class="token punctuation">,</span> 31 <span class="token punctuation">]</span> 32 <span class="token punctuation">]</span> 33 </code></pre></div><p>The outcomes of above two approaches are identical.</p>`,19),p=[o];function i(r,c,l,u,d,h){return n(),a("div",null,p)}var k=e(s,[["render",i]]);export{g as __pageData,k as default};