diff --git a/main/404.html b/main/404.html
index 944c0948..b3f4875c 100644
--- a/main/404.html
+++ b/main/404.html
@@ -249,6 +249,26 @@
   
     
     
+      <li class="md-tabs__item">
+        <a href="/main/guides/unmatched-formatters/" class="md-tabs__link">
+          
+  
+    
+  
+  Guides
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
+  
+    
+    
       <li class="md-tabs__item">
         <a href="/main/contributing/code/" class="md-tabs__link">
           
@@ -456,8 +476,6 @@
       
         
       
-        
-      
     
     
       
@@ -477,7 +495,7 @@
             
   
   <span class="md-ellipsis">
-    Contributing
+    Guides
   </span>
   
 
@@ -486,6 +504,80 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+            Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="/main/guides/unmatched-formatters/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    
+    
+      
+        
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        
+          
+          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Contributing
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3">
             <span class="md-nav__icon md-icon"></span>
             Contributing
           </label>
@@ -563,10 +655,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
         
           
-          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -577,8 +669,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_4">
             <span class="md-nav__icon md-icon"></span>
             Reference
           </label>
diff --git a/main/contributing/code/index.html b/main/contributing/code/index.html
index be970501..b35a3536 100644
--- a/main/contributing/code/index.html
+++ b/main/contributing/code/index.html
@@ -13,7 +13,7 @@
         <link rel="canonical" href="https://treefmt.com/main/contributing/code/">
       
       
-        <link rel="prev" href="../../getting-started/usage/">
+        <link rel="prev" href="../../guides/unmatched-formatters/">
       
       
         <link rel="next" href="../docs/">
@@ -257,6 +257,26 @@
         
   
   
+  
+    
+    
+      <li class="md-tabs__item">
+        <a href="../../guides/unmatched-formatters/" class="md-tabs__link">
+          
+  
+    
+  
+  Guides
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
     
   
   
@@ -462,6 +482,78 @@
       
   
   
+  
+  
+    
+    
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" >
+        
+          
+          <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Guides
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+            Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../guides/unmatched-formatters/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
     
   
   
@@ -488,10 +580,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
         
           
-          <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="">
+          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
             
   
   <span class="md-ellipsis">
@@ -502,8 +594,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_2">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_3">
             <span class="md-nav__icon md-icon"></span>
             Contributing
           </label>
@@ -666,10 +758,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
         
           
-          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -680,8 +772,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_4">
             <span class="md-nav__icon md-icon"></span>
             Reference
           </label>
@@ -1008,7 +1100,7 @@ <h2 id="documentation">Documentation</h2>
       <nav class="md-footer__inner md-grid" aria-label="Footer" >
         
           
-          <a href="../../getting-started/usage/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Usage">
+          <a href="../../guides/unmatched-formatters/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Handling Unmatched Files">
             <div class="md-footer__button md-icon">
               
               <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
@@ -1018,7 +1110,7 @@ <h2 id="documentation">Documentation</h2>
                 Previous
               </span>
               <div class="md-ellipsis">
-                Usage
+                Handling Unmatched Files
               </div>
             </div>
           </a>
diff --git a/main/contributing/docs/index.html b/main/contributing/docs/index.html
index dd060478..b3b6160b 100644
--- a/main/contributing/docs/index.html
+++ b/main/contributing/docs/index.html
@@ -257,6 +257,26 @@
         
   
   
+  
+    
+    
+      <li class="md-tabs__item">
+        <a href="../../guides/unmatched-formatters/" class="md-tabs__link">
+          
+  
+    
+  
+  Guides
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
     
   
   
@@ -462,6 +482,78 @@
       
   
   
+  
+  
+    
+    
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" >
+        
+          
+          <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Guides
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+            Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../guides/unmatched-formatters/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
     
   
   
@@ -488,10 +580,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
         
           
-          <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="">
+          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
             
   
   <span class="md-ellipsis">
@@ -502,8 +594,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_2">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_3">
             <span class="md-nav__icon md-icon"></span>
             Contributing
           </label>
@@ -639,10 +731,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
         
           
-          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -653,8 +745,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_4">
             <span class="md-nav__icon md-icon"></span>
             Reference
           </label>
diff --git a/main/getting-started/configure/index.html b/main/getting-started/configure/index.html
index aae92416..4205a5d0 100644
--- a/main/getting-started/configure/index.html
+++ b/main/getting-started/configure/index.html
@@ -262,6 +262,26 @@
   
     
     
+      <li class="md-tabs__item">
+        <a href="../../guides/unmatched-formatters/" class="md-tabs__link">
+          
+  
+    
+  
+  Guides
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
+  
+    
+    
       <li class="md-tabs__item">
         <a href="../../contributing/code/" class="md-tabs__link">
           
@@ -784,8 +804,6 @@
       
         
       
-        
-      
     
     
       
@@ -805,7 +823,7 @@
             
   
   <span class="md-ellipsis">
-    Contributing
+    Guides
   </span>
   
 
@@ -814,6 +832,80 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+            Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../guides/unmatched-formatters/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    
+    
+      
+        
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        
+          
+          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Contributing
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3">
             <span class="md-nav__icon md-icon"></span>
             Contributing
           </label>
@@ -891,10 +983,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
         
           
-          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -905,8 +997,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_4">
             <span class="md-nav__icon md-icon"></span>
             Reference
           </label>
diff --git a/main/getting-started/install/index.html b/main/getting-started/install/index.html
index ee096c22..21f7dd77 100644
--- a/main/getting-started/install/index.html
+++ b/main/getting-started/install/index.html
@@ -260,6 +260,26 @@
   
     
     
+      <li class="md-tabs__item">
+        <a href="../../guides/unmatched-formatters/" class="md-tabs__link">
+          
+  
+    
+  
+  Guides
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
+  
+    
+    
       <li class="md-tabs__item">
         <a href="../../contributing/code/" class="md-tabs__link">
           
@@ -554,8 +574,6 @@
       
         
       
-        
-      
     
     
       
@@ -575,7 +593,7 @@
             
   
   <span class="md-ellipsis">
-    Contributing
+    Guides
   </span>
   
 
@@ -584,6 +602,80 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+            Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../guides/unmatched-formatters/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    
+    
+      
+        
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        
+          
+          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Contributing
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3">
             <span class="md-nav__icon md-icon"></span>
             Contributing
           </label>
@@ -661,10 +753,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
         
           
-          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -675,8 +767,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_4">
             <span class="md-nav__icon md-icon"></span>
             Reference
           </label>
diff --git a/main/getting-started/usage/index.html b/main/getting-started/usage/index.html
index 228704f4..3b6ab966 100644
--- a/main/getting-started/usage/index.html
+++ b/main/getting-started/usage/index.html
@@ -16,7 +16,7 @@
         <link rel="prev" href="../configure/">
       
       
-        <link rel="next" href="../../contributing/code/">
+        <link rel="next" href="../../guides/unmatched-formatters/">
       
       
       <link rel="icon" href="../../assets/images/logo.png">
@@ -262,6 +262,26 @@
   
     
     
+      <li class="md-tabs__item">
+        <a href="../../guides/unmatched-formatters/" class="md-tabs__link">
+          
+  
+    
+  
+  Guides
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
+  
+    
+    
       <li class="md-tabs__item">
         <a href="../../contributing/code/" class="md-tabs__link">
           
@@ -559,8 +579,6 @@
       
         
       
-        
-      
     
     
       
@@ -580,7 +598,7 @@
             
   
   <span class="md-ellipsis">
-    Contributing
+    Guides
   </span>
   
 
@@ -589,6 +607,80 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+            Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../guides/unmatched-formatters/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    
+    
+      
+        
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        
+          
+          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Contributing
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3">
             <span class="md-nav__icon md-icon"></span>
             Contributing
           </label>
@@ -666,10 +758,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
         
           
-          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -680,8 +772,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_4">
             <span class="md-nav__icon md-icon"></span>
             Reference
           </label>
@@ -1057,13 +1149,13 @@ <h2 id="ci-integration">CI integration</h2>
         
         
           
-          <a href="../../contributing/code/" class="md-footer__link md-footer__link--next" aria-label="Next: Code">
+          <a href="../../guides/unmatched-formatters/" class="md-footer__link md-footer__link--next" aria-label="Next: Handling Unmatched Files">
             <div class="md-footer__title">
               <span class="md-footer__direction">
                 Next
               </span>
               <div class="md-ellipsis">
-                Code
+                Handling Unmatched Files
               </div>
             </div>
             <div class="md-footer__button md-icon">
