features_03-filename-manipulating.md.4f4fb6b1.js
1 import{_ as e,y as a,x as n,W as t}from"./plugin-vue_export-helper.f07d1dea.js";const m='{"title":"Filename Manipulating","description":"","frontmatter":{},"headers":[{"level":2,"title":"Background","slug":"background"},{"level":2,"title":"rename","slug":"rename"}],"relativePath":"features/03-filename-manipulating.md","lastUpdated":1692639959838}',s={},o=t(`<h1 id="filename-manipulating-examples" tabindex="-1">Filename Manipulating <sub>[<a href="/config/guide/06-filename-manipulating.html"><strong>Examples</strong></a>]</sub> <a class="header-anchor" href="#filename-manipulating-examples" aria-hidden="true">#</a></h1><p>Being able to have different names for the source items and their destination items arises as a vital need in some use cases. <code>dt-cli</code> offers this utility via a convenient and versatile way, with the power of regular expressions.</p><h2 id="background" tabindex="-1">Background <a class="header-anchor" href="#background" aria-hidden="true">#</a></h2><p>This is not new. <a href="https://www.gnu.org/software/stow/" target="_blank" rel="noopener noreferrer">GNU Stow</a> has an option <code>--dotfiles</code>, which explains this in <a href="https://man.archlinux.org/man/community/stow/stow.8.en" target="_blank" rel="noopener noreferrer">man:stow(8)</a>:</p><blockquote><p><code>--dotfiles</code>:</p><p>Enable special handling for "dotfiles" (files or folders whose name begins with a period) in the package directory. If this option is enabled, Stow will add a preprocessing step for each file or folder whose name begins with "dot-", and replace the "dot-" prefix in the name by a period (.). This is useful when Stow is used to manage collections of dotfiles, to avoid having a package directory full of hidden files.</p></blockquote><p><code>dt-cli</code>'s filename manipulating capability functions in a similar way, but in a much more powerful way: you can specify arbitrary renaming rules, thanks to the flexibility of regular expressions; you can also specify arbitrary number of renaming rules, multiple defined rules will apply to your items one-after-another.</p><h2 id="rename" tabindex="-1"><code>rename</code> <a class="header-anchor" href="#rename" aria-hidden="true">#</a></h2><p>Renaming rules are defined in the <a href="/config/key-references.html#rename"><code>rename</code></a> array. A renaming rule is represented by a 2-tuple in the config file, where the first element is a regular expression <em>pattern</em> and the second element is a <em>substitution rule</em>. To achieve an identical behaviour as the <code>--dotfiles</code> option with <a href="https://www.gnu.org/software/stow/" target="_blank" rel="noopener noreferrer">GNU Stow</a>, a renaming rule can be set in <code>global</code> section of the config file 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"</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><p>Since <code>dt-cli</code>'s renaming capability is powered by regular expressions, it also supports regular expression features like <a href="https://www.regular-expressions.info/refcapture.html" target="_blank" rel="noopener noreferrer">capturing groups</a>, which allows infinitely flexible filename manipulation. More examples can be found in the <a href="/config/guide/06-filename-manipulating.html">hands-on guide</a>.</p>`,10),i=[o];function r(l,p,c,u,d,h){return n(),a("div",null,i)}var g=e(s,[["render",r]]);export{m as __pageData,g as default};