diff --git a/main/guides/unmatched-formatters/index.html b/main/guides/unmatched-formatters/index.html
new file mode 100644
index 00000000..1431d9fc
--- /dev/null
+++ b/main/guides/unmatched-formatters/index.html
@@ -0,0 +1,1059 @@
+
+<!doctype html>
+<html lang="en" class="no-js">
+  <head>
+    
+      <meta charset="utf-8">
+      <meta name="viewport" content="width=device-width,initial-scale=1">
+      
+        <meta name="description" content="One CLI to format your repo">
+      
+      
+      
+        <link rel="canonical" href="https://treefmt.com/main/guides/unmatched-formatters/">
+      
+      
+        <link rel="prev" href="../../getting-started/usage/">
+      
+      
+        <link rel="next" href="../../contributing/code/">
+      
+      
+      <link rel="icon" href="../../assets/images/logo.png">
+      <meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.5.39">
+    
+    
+      
+        <title>Handling Unmatched Files - Treefmt</title>
+      
+    
+    
+      <link rel="stylesheet" href="../../assets/stylesheets/main.8c3ca2c6.min.css">
+      
+        
+        <link rel="stylesheet" href="../../assets/stylesheets/palette.06af60db.min.css">
+      
+      
+
+
+    
+    
+      
+    
+    
+      
+        
+        
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
+        <style>:root{--md-text-font:"Inter";--md-code-font:"Roboto Mono"}</style>
+      
+    
+    
+      <link rel="stylesheet" href="../../stylesheets/extra.css">
+    
+    <script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
+    
+      
+
+    
+    
+    
+  </head>
+  
+  
+    
+    
+      
+    
+    
+    
+    
+    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo">
+  
+    
+    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
+    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
+    <label class="md-overlay" for="__drawer"></label>
+    <div data-md-component="skip">
+      
+        
+        <a href="#handling-unmatched-files" class="md-skip">
+          Skip to content
+        </a>
+      
+    </div>
+    <div data-md-component="announce">
+      
+    </div>
+    
+      <div data-md-color-scheme="default" data-md-component="outdated" hidden>
+        
+      </div>
+    
+    
+      
+
+<header class="md-header" data-md-component="header">
+  <nav class="md-header__inner md-grid" aria-label="Header">
+    <a href="../.." title="Treefmt" class="md-header__button md-logo" aria-label="Treefmt" data-md-component="logo">
+      
+  <img src="../../assets/images/logo.png" alt="logo">
+
+    </a>
+    <label class="md-header__button md-icon" for="__drawer">
+      
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
+    </label>
+    <div class="md-header__title" data-md-component="header-title">
+      <div class="md-header__ellipsis">
+        <div class="md-header__topic">
+          <span class="md-ellipsis">
+            Treefmt
+          </span>
+        </div>
+        <div class="md-header__topic" data-md-component="header-topic">
+          <span class="md-ellipsis">
+            
+              Handling Unmatched Files
+            
+          </span>
+        </div>
+      </div>
+    </div>
+    
+      
+        <form class="md-header__option" data-md-component="palette">
+  
+    
+    
+    
+    <input class="md-option" data-md-color-media="(prefers-color-scheme)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo"  aria-label="Switch to light mode"  type="radio" name="__palette" id="__palette_0">
+    
+      <label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m14.3 16-.7-2h-3.2l-.7 2H7.8L11 7h2l3.2 9zM20 8.69V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12zm-9.15 3.96h2.3L12 9z"/></svg>
+      </label>
+    
+  
+    
+    
+    
+    <input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="indigo" data-md-color-accent="indigo"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_1">
+    
+      <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
+      </label>
+    
+  
+    
+    
+    
+    <input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="indigo" data-md-color-accent="indigo"  aria-label="Switch to system preference"  type="radio" name="__palette" id="__palette_2">
+    
+      <label class="md-header__button md-icon" title="Switch to system preference" for="__palette_0" hidden>
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg>
+      </label>
+    
+  
+</form>
+      
+    
+    
+      <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
+    
+    
+    
+      <label class="md-header__button md-icon" for="__search">
+        
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
+      </label>
+      <div class="md-search" data-md-component="search" role="dialog">
+  <label class="md-search__overlay" for="__search"></label>
+  <div class="md-search__inner" role="search">
+    <form class="md-search__form" name="search">
+      <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
+      <label class="md-search__icon md-icon" for="__search">
+        
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
+        
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
+      </label>
+      <nav class="md-search__options" aria-label="Search">
+        
+          <a href="javascript:void(0)" class="md-search__icon md-icon" title="Share" aria-label="Share" data-clipboard data-clipboard-text="" data-md-component="search-share" tabindex="-1">
+            
+            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18 16.08c-.76 0-1.44.3-1.96.77L8.91 12.7c.05-.23.09-.46.09-.7s-.04-.47-.09-.7l7.05-4.11c.54.5 1.25.81 2.04.81a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3c0 .24.04.47.09.7L8.04 9.81C7.5 9.31 6.79 9 6 9a3 3 0 0 0-3 3 3 3 0 0 0 3 3c.79 0 1.5-.31 2.04-.81l7.12 4.15c-.05.21-.08.43-.08.66 0 1.61 1.31 2.91 2.92 2.91s2.92-1.3 2.92-2.91A2.92 2.92 0 0 0 18 16.08"/></svg>
+          </a>
+        
+        <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
+          
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
+        </button>
+      </nav>
+      
+        <div class="md-search__suggest" data-md-component="search-suggest"></div>
+      
+    </form>
+    <div class="md-search__output">
+      <div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
+        <div class="md-search-result" data-md-component="search-result">
+          <div class="md-search-result__meta">
+            Initializing search
+          </div>
+          <ol class="md-search-result__list" role="presentation"></ol>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+    
+    
+      <div class="md-header__source">
+        <a href="https://github.com/numtide/treefmt" title="Go to repository" class="md-source" data-md-component="source">
+  <div class="md-source__icon md-icon">
+    
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
+  </div>
+  <div class="md-source__repository">
+    numtide/treefmt
+  </div>
+</a>
+      </div>
+    
+  </nav>
+  
+</header>
+    
+    <div class="md-container" data-md-component="container">
+      
+      
+        
+          
+            
+<nav class="md-tabs" aria-label="Tabs" data-md-component="tabs">
+  <div class="md-grid">
+    <ul class="md-tabs__list">
+      
+        
+  
+  
+  
+    
+    
+      <li class="md-tabs__item">
+        <a href="../../getting-started/install/" class="md-tabs__link">
+          
+  
+    
+  
+  Getting started
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
+    
+  
+  
+    
+    
+      <li class="md-tabs__item md-tabs__item--active">
+        <a href="./" class="md-tabs__link">
+          
+  
+    
+  
+  Guides
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
+  
+    
+    
+      <li class="md-tabs__item">
+        <a href="../../contributing/code/" class="md-tabs__link">
+          
+  
+    
+  
+  Contributing
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
+  
+    
+    
+      <li class="md-tabs__item">
+        <a href="../../reference/formatter-spec/" class="md-tabs__link">
+          
+  
+    
+  
+  Reference
+
+        </a>
+      </li>
+    
+  
+
+      
+    </ul>
+  </div>
+</nav>
+          
+        
+      
+      <main class="md-main" data-md-component="main">
+        <div class="md-main__inner md-grid">
+          
+            
+              
+              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
+                <div class="md-sidebar__scrollwrap">
+                  <div class="md-sidebar__inner">
+                    
+
+
+  
+
+
+<nav class="md-nav md-nav--primary md-nav--lifted" aria-label="Navigation" data-md-level="0">
+  <label class="md-nav__title" for="__drawer">
+    <a href="../.." title="Treefmt" class="md-nav__button md-logo" aria-label="Treefmt" data-md-component="logo">
+      
+  <img src="../../assets/images/logo.png" alt="logo">
+
+    </a>
+    Treefmt
+  </label>
+  
+    <div class="md-nav__source">
+      <a href="https://github.com/numtide/treefmt" title="Go to repository" class="md-source" data-md-component="source">
+  <div class="md-source__icon md-icon">
+    
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81"/></svg>
+  </div>
+  <div class="md-source__repository">
+    numtide/treefmt
+  </div>
+</a>
+    </div>
+  
+  <ul class="md-nav__list" data-md-scrollfix>
+    
+      
+      
+  
+  
+  
+  
+    
+    
+      
+        
+      
+        
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" >
+        
+          
+          <label class="md-nav__link" for="__nav_1" id="__nav_1_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Getting started
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_1">
+            <span class="md-nav__icon md-icon"></span>
+            Getting started
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../getting-started/install/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Install
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../getting-started/configure/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Configure
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../getting-started/usage/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Usage
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
+    
+  
+  
+  
+    
+    
+      
+        
+      
+    
+    
+      
+        
+        
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" checked>
+        
+          
+          <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="">
+            
+  
+  <span class="md-ellipsis">
+    Guides
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+            Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+    
+  
+  
+  
+    <li class="md-nav__item md-nav__item--active">
+      
+      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
+      
+      
+        
+      
+      
+        <label class="md-nav__link md-nav__link--active" for="__toc">
+          
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+          <span class="md-nav__icon md-icon"></span>
+        </label>
+      
+      <a href="./" class="md-nav__link md-nav__link--active">
+        
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+      </a>
+      
+        
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+  
+  
+  
+    
+  
+  
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#customizing-notifications" class="md-nav__link">
+    <span class="md-ellipsis">
+      Customizing Notifications
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Customizing Notifications">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#reducing-log-verbosity" class="md-nav__link">
+    <span class="md-ellipsis">
+      Reducing Log Verbosity
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#enforcing-strict-matching" class="md-nav__link">
+    <span class="md-ellipsis">
+      Enforcing Strict Matching
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+    </ul>
+  
+</nav>
+      
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    
+    
+      
+        
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        
+          
+          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Contributing
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3">
+            <span class="md-nav__icon md-icon"></span>
+            Contributing
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../contributing/code/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Code
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../contributing/docs/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Documentation
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    
+    
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
+        
+          
+          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Reference
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_4">
+            <span class="md-nav__icon md-icon"></span>
+            Reference
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../reference/formatter-spec/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Formatter Specification
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+  </ul>
+</nav>
+                  </div>
+                </div>
+              </div>
+            
+            
+              
+              <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
+                <div class="md-sidebar__scrollwrap">
+                  <div class="md-sidebar__inner">
+                    
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+  
+  
+  
+    
+  
+  
+    <label class="md-nav__title" for="__toc">
+      <span class="md-nav__icon md-icon"></span>
+      Table of contents
+    </label>
+    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+      
+        <li class="md-nav__item">
+  <a href="#customizing-notifications" class="md-nav__link">
+    <span class="md-ellipsis">
+      Customizing Notifications
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Customizing Notifications">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#reducing-log-verbosity" class="md-nav__link">
+    <span class="md-ellipsis">
+      Reducing Log Verbosity
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#enforcing-strict-matching" class="md-nav__link">
+    <span class="md-ellipsis">
+      Enforcing Strict Matching
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+    </ul>
+  
+</nav>
+                  </div>
+                </div>
+              </div>
+            
+          
+          
+            <div class="md-content" data-md-component="content">
+              <article class="md-content__inner md-typeset">
+                
+                  
+
+  
+  
+
+
+<h1 id="handling-unmatched-files">Handling Unmatched Files</h1>
+<p>By default, treefmt lists all files that aren't matched by any formatter:</p>
+<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-1">1</a></span>
+<span class="normal"><a href="#__codelineno-0-2">2</a></span>
+<span class="normal"><a href="#__codelineno-0-3">3</a></span>
+<span class="normal"><a href="#__codelineno-0-4">4</a></span>
+<span class="normal"><a href="#__codelineno-0-5">5</a></span>
+<span class="normal"><a href="#__codelineno-0-6">6</a></span>
+<span class="normal"><a href="#__codelineno-0-7">7</a></span>
+<span class="normal"><a href="#__codelineno-0-8">8</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1"></a><span class="gp">$ </span>treefmt
+<a id="__codelineno-0-2" name="__codelineno-0-2"></a><span class="go">WARN no formatter for path: .gitignore</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3"></a><span class="go">WARN no formatter for path: LICENSE</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4"></a><span class="go">WARN no formatter for path: README.md</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5"></a><span class="go">WARN no formatter for path: go.mod</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6"></a><span class="go">WARN no formatter for path: go.sum</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7"></a><span class="go">WARN no formatter for path: build/build.go</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8"></a><span class="gp"># </span>...
+</code></pre></div></td></tr></table></div>
+<p>This helps you decide whether to add formatters for specific files or ignore them entirely.</p>
+<h2 id="customizing-notifications">Customizing Notifications</h2>
+<h3 id="reducing-log-verbosity">Reducing Log Verbosity</h3>
+<p>If you find the unmatched file warnings too noisy, you can lower the logging level in your config:</p>
+<p><code>treefmt.toml</code>:
+<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-1-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1"></a><span class="n">on-unmatched</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;debug&quot;</span>
+</code></pre></div></td></tr></table></div></p>
+<p>To later find out what files are unmatched, you can override this setting via the command line:
+<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-2-1">1</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1"></a><span class="gp">$ </span>treefmt<span class="w"> </span>--on-unmatched<span class="w"> </span>warn
+</code></pre></div></td></tr></table></div></p>
+<h3 id="enforcing-strict-matching">Enforcing Strict Matching</h3>
+<p>Another stricter policy approach is to fail the run if any unmatched files are found.
+This can be paired with an <code>excludes</code> list to ignore specific files:</p>
+<p><code>treefmt.toml</code>:
+<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-3-1">1</a></span>
+<span class="normal"><a href="#__codelineno-3-2">2</a></span>
+<span class="normal"><a href="#__codelineno-3-3">3</a></span>
+<span class="normal"><a href="#__codelineno-3-4">4</a></span>
+<span class="normal"><a href="#__codelineno-3-5">5</a></span>
+<span class="normal"><a href="#__codelineno-3-6">6</a></span>
+<span class="normal"><a href="#__codelineno-3-7">7</a></span>
+<span class="normal"><a href="#__codelineno-3-8">8</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1"></a><span class="c1"># Fail if any unmatched files are found</span>
+<a id="__codelineno-3-2" name="__codelineno-3-2"></a><span class="n">on-unmatched</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">&quot;fatal&quot;</span>
+<a id="__codelineno-3-3" name="__codelineno-3-3"></a>
+<a id="__codelineno-3-4" name="__codelineno-3-4"></a><span class="c1"># List files to explicitly ignore</span>
+<a id="__codelineno-3-5" name="__codelineno-3-5"></a><span class="n">excludes</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span>
+<a id="__codelineno-3-6" name="__codelineno-3-6"></a><span class="w">  </span><span class="s2">&quot;LICENCE&quot;</span><span class="p">,</span>
+<a id="__codelineno-3-7" name="__codelineno-3-7"></a><span class="w">  </span><span class="s2">&quot;go.sum&quot;</span><span class="p">,</span>
+<a id="__codelineno-3-8" name="__codelineno-3-8"></a><span class="p">]</span>
+</code></pre></div></td></tr></table></div></p>
+
+
+
+
+
+
+
+
+
+
+
+
+                
+              </article>
+            </div>
+          
+          
+<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
+        </div>
+        
+      </main>
+      
+        <footer class="md-footer">
+  
+    
+      
+      <nav class="md-footer__inner md-grid" aria-label="Footer" >
+        
+          
+          <a href="../../getting-started/usage/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Usage">
+            <div class="md-footer__button md-icon">
+              
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
+            </div>
+            <div class="md-footer__title">
+              <span class="md-footer__direction">
+                Previous
+              </span>
+              <div class="md-ellipsis">
+                Usage
+              </div>
+            </div>
+          </a>
+        
+        
+          
+          <a href="../../contributing/code/" class="md-footer__link md-footer__link--next" aria-label="Next: Code">
+            <div class="md-footer__title">
+              <span class="md-footer__direction">
+                Next
+              </span>
+              <div class="md-ellipsis">
+                Code
+              </div>
+            </div>
+            <div class="md-footer__button md-icon">
+              
+              <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg>
+            </div>
+          </a>
+        
+      </nav>
+    
+  
+  <div class="md-footer-meta md-typeset">
+    <div class="md-footer-meta__inner md-grid">
+      <div class="md-copyright">
+  
+    <div class="md-copyright__highlight">
+      Content on this site is licensed under a <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons  Attribution-ShareAlike 4.0 International license</a>.
+    </div>
+  
+  
+    Made with
+    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
+      Material for MkDocs
+    </a>
+  
+</div>
+      
+        <div class="md-social">
+  
+    
+    
+    
+    
+      
+      
+    
+    <a href="https://github.com/numtide" target="_blank" rel="noopener" title="github.com" class="md-social__link">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8M97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg>
+    </a>
+  
+    
+    
+    
+    
+      
+      
+    
+    <a href="https://x.com/numtide" target="_blank" rel="noopener" title="x.com" class="md-social__link">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M389.2 48h70.6L305.6 224.2 487 464H345L233.7 318.6 106.5 464H35.8l164.9-188.5L26.8 48h145.6l100.5 132.9zm-24.8 373.8h39.1L151.1 88h-42z"/></svg>
+    </a>
+  
+    
+    
+      
+    
+    
+    
+      
+      
+    
+    <a href="https://fosstodon.org/@numtide" target="_blank" rel="noopener me" title="fosstodon.org" class="md-social__link">
+      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2024 Fonticons, Inc.--><path d="M433 179.11c0-97.2-63.71-125.7-63.71-125.7-62.52-28.7-228.56-28.4-290.48 0 0 0-63.72 28.5-63.72 125.7 0 115.7-6.6 259.4 105.63 289.1 40.51 10.7 75.32 13 103.33 11.4 50.81-2.8 79.32-18.1 79.32-18.1l-1.7-36.9s-36.31 11.4-77.12 10.1c-40.41-1.4-83-4.4-89.63-54a102.5 102.5 0 0 1-.9-13.9c85.63 20.9 158.65 9.1 178.75 6.7 56.12-6.7 105-41.3 111.23-72.9 9.8-49.8 9-121.5 9-121.5m-75.12 125.2h-46.63v-114.2c0-49.7-64-51.6-64 6.9v62.5h-46.33V197c0-58.5-64-56.6-64-6.9v114.2H90.19c0-122.1-5.2-147.9 18.41-175 25.9-28.9 79.82-30.8 103.83 6.1l11.6 19.5 11.6-19.5c24.11-37.1 78.12-34.8 103.83-6.1 23.71 27.3 18.4 53 18.4 175z"/></svg>
+    </a>
+  
+</div>
+      
+    </div>
+  </div>
+</footer>
+      
+    </div>
+    <div class="md-dialog" data-md-component="dialog">
+      <div class="md-dialog__inner md-typeset"></div>
+    </div>
+    
+    
+    <script id="__config" type="application/json">{"base": "../..", "features": ["content.code.annotate", "content.code.copy", "navigation.footer", "navigation.indexes", "navigation.path", "navigation.sections", "navigation.tabs", "navigation.tracking", "search.highlight", "search.share", "search.suggest"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": {"provider": "mike"}}</script>
+    
+    
+      <script src="../../assets/javascripts/bundle.525ec568.min.js"></script>
+      
+    
+  </body>
+</html>
\ No newline at end of file
diff --git a/main/reference/formatter-spec/index.html b/main/reference/formatter-spec/index.html
index 99643b62..1a507058 100644
--- a/main/reference/formatter-spec/index.html
+++ b/main/reference/formatter-spec/index.html
@@ -258,6 +258,26 @@
   
     
     
+      <li class="md-tabs__item">
+        <a href="../../guides/unmatched-formatters/" class="md-tabs__link">
+          
+  
+    
+  
+  Guides
+
+        </a>
+      </li>
+    
+  
+
+      
+        
+  
+  
+  
+    
+    
       <li class="md-tabs__item">
         <a href="../../contributing/code/" class="md-tabs__link">
           
@@ -467,8 +487,6 @@
       
         
       
-        
-      
     
     
       
@@ -488,7 +506,7 @@
             
   
   <span class="md-ellipsis">
-    Contributing
+    Guides
   </span>
   
 
@@ -497,6 +515,80 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_2">
+            <span class="md-nav__icon md-icon"></span>
+            Guides
+          </label>
+          <ul class="md-nav__list" data-md-scrollfix>
+            
+              
+                
+  
+  
+  
+  
+    <li class="md-nav__item">
+      <a href="../../guides/unmatched-formatters/" class="md-nav__link">
+        
+  
+  <span class="md-ellipsis">
+    Handling Unmatched Files
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+              
+            
+          </ul>
+        </nav>
+      
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
+    
+    
+      
+        
+      
+        
+      
+    
+    
+      
+      
+        
+      
+    
+    
+    <li class="md-nav__item md-nav__item--nested">
+      
+        
+        
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
+        
+          
+          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
+            
+  
+  <span class="md-ellipsis">
+    Contributing
+  </span>
+  
+
+            <span class="md-nav__icon md-icon"></span>
+          </label>
+        
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_3">
             <span class="md-nav__icon md-icon"></span>
             Contributing
           </label>
@@ -579,10 +671,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" checked>
         
           
-          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
+          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="">
             
   
   <span class="md-ellipsis">
@@ -593,8 +685,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_3">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_4">
             <span class="md-nav__icon md-icon"></span>
             Reference
           </label>
diff --git a/main/search/search_index.json b/main/search/search_index.json
index 74a8b2ad..c4e50e56 100644
--- a/main/search/search_index.json
+++ b/main/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"contributing/code/","title":"Code","text":""},{"location":"contributing/code/#pre-requisites","title":"Pre-requisites","text":"<p>You will need to have the following installed:</p> <ul> <li>Nix</li> <li>Direnv</li> </ul> <p>Important</p> <p>We use a Flake-based workflow. You can certainly develop for <code>treefmt</code> without Flakes and leverage much of what is listed below, but it is left up to the reader to determine how to make that work.</p>"},{"location":"contributing/code/#go-development","title":"Go development","text":"<p>The default devshell provides all the necessary tooling and utilities for working on <code>treefmt</code>.</p> nix/devshells/default.nix<pre><code>{\n  pkgs,\n  perSystem,\n  ...\n}:\npkgs.mkShellNoCC {\n  env.GOROOT = \"${pkgs.go}/share/go\";\n\n  packages =\n    (with pkgs; [\n      go\n      goreleaser\n      golangci-lint\n      delve\n      pprof\n      graphviz\n      cobra-cli\n      enumer\n      perSystem.gomod2nix.default\n    ])\n    ++ # include formatters for development and testing\n    (import ../packages/treefmt/formatters.nix pkgs);\n}\n</code></pre> <p>Direnv should load this by default when entering the root of the repository.</p> <p>For the most part, you should be able to develop normally as you would any other Go program.</p> <p>Important</p> <p>When you have completed making any changes and have tested it as you would any other Go program, it is important to ensure it works when run as a Nix package.</p> <p>This can be done with <code>nix run .# -- &lt;args&gt;</code>, which will build the Nix derivation and execute the resultant <code>treefmt</code> binary.</p>"},{"location":"contributing/code/#formatting","title":"Formatting","text":"<p>We use the latest released version of treefmt and treefmt-nix to format the repository by running <code>nix fmt</code> from the root directory.</p> nix/formatter.nix<pre><code>{\n  pkgs,\n  inputs,\n  ...\n}:\ninputs.treefmt-nix.lib.mkWrapper pkgs {\n  projectRootFile = \"flake.nix\";\n\n  programs = {\n    alejandra.enable = true;\n    deadnix.enable = true;\n    gofumpt.enable = true;\n    prettier.enable = true;\n    statix.enable = true;\n  };\n\n  settings = {\n    global.excludes = [\n      \"LICENSE\"\n      # let's not mess with the test folder\n      \"test/*\"\n      # unsupported extensions\n      \"*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore,pages}\"\n    ];\n\n    formatter = {\n      deadnix = {\n        priority = 1;\n      };\n\n      statix = {\n        priority = 2;\n      };\n\n      alejandra = {\n        priority = 3;\n      };\n\n      prettier = {\n        options = [\n          \"--tab-width\"\n          \"4\"\n        ];\n        includes = [\"*.{css,html,js,json,jsx,md,mdx,scss,ts,yaml}\"];\n      };\n    };\n  };\n}\n</code></pre>"},{"location":"contributing/code/#checks","title":"Checks","text":"<p>Running <code>nix flake check</code> will build all the devshells and Nix packages, as well as check the formatting with treefmt and any other Flake checks that have been configured.</p>"},{"location":"contributing/code/#documentation","title":"Documentation","text":"<p>When making changes, it is important to add or update any relevant sections in the documentation within the same pull request.</p> <p>For more information see the next section.</p>"},{"location":"contributing/docs/","title":"Documentation","text":"<p>There is a separate devshell called <code>docs</code> which is provided for working with the docs locally.</p> <p>It can be entered by running: <code>nix develop .#docs</code></p> nix/devshells/docs.nix<pre><code>\n</code></pre> <p>The docs are based on MkDocs and the MkDocs Material theme. You will find its configuration and content in the following locations:</p> <ul> <li><code>mkdocs.yaml</code></li> <li><code>./docs</code></li> </ul>"},{"location":"contributing/docs/#serve-locally","title":"Serve locally","text":"<p>To serve the docs locally run <code>mkdocs serve</code> from the root of the repository:</p> <pre><code>\u276f mkdocs serve\nINFO    -  Building documentation...\nINFO    -  Cleaning site directory\nWARNING -  The following pages exist in the docs directory, but are not included in the \"nav\" configuration:\n             - index.md\nINFO    -  Documentation built in 0.26 seconds\nINFO    -  [16:22:36] Watching paths for changes: 'docs/content', 'mkdocs.yml'\nINFO    -  [16:22:36] Serving on http://127.0.0.1:8000/treefmt/\n</code></pre>"},{"location":"contributing/docs/#versioning-publication","title":"Versioning &amp; Publication","text":"<p>Versioning of the docs is managed through mike.</p> <p>It is responsible for managing the structure of the <code>gh-pages</code> branch in the repository, which Github Pages is configured to serve from.</p> <p>Note</p> <p>More information about versioning with MkDocs Material and mike can be found here.</p> <p>There is a github workflow, <code>.github/workflows/gh-pages.yml</code> which is responsible for publishing the docs. It does the following:</p> <ul> <li>On merge to <code>main</code>, the docs version main is updated.</li> <li>When a new tag is created of the form <code>v.&lt;major&gt;.&lt;minor&gt;.&lt;patch&gt;</code> a docs version <code>v&lt;major&gt;.&lt;minor&gt;</code> is created and the     latest alias is updated to point to this.</li> </ul> <p>The idea is that users will land on the latest released version of the docs by default, with <code>main</code> being available if they wish to read about unreleased features and changes.</p> <p>To preview the versions locally you can use <code>mike serve</code> instead of <code>mkdocs serve</code>.</p> <p>Warning</p> <p>Be sure to have fetched the latest changes for the <code>gh-pages</code> branch first. This is especially important if you are using <code>mike</code> locally to make manual changes to the published site.</p>"},{"location":"getting-started/configure/","title":"Configure","text":"<p><code>treefmt</code>'s behaviour can be influenced in one of three ways:</p> <ol> <li>Process flags and arguments</li> <li>Environment variables</li> <li>A TOML based config file</li> </ol> <p>There is an order of precedence between these mechanisms as listed above, with process flags having the highest precedence and values in the configuration file having the lowest.</p> <p>Note</p> <p>Some options can only be configured as process flags, others may support process flags and environment variables, and others still may support all three mechanisms.</p>"},{"location":"getting-started/configure/#config-file","title":"Config File","text":"<p>The <code>treefmt</code> configuration file is a mixture of global options and formatter sections.</p> <p>It should be named <code>treefmt.toml</code> or <code>.treefmt.toml</code>, and typically resides at the root of a repository.</p> <p>When executing <code>treefmt</code> within a subdirectory, <code>treefmt</code> will search upwards in the directory structure, looking for <code>treefmt.toml</code> or <code>.treefmt.toml</code>. You can change this behaviour using the config-file options</p> <p>Tip</p> <p>When starting a new project you can generate an initial config file using <code>treefmt --init</code></p> treefmt.toml<pre><code># One CLI to format the code tree - https://github.com/numtide/treefmt\n\n# Do not exit with error if a configured formatter is missing\n# Env $TREEFMT_ALLOW_MISSING_FORMATTER\n# allow-missing-formatter = true\n\n# The file into which a cpu profile will be written\n# Env $TREEFMT_CPU_PROFILE\n# cpu-profile = ./cpu.pprof\n\n# Exclude files or directories matching the specified globs\n# Env $TREEFMT_EXCLUDES\n# excludes = [\"*.md\", \"*.gif\"]\n\n# Exit with error if any changes were made during execution\n# Useful for CI\n# Env $TREEFMT_FAIL_ON_CHANGE\n# fail-on-change = true\n\n# A list of formatters to apply\n# Defaults to all configured formatters\n# Env $TREEFMT_FORMATTERS\n# formatters = [\"gofmt\", \"prettier\"]\n\n# Log paths that did not match any formatters at the specified log level\n# Possible values are &lt;debug|info|warn|error|fatal&gt;\n# Env $TREEFMT_ON_UNMATCHED\n# on-unmatched = \"info\"\n\n# The root directory from which treefmt will start walking the filesystem\n# Defaults to the directory containing the config file\n# Env $TREEFMT_TREE_ROOT\n# tree-root = \"/tmp/foo\"\n\n# File to search for to find the tree root (if tree-root is not set)\n# Env $TREEFMT_TREE_ROOT_FILE\n# tree-root-file = \".git/config\"\n\n# Set the verbosity of logs\n# 0 = warn, 1 = info, 2 = debug\n# Env $TREEFMT_VERBOSE\n# verbose = 2\n\n# The method used to traverse the files within the tree root\n# Currently, we support 'auto', 'git' or 'filesystem'\n# Env $TREEFMT_WALK\n# walk = \"filesystem\"\n\n[formatter.mylanguage]\n# Command to execute\ncommand = \"command-to-run\"\n# Command-line arguments for the command\noptions = []\n# Glob pattern of files to include\nincludes = [ \"*.&lt;language-extension&gt;\" ]\n# Glob patterns of files to exclude\nexcludes = []\n# Controls the order of application when multiple formatters match the same file\n# Lower the number, the higher the precedence\n# Default is 0\npriority = 0\n</code></pre>"},{"location":"getting-started/configure/#global-options","title":"Global Options","text":""},{"location":"getting-started/configure/#allow-missing-formatter","title":"<code>allow-missing-formatter</code>","text":"<p>Do not exit with error if a configured formatter is missing.</p> FlagEnvConfig <pre><code>treefmt --allow-missing-formatter true\n</code></pre> <pre><code>TREEFMT_ALLOW_MISSING_FORMATTER=true treefmt\n</code></pre> <pre><code>allow-missing-formatter = true\n</code></pre>"},{"location":"getting-started/configure/#ci","title":"<code>ci</code>","text":"<p>Runs treefmt in a CI mode, enabling no-cache, fail-on-change and adjusting some other settings best suited to a continuous integration environment.</p> FlagEnv <pre><code>treefmt --ci\n</code></pre> <pre><code>TREEFMT_CI=true treefmt\n</code></pre>"},{"location":"getting-started/configure/#clear-cache","title":"<code>clear-cache</code>","text":"<p>Reset the evaluation cache. Use in case the cache is not precise enough.</p> FlagEnv <pre><code>treefmt -c\ntreefmt --clear-cache\n</code></pre> <pre><code>TREEFMT_CLEAR_CACHE=true treefmt\n</code></pre>"},{"location":"getting-started/configure/#config-file_1","title":"<code>config-file</code>","text":"FlagEnv <pre><code>treefmt --config-file /tmp/treefmt.toml\n</code></pre> <pre><code>TREEFMT_CONFIG=/tmp/treefmt.toml treefmt\n</code></pre>"},{"location":"getting-started/configure/#cpu-profile","title":"<code>cpu-profile</code>","text":"<p>The file into which a pprof cpu profile will be written.</p> FlagEnvConfig <pre><code>treefmt --cpu-profile ./cpu.pprof\n</code></pre> <pre><code>TREEFMT_CPU_PROFILE=./cpu.pprof treefmt\n</code></pre> <pre><code>cpu-profile = \"./cpu.pprof\"\n</code></pre>"},{"location":"getting-started/configure/#excludes","title":"<code>excludes</code>","text":"<p>An optional list of glob patterns used to exclude files from all formatters.</p> FlagEnvConfig <pre><code>treefmt --excludes *.toml,*.php,README\n</code></pre> <pre><code>TREEFMT_EXCLUDES=\"*.toml,*.php,README\" treefmt\n</code></pre> <pre><code>excludes = [\"*.toml\", \"*.php\", \"README\"]\n</code></pre>"},{"location":"getting-started/configure/#fail-on-change","title":"<code>fail-on-change</code>","text":"<p>Exit with error if any changes were made during execution.</p> FlagEnvConfig <pre><code>treefmt --fail-on-change true\n</code></pre> <pre><code>TREEFMT_FAIL_ON_CHANGE=true treefmt\n</code></pre> <pre><code>fail-on-change = true\n</code></pre>"},{"location":"getting-started/configure/#formatters","title":"<code>formatters</code>","text":"<p>A list of formatters to apply. Defaults to all configured formatters.</p> FlagEnvConfig <pre><code>treefmt -f go,toml,haskell\ntreefmt --formatters go,toml,haskell\n</code></pre> <pre><code>TREEFMT_FORMATTERS=go,toml,haskell treefmt\n</code></pre> <pre><code>formatters = [\"go\", \"toml\", \"haskell\"]\n\n[formatter.go]\n...\n\n[formatter.toml]\n...\n\n[formatter.haskell]\n...\n\n[formatter.ruby]\n...\n\n[formatter.shellcheck]\n...\n</code></pre>"},{"location":"getting-started/configure/#no-cache","title":"<code>no-cache</code>","text":"<p>Ignore the evaluation cache entirely. Useful for CI.</p> FlagEnv <pre><code>treefmt --no-cache\n</code></pre> <pre><code>TREEFMT_NO_CACHE=true treefmt\n</code></pre>"},{"location":"getting-started/configure/#on-unmatched","title":"<code>on-unmatched</code>","text":"<p>Log paths that did not match any formatters at the specified log level. Possible values are <code>&lt;debug|info|warn|error|fatal&gt;</code>.</p> <p>Warning</p> <p>If you select <code>fatal</code>, the process will exit immediately with a non-zero exit.</p> FlagEnvConfig <pre><code>treefmt -u debug\ntreefmt --on-unmatched debug\n</code></pre> <pre><code>TREEFMT_ON_UNMACTHED=info treefmt\n</code></pre> <pre><code>on-unmatched = \"debug\"\n</code></pre>"},{"location":"getting-started/configure/#stdin","title":"<code>stdin</code>","text":"<p>Format the context passed in via stdin.</p> <p>Note</p> <p>You must provide a single path argument, the value of which is used to match against the configured formatters.</p> Flag <pre><code>cat ../test.go | treefmt --stdin foo.go\n</code></pre>"},{"location":"getting-started/configure/#tree-root","title":"<code>tree-root</code>","text":"<p>The root directory from which treefmt will start walking the filesystem. Defaults to the directory containing the config file.</p> FlagEnvConfig <pre><code>treefmt --tree-root /tmp/foo\n</code></pre> <pre><code>TREEFMT_TREE_ROOT=/tmp/foo treefmt\n</code></pre> <pre><code>tree-root = \"/tmp/foo\"\n</code></pre>"},{"location":"getting-started/configure/#tree-root-file","title":"<code>tree-root-file</code>","text":"<p>File to search for to find the tree root (if <code>tree-root</code> is not set)</p> FlagEnvConfig <pre><code>treefmt --tree-root-file .git/config\n</code></pre> <pre><code>TREEFMT_TREE_ROOT_FILE=.git/config treefmt\n</code></pre> <pre><code>tree-root-file = \".git/config\"\n</code></pre>"},{"location":"getting-started/configure/#verbose","title":"<code>verbose</code>","text":"<p>Set the verbosity level of logs:</p> <ul> <li><code>0</code> =&gt; <code>warn</code></li> <li><code>1</code> =&gt; <code>info</code></li> <li><code>2</code> =&gt; <code>debug</code></li> </ul> FlagEnvConfig <p>The number of <code>v</code>'s passed matches the level set.</p> <pre><code>treefmt -vv\n</code></pre> <pre><code>TREEFMT_VERBOSE=1 treefmt\n</code></pre> <pre><code>verbose = 2\n</code></pre>"},{"location":"getting-started/configure/#walk","title":"<code>walk</code>","text":"<p>The method used to traverse the files within the tree root. Currently, we support 'auto', 'git' or 'filesystem'</p> FlagEnvConfig <pre><code>treefmt --walk filesystem\n</code></pre> <pre><code>TREEFMT_WALK=filesystem treefmt\n</code></pre> <pre><code>walk = \"filesystem\"\n</code></pre>"},{"location":"getting-started/configure/#working-dir","title":"<code>working-dir</code>","text":"<p>Run as if <code>treefmt</code> was started in the specified working directory instead of the current working directory.</p> FlagEnv <pre><code>treefmt -C /tmp/foo\ntreefmt --working-dir /tmp/foo\n</code></pre> <pre><code>TREEFMT_WORKING_DIR=/tmp/foo treefmt\n</code></pre>"},{"location":"getting-started/configure/#formatter-options","title":"Formatter Options","text":"<p>Formatters are configured using a table entry in <code>treefmt.toml</code> of the form <code>[formatter.&lt;name&gt;]</code>:</p> <pre><code>[formatter.alejandra]\ncommand = \"alejandra\"\nincludes = [\"*.nix\"]\nexcludes = [\"examples/nix/sources.nix\"]\npriority = 1\n\n[formatter.deadnix]\ncommand = \"deadnix\"\noptions = [\"-e\"]\nincludes = [\"*.nix\"]\npriority = 2\n</code></pre>"},{"location":"getting-started/configure/#command","title":"<code>command</code>","text":"<p>The command to invoke when applying the formatter.</p>"},{"location":"getting-started/configure/#options","title":"<code>options</code>","text":"<p>An optional list of args to be passed to <code>command</code>.</p>"},{"location":"getting-started/configure/#includes","title":"<code>includes</code>","text":"<p>A list of glob patterns used to determine whether the formatter should be applied against a given path.</p>"},{"location":"getting-started/configure/#excludes_1","title":"<code>excludes</code>","text":"<p>An optional list of glob patterns used to exclude certain files from this formatter.</p>"},{"location":"getting-started/configure/#priority","title":"<code>priority</code>","text":"<p>Influences the order of execution. Greater precedence is given to lower numbers, with the default being <code>0</code>.</p>"},{"location":"getting-started/configure/#same-file-multiple-formatters","title":"Same file, multiple formatters?","text":"<p>For each file, <code>treefmt</code> determines a list of formatters based on the configured <code>includes</code> / <code>excludes</code> rules. This list is then sorted, first by priority (lower the value, higher the precedence) and secondly by formatter name (lexicographically).</p> <p>The resultant sequence of formatters is used to create a batch key, and similarly matched files get added to that batch until it is full, at which point the files are passed to each formatter in turn.</p> <p>This means that <code>treefmt</code> guarantees only one formatter will be operating on a given file at any point in time. Another consequence is that formatting is deterministic for a given file and a given <code>treefmt</code> configuration.</p> <p>By setting the priority fields appropriately, you can control the order in which those formatters are applied for any files they both happen to match on.</p>"},{"location":"getting-started/configure/#glob-patterns-format","title":"Glob patterns format","text":"<p>This is a variant of the Unix glob pattern. It supports all the usual selectors such as <code>*</code> and <code>?</code>.</p>"},{"location":"getting-started/configure/#examples","title":"Examples","text":"<ul> <li><code>*.go</code> - match all files in the project that end with a \".go\" file extension.</li> <li><code>vendor/*</code> - match all files under the vendor folder, recursively.</li> </ul>"},{"location":"getting-started/configure/#supported-formatters","title":"Supported Formatters","text":"<p>Any formatter that follows the spec is supported out of the box.</p> <p>Already 60+ formatters are supported.</p> <p>To find examples, take a look at https://github.com/numtide/treefmt-nix/tree/main/examples.</p> <p>If you are a Nix user, you might also like https://github.com/numtide/treefmt-nix, which uses Nix to pull in the right formatter package and seamlessly integrates both together.</p>"},{"location":"getting-started/install/","title":"Install","text":"<p>There are two ways to install <code>treefmt</code>:</p> <ol> <li>Download the latest binary</li> <li>Compile and build from source.</li> </ol>"},{"location":"getting-started/install/#download-a-binary-file","title":"Download a binary file","text":"<p>You can download the latest <code>treefmt</code> binaries here.</p>"},{"location":"getting-started/install/#build-from-source","title":"Build from source","text":"<p>There are several ways to build <code>treefmt</code> from source. Your choice will depend on whether you're a nix user or not.</p>"},{"location":"getting-started/install/#non-nix-user","title":"Non-Nix User","text":"<p>To try the project without building it, run the following from the project root folder:</p> <pre><code>$ go run main.go --help\n</code></pre> <p>This command will output the manual. You can run the tool in this manner with any other flag or option to format your project.</p> <p>To build a binary, you need to have <code>go 1.22</code> installed. You can find instructions on how to install a <code>go</code> compiler here.</p> <p>To build the project, run the following:</p> <pre><code>$ go build\n</code></pre> <p>After the build command exits successfully, you will find the <code>treefmt</code> binary in the project root folder.</p>"},{"location":"getting-started/install/#nix-user","title":"Nix User","text":"<p>If you're using both <code>treefmt</code> and <code>nix</code>, you can make use of <code>treefmt-nix</code>, a wrapper that makes installing and configuring <code>treefmt</code> with <code>nix</code> easier.</p> <p>Non-flake user</p> <p>Here you also have two options: you can install <code>treefmt</code> with plain <code>nix-build</code>, or with <code>nix-shell</code>.</p> <p>To build the package with <code>nix-build</code>, run the following:</p> <pre><code>$ nix-build -A packages.x86_64-linux.treefmt\n</code></pre> <p>note: substitute <code>x86_64-linux</code> for the target system you with to build for</p> <p>Nix-flake user</p> <p>If you want to use this repository with flakes, first ensure you have flakes enabled. You can then execute the following command in the project root folder:</p> <pre><code>$ nix run . -- --help\n</code></pre> <p>To build the project, run the following command in the project root folder:</p> <pre><code>$ nix build\n</code></pre> <p>The <code>treefmt</code> binary will be available in the <code>result</code> folder.</p>"},{"location":"getting-started/usage/","title":"Usage","text":"<p><code>treefmt</code> has the following specification:</p> <pre><code>Usage:\n  treefmt &lt;paths...&gt; [flags]\n\nFlags:\n      --allow-missing-formatter   Do not exit with error if a configured formatter is missing. (env $TREEFMT_ALLOW_MISSING_FORMATTER)\n      --ci                        Runs treefmt in a CI mode, enabling --no-cache, --fail-on-change and adjusting some other settings best suited to a CI use case. (env $TREEFMT_CI)\n  -c, --clear-cache               Reset the evaluation cache. Use in case the cache is not precise enough. (env $TREEFMT_CLEAR_CACHE)\n      --config-file string        Load the config file from the given path (defaults to searching upwards for treefmt.toml or .treefmt.toml).\n      --cpu-profile string        The file into which a cpu profile will be written. (env $TREEFMT_CPU_PROFILE)\n      --excludes strings          Exclude files or directories matching the specified globs. (env $TREEFMT_EXCLUDES)\n      --fail-on-change            Exit with error if any changes were made. Useful for CI. (env $TREEFMT_FAIL_ON_CHANGE)\n  -f, --formatters strings        Specify formatters to apply. Defaults to all configured formatters. (env $TREEFMT_FORMATTERS)\n  -h, --help                      help for treefmt\n  -i, --init                      Create a treefmt.toml file in the current directory.\n      --no-cache                  Ignore the evaluation cache entirely. Useful for CI. (env $TREEFMT_NO_CACHE)\n  -u, --on-unmatched string       Log paths that did not match any formatters at the specified log level. Possible values are &lt;debug|info|warn|error|fatal&gt;. (env $TREEFMT_ON_UNMATCHED) (default \"warn\")\n      --stdin                     Format the context passed in via stdin.\n      --tree-root string          The root directory from which treefmt will start walking the filesystem (defaults to the directory containing the config file). (env $TREEFMT_TREE_ROOT)\n      --tree-root-file string     File to search for to find the tree root (if --tree-root is not passed). (env $TREEFMT_TREE_ROOT_FILE)\n  -v, --verbose count             Set the verbosity of logs e.g. -vv. (env $TREEFMT_VERBOSE)\n      --version                   version for treefmt\n      --walk string               The method used to traverse the files within the tree root. Currently supports &lt;auto|git|filesystem&gt;. (env $TREEFMT_WALK) (default \"auto\")\n  -C, --working-dir string        Run as if treefmt was started in the specified working directory instead of the current working directory. (env $TREEFMT_WORKING_DIR) (default \".\")\n</code></pre> <p>Typically, you will execute <code>treefmt</code> from the root of your repository with no arguments:</p> <pre><code>\u276f treefmt\ntraversed 106 files\nemitted 9 files for processing\nformatted 6 files (2 changed) in 184ms\n</code></pre>"},{"location":"getting-started/usage/#clear-cache","title":"Clear Cache","text":"<p>To force re-evaluation of the entire tree, you run <code>treefmt</code> with the <code>-c</code> or <code>--clear-cache</code> flag:</p> <pre><code>\u276f treefmt -c\ntraversed 106 files\nemitted 106 files for processing\nformatted 56 files (0 changed) in 363ms\n\n\u276f treefmt --clear-cache\ntraversed 106 files\nemitted 106 files for processing\nformatted 56 files (0 changed) in 351ms\n</code></pre>"},{"location":"getting-started/usage/#change-working-directory","title":"Change working directory","text":"<p>Similar to git, <code>treefmt</code> has an option to change working directory before executing:</p> <pre><code>\u276f treefmt -C test/examples --allow-missing-formatter\ntraversed 106 files\nemitted 56 files for processing\nformatted 46 files (1 changed) in 406ms\n</code></pre>"},{"location":"getting-started/usage/#format-files-directories","title":"Format files &amp; directories","text":"<p>To format one or more specific files, you can pass them as arguments.</p> <pre><code>&gt; treefmt default.nix walk/walk.go nix/devshells/renovate.nix\ntraversed 3 files\nemitted 3 files for processing\nformatted 3 files (0 changed) in 144ms\n</code></pre> <p>You can also pass directories:</p> <pre><code>&gt; treefmt nix walk/cache\ntraversed 9 files\nemitted 8 files for processing\nformatted 7 files (0 changed) in 217ms\n</code></pre> <p>Note</p> <p>When passing directories as arguments, <code>treefmt</code> will traverse them using the configured walk strategy.</p>"},{"location":"getting-started/usage/#format-stdin","title":"Format stdin","text":"<p>Using the stdin option, <code>treefmt</code> can format content passed via <code>stdin</code>, forwarding its output to <code>stdout</code>:</p> <pre><code>\u276f cat default.nix | treefmt --stdin foo.nix\n# This file provides backward compatibility to nix &lt; 2.4 clients\n{system ? builtins.currentSystem}: let\n  lock = builtins.fromJSON (builtins.readFile ./flake.lock);\n\n  inherit\n    (lock.nodes.flake-compat.locked)\n    owner\n    repo\n    rev\n    narHash\n    ;\n\n  flake-compat = fetchTarball {\n    url = \"https://github.com/${owner}/${repo}/archive/${rev}.tar.gz\";\n    sha256 = narHash;\n  };\n\n  flake = import flake-compat {\n    inherit system;\n    src = ./.;\n  };\nin\n  flake.defaultNix\n</code></pre>"},{"location":"getting-started/usage/#ci-integration","title":"CI integration","text":"<p>We recommend using the CI option in continuous integration environments.</p> <p>You can configure a <code>treefmt</code> job in a GitHub pipeline for Ubuntu with <code>nix-shell</code> like this:</p> <pre><code>name: treefmt\non:\n    pull_request:\n    push:\n        branches: main\njobs:\n    formatter:\n        runs-on: ubuntu-latest\n        steps:\n            - uses: actions/checkout@v4\n            - uses: cachix/install-nix-action@v26\n              with:\n                  nix_path: nixpkgs=channel:nixos-unstable\n            - uses: cachix/cachix-action@v14\n              with:\n                  name: nix-community\n                  authToken: \"${{ secrets.CACHIX_AUTH_TOKEN }}\"\n            - name: treefmt\n              run: nix-shell -p treefmt --run \"treefmt --ci\"\n</code></pre>"},{"location":"reference/formatter-spec/","title":"Formatter Specification","text":"<p>To keep the design of <code>treefmt</code> simple, we only support formatters that adhere to a certain standard. This document outlines that standard.</p> <p>In this design, we rely on <code>treefmt</code> to do the tree traversal, and only invoke the code formatter on the selected files.</p> <p>Note</p> <p>If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification.</p>"},{"location":"reference/formatter-spec/#rules","title":"Rules","text":"<p>In order for the formatter to comply with this spec, it MUST satisfy the following:</p>"},{"location":"reference/formatter-spec/#1-files-passed-as-arguments","title":"1. Files passed as arguments","text":"<p>The formatter's CLI must be of the form:</p> <pre><code>&lt;command&gt; [options] [...&lt;files&gt;]\n</code></pre> <p>Where:</p> <ul> <li><code>&lt;command&gt;</code> is the name of the formatting tool.</li> <li><code>[options]</code> is any number of flags and options that the formatter accepts.</li> <li><code>[...&lt;files&gt;]</code> is one or more files given to the formatter for processing.</li> </ul> <p>Example:</p> <pre><code>$ rustfmt --edition 2018 src/main.rs src/lib.rs\n</code></pre> <p>Note</p> <p>It MUST process the specified files. For example, it MUST NOT ignore files because they are not tracked by a VCS.</p> <p>It SHOULD processes only the specified files. Files that are not passed SHOULD never be formatted.</p>"},{"location":"reference/formatter-spec/#2-write-to-changed-files","title":"2. Write to changed files","text":"<p>Whenever there is a change to the code formatting, the code formatter MUST write those changes back to the original location.</p> <p>If there are no changes to the original file, the formatter MUST NOT write to the original location.</p>"},{"location":"reference/formatter-spec/#3-idempotent","title":"3. Idempotent","text":"<p>The code formatter SHOULD be indempotent. Meaning that it produces stable outputs.</p>"},{"location":"reference/formatter-spec/#4-reliable","title":"4. Reliable","text":"<p>We expect the formatter to be reliable and not break the semantics of the formatted files.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"contributing/code/","title":"Code","text":""},{"location":"contributing/code/#pre-requisites","title":"Pre-requisites","text":"<p>You will need to have the following installed:</p> <ul> <li>Nix</li> <li>Direnv</li> </ul> <p>Important</p> <p>We use a Flake-based workflow. You can certainly develop for <code>treefmt</code> without Flakes and leverage much of what is listed below, but it is left up to the reader to determine how to make that work.</p>"},{"location":"contributing/code/#go-development","title":"Go development","text":"<p>The default devshell provides all the necessary tooling and utilities for working on <code>treefmt</code>.</p> nix/devshells/default.nix<pre><code>{\n  pkgs,\n  perSystem,\n  ...\n}:\npkgs.mkShellNoCC {\n  env.GOROOT = \"${pkgs.go}/share/go\";\n\n  packages =\n    (with pkgs; [\n      go\n      goreleaser\n      golangci-lint\n      delve\n      pprof\n      graphviz\n      cobra-cli\n      enumer\n      perSystem.gomod2nix.default\n    ])\n    ++ # include formatters for development and testing\n    (import ../packages/treefmt/formatters.nix pkgs);\n}\n</code></pre> <p>Direnv should load this by default when entering the root of the repository.</p> <p>For the most part, you should be able to develop normally as you would any other Go program.</p> <p>Important</p> <p>When you have completed making any changes and have tested it as you would any other Go program, it is important to ensure it works when run as a Nix package.</p> <p>This can be done with <code>nix run .# -- &lt;args&gt;</code>, which will build the Nix derivation and execute the resultant <code>treefmt</code> binary.</p>"},{"location":"contributing/code/#formatting","title":"Formatting","text":"<p>We use the latest released version of treefmt and treefmt-nix to format the repository by running <code>nix fmt</code> from the root directory.</p> nix/formatter.nix<pre><code>{\n  pkgs,\n  inputs,\n  ...\n}:\ninputs.treefmt-nix.lib.mkWrapper pkgs {\n  projectRootFile = \"flake.nix\";\n\n  programs = {\n    alejandra.enable = true;\n    deadnix.enable = true;\n    gofumpt.enable = true;\n    prettier.enable = true;\n    statix.enable = true;\n  };\n\n  settings = {\n    global.excludes = [\n      \"LICENSE\"\n      # let's not mess with the test folder\n      \"test/*\"\n      # unsupported extensions\n      \"*.{gif,png,svg,tape,mts,lock,mod,sum,toml,env,envrc,gitignore,pages}\"\n    ];\n\n    formatter = {\n      deadnix = {\n        priority = 1;\n      };\n\n      statix = {\n        priority = 2;\n      };\n\n      alejandra = {\n        priority = 3;\n      };\n\n      prettier = {\n        options = [\n          \"--tab-width\"\n          \"4\"\n        ];\n        includes = [\"*.{css,html,js,json,jsx,md,mdx,scss,ts,yaml}\"];\n      };\n    };\n  };\n}\n</code></pre>"},{"location":"contributing/code/#checks","title":"Checks","text":"<p>Running <code>nix flake check</code> will build all the devshells and Nix packages, as well as check the formatting with treefmt and any other Flake checks that have been configured.</p>"},{"location":"contributing/code/#documentation","title":"Documentation","text":"<p>When making changes, it is important to add or update any relevant sections in the documentation within the same pull request.</p> <p>For more information see the next section.</p>"},{"location":"contributing/docs/","title":"Documentation","text":"<p>There is a separate devshell called <code>docs</code> which is provided for working with the docs locally.</p> <p>It can be entered by running: <code>nix develop .#docs</code></p> nix/devshells/docs.nix<pre><code>\n</code></pre> <p>The docs are based on MkDocs and the MkDocs Material theme. You will find its configuration and content in the following locations:</p> <ul> <li><code>mkdocs.yaml</code></li> <li><code>./docs</code></li> </ul>"},{"location":"contributing/docs/#serve-locally","title":"Serve locally","text":"<p>To serve the docs locally run <code>mkdocs serve</code> from the root of the repository:</p> <pre><code>\u276f mkdocs serve\nINFO    -  Building documentation...\nINFO    -  Cleaning site directory\nWARNING -  The following pages exist in the docs directory, but are not included in the \"nav\" configuration:\n             - index.md\nINFO    -  Documentation built in 0.26 seconds\nINFO    -  [16:22:36] Watching paths for changes: 'docs/content', 'mkdocs.yml'\nINFO    -  [16:22:36] Serving on http://127.0.0.1:8000/treefmt/\n</code></pre>"},{"location":"contributing/docs/#versioning-publication","title":"Versioning &amp; Publication","text":"<p>Versioning of the docs is managed through mike.</p> <p>It is responsible for managing the structure of the <code>gh-pages</code> branch in the repository, which Github Pages is configured to serve from.</p> <p>Note</p> <p>More information about versioning with MkDocs Material and mike can be found here.</p> <p>There is a github workflow, <code>.github/workflows/gh-pages.yml</code> which is responsible for publishing the docs. It does the following:</p> <ul> <li>On merge to <code>main</code>, the docs version main is updated.</li> <li>When a new tag is created of the form <code>v.&lt;major&gt;.&lt;minor&gt;.&lt;patch&gt;</code> a docs version <code>v&lt;major&gt;.&lt;minor&gt;</code> is created and the     latest alias is updated to point to this.</li> </ul> <p>The idea is that users will land on the latest released version of the docs by default, with <code>main</code> being available if they wish to read about unreleased features and changes.</p> <p>To preview the versions locally you can use <code>mike serve</code> instead of <code>mkdocs serve</code>.</p> <p>Warning</p> <p>Be sure to have fetched the latest changes for the <code>gh-pages</code> branch first. This is especially important if you are using <code>mike</code> locally to make manual changes to the published site.</p>"},{"location":"getting-started/configure/","title":"Configure","text":"<p><code>treefmt</code>'s behaviour can be influenced in one of three ways:</p> <ol> <li>Process flags and arguments</li> <li>Environment variables</li> <li>A TOML based config file</li> </ol> <p>There is an order of precedence between these mechanisms as listed above, with process flags having the highest precedence and values in the configuration file having the lowest.</p> <p>Note</p> <p>Some options can only be configured as process flags, others may support process flags and environment variables, and others still may support all three mechanisms.</p>"},{"location":"getting-started/configure/#config-file","title":"Config File","text":"<p>The <code>treefmt</code> configuration file is a mixture of global options and formatter sections.</p> <p>It should be named <code>treefmt.toml</code> or <code>.treefmt.toml</code>, and typically resides at the root of a repository.</p> <p>When executing <code>treefmt</code> within a subdirectory, <code>treefmt</code> will search upwards in the directory structure, looking for <code>treefmt.toml</code> or <code>.treefmt.toml</code>. You can change this behaviour using the config-file options</p> <p>Tip</p> <p>When starting a new project you can generate an initial config file using <code>treefmt --init</code></p> treefmt.toml<pre><code># One CLI to format the code tree - https://github.com/numtide/treefmt\n\n# Do not exit with error if a configured formatter is missing\n# Env $TREEFMT_ALLOW_MISSING_FORMATTER\n# allow-missing-formatter = true\n\n# The file into which a cpu profile will be written\n# Env $TREEFMT_CPU_PROFILE\n# cpu-profile = ./cpu.pprof\n\n# Exclude files or directories matching the specified globs\n# Env $TREEFMT_EXCLUDES\n# excludes = [\"*.md\", \"*.gif\"]\n\n# Exit with error if any changes were made during execution\n# Useful for CI\n# Env $TREEFMT_FAIL_ON_CHANGE\n# fail-on-change = true\n\n# A list of formatters to apply\n# Defaults to all configured formatters\n# Env $TREEFMT_FORMATTERS\n# formatters = [\"gofmt\", \"prettier\"]\n\n# Log paths that did not match any formatters at the specified log level\n# Possible values are &lt;debug|info|warn|error|fatal&gt;\n# Env $TREEFMT_ON_UNMATCHED\n# on-unmatched = \"info\"\n\n# The root directory from which treefmt will start walking the filesystem\n# Defaults to the directory containing the config file\n# Env $TREEFMT_TREE_ROOT\n# tree-root = \"/tmp/foo\"\n\n# File to search for to find the tree root (if tree-root is not set)\n# Env $TREEFMT_TREE_ROOT_FILE\n# tree-root-file = \".git/config\"\n\n# Set the verbosity of logs\n# 0 = warn, 1 = info, 2 = debug\n# Env $TREEFMT_VERBOSE\n# verbose = 2\n\n# The method used to traverse the files within the tree root\n# Currently, we support 'auto', 'git' or 'filesystem'\n# Env $TREEFMT_WALK\n# walk = \"filesystem\"\n\n[formatter.mylanguage]\n# Command to execute\ncommand = \"command-to-run\"\n# Command-line arguments for the command\noptions = []\n# Glob pattern of files to include\nincludes = [ \"*.&lt;language-extension&gt;\" ]\n# Glob patterns of files to exclude\nexcludes = []\n# Controls the order of application when multiple formatters match the same file\n# Lower the number, the higher the precedence\n# Default is 0\npriority = 0\n</code></pre>"},{"location":"getting-started/configure/#global-options","title":"Global Options","text":""},{"location":"getting-started/configure/#allow-missing-formatter","title":"<code>allow-missing-formatter</code>","text":"<p>Do not exit with error if a configured formatter is missing.</p> FlagEnvConfig <pre><code>treefmt --allow-missing-formatter true\n</code></pre> <pre><code>TREEFMT_ALLOW_MISSING_FORMATTER=true treefmt\n</code></pre> <pre><code>allow-missing-formatter = true\n</code></pre>"},{"location":"getting-started/configure/#ci","title":"<code>ci</code>","text":"<p>Runs treefmt in a CI mode, enabling no-cache, fail-on-change and adjusting some other settings best suited to a continuous integration environment.</p> FlagEnv <pre><code>treefmt --ci\n</code></pre> <pre><code>TREEFMT_CI=true treefmt\n</code></pre>"},{"location":"getting-started/configure/#clear-cache","title":"<code>clear-cache</code>","text":"<p>Reset the evaluation cache. Use in case the cache is not precise enough.</p> FlagEnv <pre><code>treefmt -c\ntreefmt --clear-cache\n</code></pre> <pre><code>TREEFMT_CLEAR_CACHE=true treefmt\n</code></pre>"},{"location":"getting-started/configure/#config-file_1","title":"<code>config-file</code>","text":"FlagEnv <pre><code>treefmt --config-file /tmp/treefmt.toml\n</code></pre> <pre><code>TREEFMT_CONFIG=/tmp/treefmt.toml treefmt\n</code></pre>"},{"location":"getting-started/configure/#cpu-profile","title":"<code>cpu-profile</code>","text":"<p>The file into which a pprof cpu profile will be written.</p> FlagEnvConfig <pre><code>treefmt --cpu-profile ./cpu.pprof\n</code></pre> <pre><code>TREEFMT_CPU_PROFILE=./cpu.pprof treefmt\n</code></pre> <pre><code>cpu-profile = \"./cpu.pprof\"\n</code></pre>"},{"location":"getting-started/configure/#excludes","title":"<code>excludes</code>","text":"<p>An optional list of glob patterns used to exclude files from all formatters.</p> FlagEnvConfig <pre><code>treefmt --excludes *.toml,*.php,README\n</code></pre> <pre><code>TREEFMT_EXCLUDES=\"*.toml,*.php,README\" treefmt\n</code></pre> <pre><code>excludes = [\"*.toml\", \"*.php\", \"README\"]\n</code></pre>"},{"location":"getting-started/configure/#fail-on-change","title":"<code>fail-on-change</code>","text":"<p>Exit with error if any changes were made during execution.</p> FlagEnvConfig <pre><code>treefmt --fail-on-change true\n</code></pre> <pre><code>TREEFMT_FAIL_ON_CHANGE=true treefmt\n</code></pre> <pre><code>fail-on-change = true\n</code></pre>"},{"location":"getting-started/configure/#formatters","title":"<code>formatters</code>","text":"<p>A list of formatters to apply. Defaults to all configured formatters.</p> FlagEnvConfig <pre><code>treefmt -f go,toml,haskell\ntreefmt --formatters go,toml,haskell\n</code></pre> <pre><code>TREEFMT_FORMATTERS=go,toml,haskell treefmt\n</code></pre> <pre><code>formatters = [\"go\", \"toml\", \"haskell\"]\n\n[formatter.go]\n...\n\n[formatter.toml]\n...\n\n[formatter.haskell]\n...\n\n[formatter.ruby]\n...\n\n[formatter.shellcheck]\n...\n</code></pre>"},{"location":"getting-started/configure/#no-cache","title":"<code>no-cache</code>","text":"<p>Ignore the evaluation cache entirely. Useful for CI.</p> FlagEnv <pre><code>treefmt --no-cache\n</code></pre> <pre><code>TREEFMT_NO_CACHE=true treefmt\n</code></pre>"},{"location":"getting-started/configure/#on-unmatched","title":"<code>on-unmatched</code>","text":"<p>Log paths that did not match any formatters at the specified log level. Possible values are <code>&lt;debug|info|warn|error|fatal&gt;</code>.</p> <p>Warning</p> <p>If you select <code>fatal</code>, the process will exit immediately with a non-zero exit.</p> FlagEnvConfig <pre><code>treefmt -u debug\ntreefmt --on-unmatched debug\n</code></pre> <pre><code>TREEFMT_ON_UNMACTHED=info treefmt\n</code></pre> <pre><code>on-unmatched = \"debug\"\n</code></pre>"},{"location":"getting-started/configure/#stdin","title":"<code>stdin</code>","text":"<p>Format the context passed in via stdin.</p> <p>Note</p> <p>You must provide a single path argument, the value of which is used to match against the configured formatters.</p> Flag <pre><code>cat ../test.go | treefmt --stdin foo.go\n</code></pre>"},{"location":"getting-started/configure/#tree-root","title":"<code>tree-root</code>","text":"<p>The root directory from which treefmt will start walking the filesystem. Defaults to the directory containing the config file.</p> FlagEnvConfig <pre><code>treefmt --tree-root /tmp/foo\n</code></pre> <pre><code>TREEFMT_TREE_ROOT=/tmp/foo treefmt\n</code></pre> <pre><code>tree-root = \"/tmp/foo\"\n</code></pre>"},{"location":"getting-started/configure/#tree-root-file","title":"<code>tree-root-file</code>","text":"<p>File to search for to find the tree root (if <code>tree-root</code> is not set)</p> FlagEnvConfig <pre><code>treefmt --tree-root-file .git/config\n</code></pre> <pre><code>TREEFMT_TREE_ROOT_FILE=.git/config treefmt\n</code></pre> <pre><code>tree-root-file = \".git/config\"\n</code></pre>"},{"location":"getting-started/configure/#verbose","title":"<code>verbose</code>","text":"<p>Set the verbosity level of logs:</p> <ul> <li><code>0</code> =&gt; <code>warn</code></li> <li><code>1</code> =&gt; <code>info</code></li> <li><code>2</code> =&gt; <code>debug</code></li> </ul> FlagEnvConfig <p>The number of <code>v</code>'s passed matches the level set.</p> <pre><code>treefmt -vv\n</code></pre> <pre><code>TREEFMT_VERBOSE=1 treefmt\n</code></pre> <pre><code>verbose = 2\n</code></pre>"},{"location":"getting-started/configure/#walk","title":"<code>walk</code>","text":"<p>The method used to traverse the files within the tree root. Currently, we support 'auto', 'git' or 'filesystem'</p> FlagEnvConfig <pre><code>treefmt --walk filesystem\n</code></pre> <pre><code>TREEFMT_WALK=filesystem treefmt\n</code></pre> <pre><code>walk = \"filesystem\"\n</code></pre>"},{"location":"getting-started/configure/#working-dir","title":"<code>working-dir</code>","text":"<p>Run as if <code>treefmt</code> was started in the specified working directory instead of the current working directory.</p> FlagEnv <pre><code>treefmt -C /tmp/foo\ntreefmt --working-dir /tmp/foo\n</code></pre> <pre><code>TREEFMT_WORKING_DIR=/tmp/foo treefmt\n</code></pre>"},{"location":"getting-started/configure/#formatter-options","title":"Formatter Options","text":"<p>Formatters are configured using a table entry in <code>treefmt.toml</code> of the form <code>[formatter.&lt;name&gt;]</code>:</p> <pre><code>[formatter.alejandra]\ncommand = \"alejandra\"\nincludes = [\"*.nix\"]\nexcludes = [\"examples/nix/sources.nix\"]\npriority = 1\n\n[formatter.deadnix]\ncommand = \"deadnix\"\noptions = [\"-e\"]\nincludes = [\"*.nix\"]\npriority = 2\n</code></pre>"},{"location":"getting-started/configure/#command","title":"<code>command</code>","text":"<p>The command to invoke when applying the formatter.</p>"},{"location":"getting-started/configure/#options","title":"<code>options</code>","text":"<p>An optional list of args to be passed to <code>command</code>.</p>"},{"location":"getting-started/configure/#includes","title":"<code>includes</code>","text":"<p>A list of glob patterns used to determine whether the formatter should be applied against a given path.</p>"},{"location":"getting-started/configure/#excludes_1","title":"<code>excludes</code>","text":"<p>An optional list of glob patterns used to exclude certain files from this formatter.</p>"},{"location":"getting-started/configure/#priority","title":"<code>priority</code>","text":"<p>Influences the order of execution. Greater precedence is given to lower numbers, with the default being <code>0</code>.</p>"},{"location":"getting-started/configure/#same-file-multiple-formatters","title":"Same file, multiple formatters?","text":"<p>For each file, <code>treefmt</code> determines a list of formatters based on the configured <code>includes</code> / <code>excludes</code> rules. This list is then sorted, first by priority (lower the value, higher the precedence) and secondly by formatter name (lexicographically).</p> <p>The resultant sequence of formatters is used to create a batch key, and similarly matched files get added to that batch until it is full, at which point the files are passed to each formatter in turn.</p> <p>This means that <code>treefmt</code> guarantees only one formatter will be operating on a given file at any point in time. Another consequence is that formatting is deterministic for a given file and a given <code>treefmt</code> configuration.</p> <p>By setting the priority fields appropriately, you can control the order in which those formatters are applied for any files they both happen to match on.</p>"},{"location":"getting-started/configure/#glob-patterns-format","title":"Glob patterns format","text":"<p>This is a variant of the Unix glob pattern. It supports all the usual selectors such as <code>*</code> and <code>?</code>.</p>"},{"location":"getting-started/configure/#examples","title":"Examples","text":"<ul> <li><code>*.go</code> - match all files in the project that end with a \".go\" file extension.</li> <li><code>vendor/*</code> - match all files under the vendor folder, recursively.</li> </ul>"},{"location":"getting-started/configure/#supported-formatters","title":"Supported Formatters","text":"<p>Any formatter that follows the spec is supported out of the box.</p> <p>Already 60+ formatters are supported.</p> <p>To find examples, take a look at https://github.com/numtide/treefmt-nix/tree/main/examples.</p> <p>If you are a Nix user, you might also like https://github.com/numtide/treefmt-nix, which uses Nix to pull in the right formatter package and seamlessly integrates both together.</p>"},{"location":"getting-started/install/","title":"Install","text":"<p>There are two ways to install <code>treefmt</code>:</p> <ol> <li>Download the latest binary</li> <li>Compile and build from source.</li> </ol>"},{"location":"getting-started/install/#download-a-binary-file","title":"Download a binary file","text":"<p>You can download the latest <code>treefmt</code> binaries here.</p>"},{"location":"getting-started/install/#build-from-source","title":"Build from source","text":"<p>There are several ways to build <code>treefmt</code> from source. Your choice will depend on whether you're a nix user or not.</p>"},{"location":"getting-started/install/#non-nix-user","title":"Non-Nix User","text":"<p>To try the project without building it, run the following from the project root folder:</p> <pre><code>$ go run main.go --help\n</code></pre> <p>This command will output the manual. You can run the tool in this manner with any other flag or option to format your project.</p> <p>To build a binary, you need to have <code>go 1.22</code> installed. You can find instructions on how to install a <code>go</code> compiler here.</p> <p>To build the project, run the following:</p> <pre><code>$ go build\n</code></pre> <p>After the build command exits successfully, you will find the <code>treefmt</code> binary in the project root folder.</p>"},{"location":"getting-started/install/#nix-user","title":"Nix User","text":"<p>If you're using both <code>treefmt</code> and <code>nix</code>, you can make use of <code>treefmt-nix</code>, a wrapper that makes installing and configuring <code>treefmt</code> with <code>nix</code> easier.</p> <p>Non-flake user</p> <p>Here you also have two options: you can install <code>treefmt</code> with plain <code>nix-build</code>, or with <code>nix-shell</code>.</p> <p>To build the package with <code>nix-build</code>, run the following:</p> <pre><code>$ nix-build -A packages.x86_64-linux.treefmt\n</code></pre> <p>note: substitute <code>x86_64-linux</code> for the target system you with to build for</p> <p>Nix-flake user</p> <p>If you want to use this repository with flakes, first ensure you have flakes enabled. You can then execute the following command in the project root folder:</p> <pre><code>$ nix run . -- --help\n</code></pre> <p>To build the project, run the following command in the project root folder:</p> <pre><code>$ nix build\n</code></pre> <p>The <code>treefmt</code> binary will be available in the <code>result</code> folder.</p>"},{"location":"getting-started/usage/","title":"Usage","text":"<p><code>treefmt</code> has the following specification:</p> <pre><code>Usage:\n  treefmt &lt;paths...&gt; [flags]\n\nFlags:\n      --allow-missing-formatter   Do not exit with error if a configured formatter is missing. (env $TREEFMT_ALLOW_MISSING_FORMATTER)\n      --ci                        Runs treefmt in a CI mode, enabling --no-cache, --fail-on-change and adjusting some other settings best suited to a CI use case. (env $TREEFMT_CI)\n  -c, --clear-cache               Reset the evaluation cache. Use in case the cache is not precise enough. (env $TREEFMT_CLEAR_CACHE)\n      --config-file string        Load the config file from the given path (defaults to searching upwards for treefmt.toml or .treefmt.toml).\n      --cpu-profile string        The file into which a cpu profile will be written. (env $TREEFMT_CPU_PROFILE)\n      --excludes strings          Exclude files or directories matching the specified globs. (env $TREEFMT_EXCLUDES)\n      --fail-on-change            Exit with error if any changes were made. Useful for CI. (env $TREEFMT_FAIL_ON_CHANGE)\n  -f, --formatters strings        Specify formatters to apply. Defaults to all configured formatters. (env $TREEFMT_FORMATTERS)\n  -h, --help                      help for treefmt\n  -i, --init                      Create a treefmt.toml file in the current directory.\n      --no-cache                  Ignore the evaluation cache entirely. Useful for CI. (env $TREEFMT_NO_CACHE)\n  -u, --on-unmatched string       Log paths that did not match any formatters at the specified log level. Possible values are &lt;debug|info|warn|error|fatal&gt;. (env $TREEFMT_ON_UNMATCHED) (default \"warn\")\n      --stdin                     Format the context passed in via stdin.\n      --tree-root string          The root directory from which treefmt will start walking the filesystem (defaults to the directory containing the config file). (env $TREEFMT_TREE_ROOT)\n      --tree-root-file string     File to search for to find the tree root (if --tree-root is not passed). (env $TREEFMT_TREE_ROOT_FILE)\n  -v, --verbose count             Set the verbosity of logs e.g. -vv. (env $TREEFMT_VERBOSE)\n      --version                   version for treefmt\n      --walk string               The method used to traverse the files within the tree root. Currently supports &lt;auto|git|filesystem&gt;. (env $TREEFMT_WALK) (default \"auto\")\n  -C, --working-dir string        Run as if treefmt was started in the specified working directory instead of the current working directory. (env $TREEFMT_WORKING_DIR) (default \".\")\n</code></pre> <p>Typically, you will execute <code>treefmt</code> from the root of your repository with no arguments:</p> <pre><code>\u276f treefmt\ntraversed 106 files\nemitted 9 files for processing\nformatted 6 files (2 changed) in 184ms\n</code></pre>"},{"location":"getting-started/usage/#clear-cache","title":"Clear Cache","text":"<p>To force re-evaluation of the entire tree, you run <code>treefmt</code> with the <code>-c</code> or <code>--clear-cache</code> flag:</p> <pre><code>\u276f treefmt -c\ntraversed 106 files\nemitted 106 files for processing\nformatted 56 files (0 changed) in 363ms\n\n\u276f treefmt --clear-cache\ntraversed 106 files\nemitted 106 files for processing\nformatted 56 files (0 changed) in 351ms\n</code></pre>"},{"location":"getting-started/usage/#change-working-directory","title":"Change working directory","text":"<p>Similar to git, <code>treefmt</code> has an option to change working directory before executing:</p> <pre><code>\u276f treefmt -C test/examples --allow-missing-formatter\ntraversed 106 files\nemitted 56 files for processing\nformatted 46 files (1 changed) in 406ms\n</code></pre>"},{"location":"getting-started/usage/#format-files-directories","title":"Format files &amp; directories","text":"<p>To format one or more specific files, you can pass them as arguments.</p> <pre><code>&gt; treefmt default.nix walk/walk.go nix/devshells/renovate.nix\ntraversed 3 files\nemitted 3 files for processing\nformatted 3 files (0 changed) in 144ms\n</code></pre> <p>You can also pass directories:</p> <pre><code>&gt; treefmt nix walk/cache\ntraversed 9 files\nemitted 8 files for processing\nformatted 7 files (0 changed) in 217ms\n</code></pre> <p>Note</p> <p>When passing directories as arguments, <code>treefmt</code> will traverse them using the configured walk strategy.</p>"},{"location":"getting-started/usage/#format-stdin","title":"Format stdin","text":"<p>Using the stdin option, <code>treefmt</code> can format content passed via <code>stdin</code>, forwarding its output to <code>stdout</code>:</p> <pre><code>\u276f cat default.nix | treefmt --stdin foo.nix\n# This file provides backward compatibility to nix &lt; 2.4 clients\n{system ? builtins.currentSystem}: let\n  lock = builtins.fromJSON (builtins.readFile ./flake.lock);\n\n  inherit\n    (lock.nodes.flake-compat.locked)\n    owner\n    repo\n    rev\n    narHash\n    ;\n\n  flake-compat = fetchTarball {\n    url = \"https://github.com/${owner}/${repo}/archive/${rev}.tar.gz\";\n    sha256 = narHash;\n  };\n\n  flake = import flake-compat {\n    inherit system;\n    src = ./.;\n  };\nin\n  flake.defaultNix\n</code></pre>"},{"location":"getting-started/usage/#ci-integration","title":"CI integration","text":"<p>We recommend using the CI option in continuous integration environments.</p> <p>You can configure a <code>treefmt</code> job in a GitHub pipeline for Ubuntu with <code>nix-shell</code> like this:</p> <pre><code>name: treefmt\non:\n    pull_request:\n    push:\n        branches: main\njobs:\n    formatter:\n        runs-on: ubuntu-latest\n        steps:\n            - uses: actions/checkout@v4\n            - uses: cachix/install-nix-action@v26\n              with:\n                  nix_path: nixpkgs=channel:nixos-unstable\n            - uses: cachix/cachix-action@v14\n              with:\n                  name: nix-community\n                  authToken: \"${{ secrets.CACHIX_AUTH_TOKEN }}\"\n            - name: treefmt\n              run: nix-shell -p treefmt --run \"treefmt --ci\"\n</code></pre>"},{"location":"guides/unmatched-formatters/","title":"Handling Unmatched Files","text":"<p>By default, treefmt lists all files that aren't matched by any formatter:</p> <pre><code>$ treefmt\nWARN no formatter for path: .gitignore\nWARN no formatter for path: LICENSE\nWARN no formatter for path: README.md\nWARN no formatter for path: go.mod\nWARN no formatter for path: go.sum\nWARN no formatter for path: build/build.go\n# ...\n</code></pre> <p>This helps you decide whether to add formatters for specific files or ignore them entirely.</p>"},{"location":"guides/unmatched-formatters/#customizing-notifications","title":"Customizing Notifications","text":""},{"location":"guides/unmatched-formatters/#reducing-log-verbosity","title":"Reducing Log Verbosity","text":"<p>If you find the unmatched file warnings too noisy, you can lower the logging level in your config:</p> <p><code>treefmt.toml</code>: <pre><code>on-unmatched = \"debug\"\n</code></pre></p> <p>To later find out what files are unmatched, you can override this setting via the command line: <pre><code>$ treefmt --on-unmatched warn\n</code></pre></p>"},{"location":"guides/unmatched-formatters/#enforcing-strict-matching","title":"Enforcing Strict Matching","text":"<p>Another stricter policy approach is to fail the run if any unmatched files are found. This can be paired with an <code>excludes</code> list to ignore specific files:</p> <p><code>treefmt.toml</code>: <pre><code># Fail if any unmatched files are found\non-unmatched = \"fatal\"\n\n# List files to explicitly ignore\nexcludes = [\n  \"LICENCE\",\n  \"go.sum\",\n]\n</code></pre></p>"},{"location":"reference/formatter-spec/","title":"Formatter Specification","text":"<p>To keep the design of <code>treefmt</code> simple, we only support formatters that adhere to a certain standard. This document outlines that standard.</p> <p>In this design, we rely on <code>treefmt</code> to do the tree traversal, and only invoke the code formatter on the selected files.</p> <p>Note</p> <p>If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification.</p>"},{"location":"reference/formatter-spec/#rules","title":"Rules","text":"<p>In order for the formatter to comply with this spec, it MUST satisfy the following:</p>"},{"location":"reference/formatter-spec/#1-files-passed-as-arguments","title":"1. Files passed as arguments","text":"<p>The formatter's CLI must be of the form:</p> <pre><code>&lt;command&gt; [options] [...&lt;files&gt;]\n</code></pre> <p>Where:</p> <ul> <li><code>&lt;command&gt;</code> is the name of the formatting tool.</li> <li><code>[options]</code> is any number of flags and options that the formatter accepts.</li> <li><code>[...&lt;files&gt;]</code> is one or more files given to the formatter for processing.</li> </ul> <p>Example:</p> <pre><code>$ rustfmt --edition 2018 src/main.rs src/lib.rs\n</code></pre> <p>Note</p> <p>It MUST process the specified files. For example, it MUST NOT ignore files because they are not tracked by a VCS.</p> <p>It SHOULD processes only the specified files. Files that are not passed SHOULD never be formatted.</p>"},{"location":"reference/formatter-spec/#2-write-to-changed-files","title":"2. Write to changed files","text":"<p>Whenever there is a change to the code formatting, the code formatter MUST write those changes back to the original location.</p> <p>If there are no changes to the original file, the formatter MUST NOT write to the original location.</p>"},{"location":"reference/formatter-spec/#3-idempotent","title":"3. Idempotent","text":"<p>The code formatter SHOULD be indempotent. Meaning that it produces stable outputs.</p>"},{"location":"reference/formatter-spec/#4-reliable","title":"4. Reliable","text":"<p>We expect the formatter to be reliable and not break the semantics of the formatted files.</p>"}]}
\ No newline at end of file
diff --git a/main/sitemap.xml b/main/sitemap.xml
index dcd26000..438ef293 100644
--- a/main/sitemap.xml
+++ b/main/sitemap.xml
@@ -24,6 +24,10 @@
          <loc>https://treefmt.com/main/getting-started/usage/</loc>
          <lastmod>1980-01-01</lastmod>
     </url>
+    <url>
+         <loc>https://treefmt.com/main/guides/unmatched-formatters/</loc>
+         <lastmod>1980-01-01</lastmod>
+    </url>
     <url>
          <loc>https://treefmt.com/main/reference/formatter-spec/</loc>
          <lastmod>1980-01-01</lastmod>
diff --git a/main/sitemap.xml.gz b/main/sitemap.xml.gz
index 568a9263..a6474e88 100644
Binary files a/main/sitemap.xml.gz and b/main/sitemap.xml.gz differ