Merge pull request 'port docs' (#31) from feat/docs into main

Reviewed-on: #31

.github/CONTRIBUTING.md

@@ -0,0 +1,5 @@
+By contributing to this project, you hereby acknowledge that you already read [Contributing](../docs/contributing.md)
+guideline, and you agree to the Developer Certificate of Origin (DCO). This document is a simple statement that you, as
+a contributor, have the legal right to submit the contribution.
+
+See the [Developer Certificate of Origin](https://developercertificate.org/) file for details.

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+    - package-ecosystem: "github-actions"
+      directory: "/"
+      schedule:
+          interval: "weekly"

.github/settings.yml

@@ -0,0 +1,137 @@
+repository:
+    # See https://developer.github.com/v3/repos/#edit for all available settings.
+
+    # The name of the repository. Changing this will rename the repository
+    name: treefmt.go
+
+    # A short description of the repository that will show up on GitHub
+    description: one CLI to format your repo
+
+    # A URL with more information about the repository
+    homepage: "https://numtide.github.io/treefmt.go/"
+
+    # A comma-separated list of topics to set on the repository
+    topics: "cli, formatter, unifies"
+
+    # Either `true` to make the repository private, or `false` to make it public.
+    private: false
+
+    # Either `true` to enable issues for this repository, `false` to disable them.
+    has_issues: true
+
+    # Either `true` to enable projects for this repository, or `false` to disable them.
+    # If projects are disabled for the organization, passing `true` will cause an API error.
+    has_projects: false
+
+    # Either `true` to enable the wiki for this repository, `false` to disable it.
+    has_wiki: true
+
+    # Either `true` to enable downloads for this repository, `false` to disable them.
+    has_downloads: false
+
+    # Updates the default branch for this repository.
+    default_branch: main
+
+    # Either `true` to allow squash-merging pull requests, or `false` to prevent
+    # squash-merging.
+    allow_squash_merge: true
+
+    # Either `true` to allow merging pull requests with a merge commit, or `false`
+    # to prevent merging pull requests with merge commits.
+    allow_merge_commit: true
+
+    # Either `true` to allow rebase-merging pull requests, or `false` to prevent
+    # rebase-merging.
+    allow_rebase_merge: true
+
+    # Either `true` to enable automatic deletion of branches on merge, or `false` to disable
+    delete_branch_on_merge: true
+
+    # Either `true` to enable automated security fixes, or `false` to disable
+    # automated security fixes.
+    enable_automated_security_fixes: true
+
+    # Either `true` to enable vulnerability alerts, or `false` to disable
+    # vulnerability alerts.
+    enable_vulnerability_alerts: true
+
+# Labels: define labels for Issues and Pull Requests
+#
+labels:
+# NOTE: leave that up to the https://github.com/numtide/.github repo
+#   - name: bug
+#     color: CC0000
+#     description: An issue with the system 🐛.
+
+#   - name: feature
+#     # If including a `#`, make sure to wrap it with quotes!
+#     color: '#336699'
+#     description: New functionality.
+
+#   - name: Help Wanted
+#     # Provide a new name to rename an existing label
+#     new_name: first-timers-only
+
+# Milestones: define milestones for Issues and Pull Requests
+milestones:
+#   - title: milestone-title
+#     description: milestone-description
+#     # The state of the milestone. Either `open` or `closed`
+#     state: open
+
+# Collaborators: give specific users access to this repository.
+# See https://docs.github.com/en/rest/reference/repos#add-a-repository-collaborator for available options
+collaborators:
+    - username: basile-henry
+      # Note: `permission` is only valid on organization-owned repositories.
+      # The permission to grant the collaborator. Can be one of:
+      # * `pull` - can pull, but not push to or administer this repository.
+      # * `push` - can pull and push, but not administer this repository.
+      # * `admin` - can pull, push and administer this repository.
+      # * `maintain` - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.
+      # * `triage` - Recommended for contributors who need to proactively manage issues and pull requests without write access.
+      permission: push
+
+# See https://docs.github.com/en/rest/reference/teams#add-or-update-team-repository-permissions for available options
+teams:
+    - name: network
+      # The permission to grant the team. Can be one of:
+      # * `pull` - can pull, but not push to or administer this repository.
+      # * `push` - can pull and push, but not administer this repository.
+      # * `admin` - can pull, push and administer this repository.
+      # * `maintain` - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.
+      # * `triage` - Recommended for contributors who need to proactively manage issues and pull requests without write access.
+      permission: maintain
+
+branches:
+    - name: main
+      # https://docs.github.com/en/rest/reference/repos#update-branch-protection
+      # Branch Protection settings. Set to null to disable
+      protection:
+          # Required. Require at least one approving review on a pull request, before merging. Set to null to disable.
+          required_pull_request_reviews:
+              # # The number of approvals required. (1-6)
+              # required_approving_review_count: 1
+              # # Dismiss approved reviews automatically when a new commit is pushed.
+              # dismiss_stale_reviews: true
+              # # Blocks merge until code owners have reviewed.
+              # require_code_owner_reviews: true
+              # # Specify which users and teams can dismiss pull request reviews. Pass an empty dismissal_restrictions object to disable. User and team dismissal_restrictions are only available for organization-owned repositories. Omit this parameter for personal repositories.
+              # dismissal_restrictions:
+              #   users: []
+              #   teams: []
+          # Required. Require status checks to pass before merging. Set to null to disable
+          required_status_checks:
+              # Required. Require branches to be up to date before merging.
+              strict: true
+              # Required. The list of status checks to require in order to merge into this branch
+              contexts: []
+          # Required. Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to null to disable.
+          enforce_admins: false
+          # Disabled for mergify to work
+          required_linear_history: false
+          # Required. Restrict who can push to this branch. Team and user restrictions are only available for organization-owned repositories. Set to null to disable.
+          restrictions:
+              apps: ["mergify"]
+              users: []
+              teams: []

.github/workflows/gh-pages.yml

@@ -0,0 +1,37 @@
+# Build and deploy MkDocs to gh-pages for main branch
+name: gh-pages
+on:
+    push:
+        branches:
+            - main
+            - staging
+            - trying
+    pull_request:
+    workflow_dispatch:
+
+permissions:
+    contents: write
+
+jobs:
+    gh-pages:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: cachix/install-nix-action@v25
+            - uses: cachix/cachix-action@v14
+              with:
+                  name: numtide
+                  authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
+
+            - name: Build the docs
+              id: build
+              run: |
+                  nix build .#docs
+                  echo "result=$(readlink ./result)" >> $GITHUB_OUTPUT
+
+            - name: Deploy
+              uses: peaceiris/actions-gh-pages@v3
+              if: github.ref == 'refs/heads/main'
+              with:
+                  github_token: ${{ secrets.GITHUB_TOKEN }}
+                  publish_dir: "${{ steps.build.outputs.result }}/"

.gitignore

@@ -10,3 +10,8 @@ repl-result-*
 
 # devshell
 /.data
+
+# docs
+node_modules
+docs/.vitepress/cache
+docs/.vitepress/dist

default.nix

@@ -0,0 +1,17 @@
+# This file provides backward compatibility to nix < 2.4 clients
+{system ? builtins.currentSystem}: let
+  lock = builtins.fromJSON (builtins.readFile ./flake.lock);
+
+  inherit (lock.nodes.flake-compat.locked) owner repo rev narHash;
+
+  flake-compat = fetchTarball {
+    url = "https://github.com/${owner}/${repo}/archive/${rev}.tar.gz";
+    sha256 = narHash;
+  };
+
+  flake = import flake-compat {
+    inherit system;
+    src = ./.;
+  };
+in
+  flake.defaultNix

docs/.vitepress/config.mts

@@ -0,0 +1,41 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Treefmt",
+  description: "one CLI to format your repo",
+
+  head: [
+    ['link', { rel: 'icon', href: '/logo.png' }],
+  ],
+
+  themeConfig: {
+
+    logo: '/logo.svg',
+
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Quick Start', link: '/quick-start' }
+    ],
+
+    sidebar: [
+      { text: 'Quick Start', link: '/quick-start' },
+      { text: 'Installation', link: '/installation' },
+      { text: 'Overview', link: '/overview' },
+      { text: 'Usage', link: '/usage' },
+      { text: 'Formatter Specification', link: '/formatter-spec' },
+      { text: 'Contributing', link: '/contributing' },
+      { text: 'FAQ', link: '/faq' },
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://https://github.com/numtide/treefmt.go' }
+    ],
+
+    footer: {
+      message: 'Released under the <a href="https://https://github.com/numtide/treefmt.go/src/branch/main/LICENSE.md">MIT License</a>.',
+      copyright: "Copyright © 2024-present Treefmt Contributors"
+    }
+  }
+})

docs/.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from "vue";
+import type { Theme } from "vitepress";
+import DefaultTheme from "vitepress/theme";
+import "./style.css";
+
+export default {
+    extends: DefaultTheme,
+    Layout: () => {
+        return h(DefaultTheme.Layout, null, {
+            // https://vitepress.dev/guide/extending-default-theme#layout-slots
+        });
+    },
+    enhanceApp({ app, router, siteData }) {
+        // ...
+    },
+} satisfies Theme;

docs/.vitepress/theme/style.css

@@ -0,0 +1,146 @@
+/**
+ * Customize default theme styling by overriding CSS variables:
+ * https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+/**
+ * Colors
+ *
+ * Each colors have exact same color scale system with 3 levels of solid
+ * colors with different brightness, and 1 soft color.
+ * 
+ * - `XXX-1`: The most solid color used mainly for colored text. It must
+ *   satisfy the contrast ratio against when used on top of `XXX-soft`.
+ *
+ * - `XXX-2`: The color used mainly for hover state of the button.
+ *
+ * - `XXX-3`: The color for solid background, such as bg color of the button.
+ *   It must satisfy the contrast ratio with pure white (#ffffff) text on
+ *   top of it.
+ *
+ * - `XXX-soft`: The color used for subtle background such as custom container
+ *   or badges. It must satisfy the contrast ratio when putting `XXX-1` colors
+ *   on top of it.
+ *
+ *   The soft color must be semi transparent alpha channel. This is crucial
+ *   because it allows adding multiple "soft" colors on top of each other
+ *   to create a accent, such as when having inline code block inside
+ *   custom containers.
+ *
+ * - `default`: The color used purely for subtle indication without any
+ *   special meanings attched to it such as bg color for menu hover state.
+ *
+ * - `brand`: Used for primary brand colors, such as link text, button with
+ *   brand theme, etc.
+ *
+ * - `tip`: Used to indicate useful information. The default theme uses the
+ *   brand color for this by default.
+ *
+ * - `warning`: Used to indicate warning to the users. Used in custom
+ *   container, badges, etc.
+ *
+ * - `danger`: Used to show error, or dangerous message to the users. Used
+ *   in custom container, badges, etc.
+ * -------------------------------------------------------------------------- */
+
+:root {
+    --vp-c-treefmt-orange-1: #f79433;
+    --vp-c-treefmt-orange-2: #f6861a;
+    --vp-c-treefmt-orange-3: #dd6d00;
+    --vp-c-treefmt-orange-soft: rgba(245, 121, 0, 0.14);
+
+    --vp-c-treefmt-green-1: #9de05c;
+    --vp-c-treefmt-green-2: #8fdb45;
+    --vp-c-treefmt-green-3: #73d216;
+    --vp-c-treefmt-green-soft: rgba(115, 210, 22, 0.14);
+
+    --vp-c-treefmt-gray-1: #6d6e6a;
+    --vp-c-treefmt-gray-2: #888a85;
+    --vp-c-treefmt-gray-3: #a0a19d;
+    --vp-c-treefmt-gray-soft: rgba(136, 138, 133, 0.14);
+
+    --vp-c-default-1: var(--vp-c-treefmt-gray-1);
+    --vp-c-default-2: var(--vp-c-treefmt-gray-2);
+    --vp-c-default-3: var(--vp-c-treefmt-gray-3);
+    --vp-c-default-soft: var(--vp-c-treefmt-gray-soft);
+
+    --vp-c-brand-1: var(--vp-c-treefmt-orange-1);
+    --vp-c-brand-2: var(--vp-c-treefmt-orange-2);
+    --vp-c-brand-3: var(--vp-c-treefmt-orange-3);
+    --vp-c-brand-soft: var(--vp-c-treefmt-orange-soft);
+
+    --vp-c-tip-1: var(--vp-c-brand-1);
+    --vp-c-tip-2: var(--vp-c-brand-2);
+    --vp-c-tip-3: var(--vp-c-brand-3);
+    --vp-c-tip-soft: var(--vp-c-brand-soft);
+
+    --vp-c-warning-1: var(--vp-c-yellow-1);
+    --vp-c-warning-2: var(--vp-c-yellow-2);
+    --vp-c-warning-3: var(--vp-c-yellow-3);
+    --vp-c-warning-soft: var(--vp-c-yellow-soft);
+
+    --vp-c-danger-1: var(--vp-c-red-1);
+    --vp-c-danger-2: var(--vp-c-red-2);
+    --vp-c-danger-3: var(--vp-c-red-3);
+    --vp-c-danger-soft: var(--vp-c-red-soft);
+}
+
+/**
+ * Component: Button
+ * -------------------------------------------------------------------------- */
+
+:root {
+    --vp-button-brand-border: transparent;
+    --vp-button-brand-text: var(--vp-c-white);
+    --vp-button-brand-bg: var(--vp-c-brand-3);
+    --vp-button-brand-hover-border: transparent;
+    --vp-button-brand-hover-text: var(--vp-c-white);
+    --vp-button-brand-hover-bg: var(--vp-c-brand-2);
+    --vp-button-brand-active-border: transparent;
+    --vp-button-brand-active-text: var(--vp-c-white);
+    --vp-button-brand-active-bg: var(--vp-c-brand-1);
+}
+
+/**
+ * Component: Home
+ * -------------------------------------------------------------------------- */
+
+:root {
+    --vp-home-hero-image-background-image: linear-gradient(
+        -45deg,
+        var(--vp-c-treefmt-orange-3) 50%,
+        var(--vp-c-treefmt-green-1) 50%
+    );
+    --vp-home-hero-image-filter: blur(44px);
+}
+
+@media (min-width: 640px) {
+    :root {
+        --vp-home-hero-image-filter: blur(56px);
+    }
+}
+
+@media (min-width: 960px) {
+    :root {
+        --vp-home-hero-image-filter: blur(68px);
+    }
+}
+
+/**
+ * Component: Custom Block
+ * -------------------------------------------------------------------------- */
+
+:root {
+    --vp-custom-block-tip-border: transparent;
+    --vp-custom-block-tip-text: var(--vp-c-text-1);
+    --vp-custom-block-tip-bg: var(--vp-c-brand-soft);
+    --vp-custom-block-tip-code-bg: var(--vp-c-brand-soft);
+}
+
+/**
+ * Component: Algolia
+ * -------------------------------------------------------------------------- */
+
+.DocSearch {
+    --docsearch-primary-color: var(--vp-c-brand-1) !important;
+}

docs/contributing.md

@@ -0,0 +1,142 @@
+---
+outline: deep
+---
+
+# Contribution guidelines
+
+This file contains instructions that will help you make a contribution.
+
+## Licensing
+
+The `treefmt` binaries and this user guide are licensed under the [MIT license](https://numtide.github.io/treefmt/LICENSE.html).
+
+## Before you contribute
+
+Here you can take a look at the [existing issues](https://github.com/numtide/treefmt.go/issues). Feel free to contribute, but make sure you have a
+[GitHub account](https://github.com/join) first :slightly_smiling_face:.
+
+If you're new to open source, please read GitHub's guide on [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/). It's a quick read,
+and it's a great way to introduce yourself to how things work behind the scenes in open-source projects.
+
+Before sending a pull request, make sure that you've read all the guidelines. If you don't understand something, please
+[state your question clearly in an issue](https://github.com/numtide/treefmt.go/issues/new) or ask the community on the [treefmt matrix server](https://matrix.to/#/#treefmt:numtide.com).
+
+## Creating an issue
+
+If you need to create an issue, make sure to clearly describe it, including:
+
+-   The steps to reproduce it (if it's a bug)
+-   The version of `treefmt` used
+
+The cache database is stored in a `.db` file in the `~/.cache/treefmt/eval-cache` directory.
+
+## Making changes
+
+If you want to introduce changes to the project, please follow these steps:
+
+-   Fork the repository on GitHub
+-   Create a branch on your fork. Don't commit directly to main
+-   Add the necessary tests for your changes
+-   Run `treefmt` in the source directory before you commit your changes
+-   Push your changes to the branch in your repository fork
+-   Submit a pull request to the original repository
+
+Make sure you based your commits on logical and atomic units!
+
+## Examples of git history
+
+<details>
+
+<summary>Git history that we want to have</summary>
+
+```
+
+*   e3ed88b (HEAD -> contribution-guide, upstream/main, origin/main, origin/HEAD, main) Merge pull request #470 from zimbatm/fix_lru_cache
+
+|\
+
+| * 1ab7d9f Use rayon for multithreading command
+
+|/
+
+*   e9c5bb4 Merge pull request #468 from zimbatm/multithread
+
+|\
+
+| * de2d6cf Add lint property for Formatter struct
+
+| * cd2ed17 Fix impl on Formatter get_command() function
+
+|/
+
+*   028c344 Merge pull request #465 from rayon/0.15.0-release
+
+|\
+
+| * 7b619d6 0.15.0 release
+
+|/
+
+*   acdf7df Merge pull request #463 from zimbatm/support-multi-part-namespaces
+
+```
+
+</details>
+
+<details>
+
+<summary>Git history that we are <b>trying</b> to avoid</summary>
+
+```
+
+*   4c8aca8 Merge pull request #120 from zimbatm/add-rayon
+
+|\
+
+| * fc2b449 use rayon for engine now
+
+| * 2304683 add rayon config
+
+| * 5285bd3 bump base image to F30
+
+* |   4d0fbe2 Merge pull request #114 from rizary/create_method_create_release
+
+|\ \
+
+| * | 36a9396 test changed
+
+| * | 22f681d method create release for github created
+
+* | |   2ef4ea1 Merge pull request #119 from rizary/config.rs
+
+|\ \ \
+
+| |/ /
+
+|/| |
+
+| * | 5f1b8f0 unused functions removed
+
+* | |   a93c361 Merge pull request #117 from zimbatm/add-getreleases-to-abstract
+
+|\ \ \
+
+| |/ /
+
+|/| |
+
+| * | 0a97236 add get_releses for Cargo
+
+| * | 55e4c57 add get_releases/get_release into engine.rs
+
+|/ /
+
+* |   badeddd Merge pull request #101 from zimbatm/extreme-cachin
+
+```
+
+</details>
+
+Additionally, it's always good to work on improving documentation and adding examples.
+
+Thank you for considering contributing to `treefmt`.

docs/faq.md

@@ -0,0 +1,28 @@
+# FAQ
+
+## How does treefmt function?
+
+`Treefmt` traverses all your project's folders, maps files to specific code formatters, and formats the code
+accordingly. Other tools also traverse the filesystem, but not necessarily starting from the root of the project.
+
+Contrary to other formatters, `treefmt` doesn't preview the changes before writing them to a file. If you want to view
+the changes, you can always check the diff in your version control (we assume that your project is checked into a
+version control system).
+
+You can also rely on version control if errors were introduced into your code as a result of disruptions in the
+formatter's work.
+
+## How is the cache organized?
+
+At the moment, the cache is a [BoltDB] database file in which file paths are mapped to `mtimes`.
+
+The file is located in:
+
+```
+~/.cache/treefmt/eval-cache/<hash-of-the-treefmt.toml-path>.db
+```
+
+At the end of each run, the database is updated with the last formatting time entries. In this way, we can
+compare the last change time of the file to the last formatting time, and figure out which files need re-formatting.
+
+[BoltDB]: https://github.com/etcd-io/bbolt

docs/formatter-spec.md

@@ -0,0 +1,57 @@
+---
+outline: deep
+---
+
+# Formatter Specification
+
+In order to keep the design of `treefmt` simple, we only supports formatters that adhere to a certain standard. This
+document outlines that standard.
+
+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.
+
+In this design, we rely on `treefmt` to do the tree traversal, and only invoke
+the code formatter on the selected files.
+
+## Rules
+
+In order for the formatter to comply to this spec, it **MUST** comply with the following:
+
+### 1. Files passed as arguments
+
+In order to be integrated with `treefmt`'s workflow, the formatter's CLI must be of the form:
+
+```
+<command> [options] [...<files>]
+```
+
+Where:
+
+-   `<command>` is the name of the formatting tool.
+-   `[options]` is any number of flags and options that the formatter accepts.
+-   `[...<files>]` is one or more files given to the formatter for processing.
+
+Example:
+
+```
+$ rustfmt --edition 2018 src/main.rs src/lib.rs
+```
+
+> [!IMPORTANT]
+> It _SHOULD_ processes only the specified files. Files that are not passed _SHOULD_ never be formatted.
+
+### 2. Write to changed files
+
+Whenever there is a change to the code formatting, the code formatter **MUST** write to the changes back to the
+original location.
+
+If there is no changes to the original file, the formatter **MUST** NOT write to the original location.
+
+### 3. Idempotent
+
+The code formatter _SHOULD_ be indempotent. Meaning that it produces stable
+outputs.
+
+### 4. Reliable
+
+We expect the formatter to be reliable and not break the semantics of the formatted files.

docs/formatters.md

@@ -0,0 +1,143 @@
+# A list of known formatters
+
+Here is a list of all the formatters we tested. Feel free to send a PR to add
+other ones!
+
+## [prettier](https://prettier.io/)
+
+An opinionated code formatter that supports many languages.
+
+```toml
+command = "prettier"
+options = ["--write"]
+includes = [
+    "*.css",
+    "*.html",
+    "*.js",
+    "*.json",
+    "*.jsx",
+    "*.md",
+    "*.mdx",
+    "*.scss",
+    "*.ts",
+    "*.yaml",
+]
+```
+
+## [Black](https://github.com/psf/black)
+
+A python formatter.
+
+```toml
+command = "black"
+includes = ["*.py"]
+```
+
+## [clang-format](https://clang.llvm.org/docs/ClangFormat.html)
+
+A tool to format C/C++/Java/JavaScript/Objective-C/Protobuf/C# code.
+
+```toml
+command = "clang-format"
+options = [ "-i" ]
+includes = [ "*.c", "*.cpp", "*.cc", "*.h", "*.hpp" ]
+```
+
+Note: This example focuses on C/C++ but can be modified to use with other languages.
+
+## Elm
+
+```toml
+command = "elm-format"
+options = ["--yes"]
+includes = ["*.elm"]
+```
+
+## Go
+
+```toml
+command = "gofmt"
+options = ["-w"]
+includes = ["*.go"]
+```
+
+## [Ormolu](https://github.com/tweag/ormolu)
+
+Haskell formatter. Make sure to use ormolu 0.1.4.0+ as older versions don't
+adhere to the spec.
+
+```toml
+command = "ormolu"
+options = [
+    "--ghc-opt", "-XBangPatterns",
+    "--ghc-opt", "-XPatternSynonyms",
+    "--ghc-opt", "-XTypeApplications",
+    "--mode", "inplace",
+    "--check-idempotence",
+]
+includes = ["*.hs"]
+```
+
+## [stylish-haskell](https://github.com/jaspervdj/stylish-haskell)
+
+Another Haskell formatter.
+
+```toml
+command = "stylish-haskell"
+options = [ "--inplace" ]
+includes = [ "*.hs" ]
+```
+
+## [nixpkgs-fmt](https://github.com/nix-community/nixpkgs-fmt)
+
+Nix code formatter.
+
+```toml
+command = "nixpkgs-fmt"
+includes = ["*.nix"]
+```
+
+## rustfmt
+
+```toml
+command = "rustfmt"
+options = ["--edition", "2018"]
+includes = ["*.rs"]
+```
+
+## [rufo](https://github.com/ruby-formatter/rufo)
+
+Rufo is an opinionated ruby formatter. By default it exits with status 3 on
+file change so we have to pass the `-x` option.
+
+```toml
+command = "rufo"
+options = ["-x"]
+includes = ["*.rb"]
+```
+
+## cargo fmt
+
+`cargo fmt` is not supported as it doesn't follow the spec. It doesn't allow
+to pass arbitrary files to be formatted, which treefmt relies on. Use `rustfmt`
+instead (which is what `cargo fmt` uses under the hood).
+
+## [shfmt](https://github.com/mvdan/sh)
+
+A shell code formatter.
+
+```toml
+command = "shfmt"
+options = [
+  "-i",
+  "2",  # indent 2
+  "-s",  # simplify the code
+  "-w",  # write back to the file
+]
+includes = ["*.sh"]
+```
+
+## terraform
+
+terraform fmt only supports formatting one file at the time. See
+https://github.com/hashicorp/terraform/pull/28191

docs/index.md

@@ -0,0 +1,18 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+    name: "Treefmt"
+    text: "One CLI to format your repo"
+    image:
+        src: /treefmt.gif
+        alt: Treefmt
+    actions:
+        - theme: brand
+          text: Quick Start
+          link: /quick-start
+        - theme: alt
+          text: More Info
+          link: /overview
+---

docs/installation.md

@@ -0,0 +1,71 @@
+---
+outline: deep
+---
+
+# Installation
+
+There are two options to install `treefmt`:
+
+1. Downloading the latest binary
+2. Compiling and building it from source.
+
+## Installing with a binary file
+
+You can find the list of the latest binaries [here](https://github.com/numtide/treefmt.go/releases).
+
+## Building from source
+
+There are several ways to build `treefmt` from source. Your choice will depend on whether you're a [nix](https://github.com/NixOS/nix) user or
+not.
+
+### Non-Nix User
+
+To try the project without building it, run:
+
+```
+$ go run main.go --help
+```
+
+The command will output the manual. You can run the tool in this manner with any other flag or option to format your
+project.
+
+To build a binary, you need to have `go 1.22` installed. You can find instructions [here](https://go.dev/doc/install).
+
+Now, if you want to build the project, switch to the project root folder and run:
+
+```
+$ go build
+```
+
+After the successful execution of the build command, you will find the `treefmt` binary in the project root folder.
+
+### Nix User
+
+If you're using both `treefmt` and `nix`, you can go for [`treefmt-nix`](https://github.com/numtide/treefmt-nix), a wrapper that makes installation and
+configuration of `treefmt` with `nix` easier.
+
+**Non-flake user**
+
+Here you also have two options: you can install `treefmt` with plain nix-build , or with nix-shell.
+
+To build the package with nix-build, just run:
+
+```
+$ nix-build -A treefmt
+```
+
+**Nix-flake user**
+
+If you want to use this repository with flakes, please enable the flakes feature first. To run the project with flakes without building it, you can execute the following command in the root folder:
+
+```
+$ nix run . -- --help
+```
+
+To build the project, run the following command in the root folder:
+
+```
+$ nix build
+```
+
+The `treefmt` binary will be available in the result folder.

docs/overview.md

@@ -0,0 +1,75 @@
+# About the project
+
+`treefmt` is a formatting tool that saves you time: it provides developers with a universal way to trigger all
+formatters needed for the project in one place.
+
+## Background
+
+Typically, each project has its own code standards enforced by the project's owner. Any code contributions must match
+that given standard, i.e. be formatted in a specific manner.
+
+At first glance, the task of code formatting may seem trivial: the formatter can be automatically triggered when you
+save a file in your IDE. Indeed, formatting doesn't take much effort if you're working on a single project long term:
+setting up the formatters in your IDE won't take much of your time, and then you're ready to go.
+
+Contrary to that, if you're working on multiple projects at the same time, you may have to update your formatter
+configs in the IDE each time you switch between the projects. This is because formatter settings aren't
+project-specific --- they are set up globally for all projects.
+
+Alternatively, you can trigger formatters manually, one-by-one or in a script. Actually, for bigger projects, it's
+common to have a script that runs over your project's directories and calls formatters consequently. But it takes time
+to iterate through all the files.
+
+All the solutions take up a significant amount of time which a developer could spend doing the actual work. They also
+require you to remember which formatters and options are used by each project you are working on.
+
+`treefmt` solves these issues.
+
+## Why treefmt?
+
+`treefmt`'s configuration is project-specific, so you don't need to re-configure formatters each time you switch
+between projects, like you have to when working with formatters in the IDE.
+
+Contrary to calling formatters from the command line, there's no need to remember all the specific formatters required
+for each project. Once you set up the config, you can run the tool in any of your project's folders without any
+additional flags or options.
+
+Typically, formatters have different ways to say there was a specific error. With `treefmt`, you get a standardized
+output which is easier to understand than the variegated outputs of different formatters, so it takes less time to
+grasp what's wrong.
+
+In addition, `treefmt` works faster than the custom script solution because the changed files are cached and the
+formatters run only against them. Moreover, formatters are run in parallel, which makes the tool even faster.
+
+The difference may not be significant for smaller projects, but it gets quite visible as the project grows. For
+instance, take the caching optimization.
+
+It takes about 23 seconds to traverse a project of 40,559 files and no changes without caching:
+
+```
+traversed 41273 files
+emitted 41273 files for processing
+matched 34311 files to formatters
+formatted 14338 files in 23.679339987s
+```
+
+...while it takes **239 milliseconds** to traverse the same project with caching:
+
+```
+traversed 41273 files
+emitted 0 files for processing
+matched 0 files to formatters
+formatted 0 files in 239.024064ms
+```
+
+The tool can be invoked manually or integrated into your CI. There's currently no integration with IDEs, but the feature is coming soon.
+
+## What we still need help with
+
+-   **IDE integration:** Most of developers are used to formatting a file upon save in the IDE. So far, you can't use `treefmt` for this purpose, but we're working on it 😀
+-   **Pre-commit hook:** It's good to have your code checked for adherence to the project's standards before commit. `treefmt` pre-commit hook won't let you commit if you have formatting issues.
+
+As a next step, learn how to [install] and [use] `treefmt`.
+
+[install]: installation.md
+[use]: usage.md

docs/package.json

@@ -0,0 +1,13 @@
+{
+    "name": "treefmt-docs",
+    "version": "0.0.1",
+    "devDependencies": {
+        "vitepress": "^1.1.4"
+    },
+    "scripts": {
+        "vitepress": "vitepress",
+        "dev": "vitepress dev",
+        "build": "vitepress build",
+        "preview": "vitepress preview"
+    }
+}

docs/public/logo.svg

@@ -0,0 +1,194 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   inkscape:export-ydpi="512"
+   inkscape:export-xdpi="512"
+   inkscape:export-filename="/home/basile/dev/treefmt.png"
+   sodipodi:docname="treefmt.svg"
+   inkscape:version="1.0 (4035a4fb49, 2020-05-01)"
+   id="svg16"
+   version="1.1"
+   viewBox="0 0 12.7 12.7"
+   height="48"
+   width="48">
+  <defs
+     id="defs10">
+    <inkscape:path-effect
+       hide_knots="false"
+       only_selected="false"
+       apply_with_radius="true"
+       apply_no_radius="true"
+       use_knot_distance="true"
+       flexible="false"
+       chamfer_steps="1"
+       radius="0.5"
+       mode="F"
+       method="auto"
+       unit="px"
+       satellites_param="F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1"
+       lpeversion="1"
+       is_visible="true"
+       id="path-effect1012"
+       effect="fillet_chamfer" />
+    <inkscape:path-effect
+       hide_knots="false"
+       only_selected="false"
+       apply_with_radius="true"
+       apply_no_radius="true"
+       use_knot_distance="true"
+       flexible="false"
+       chamfer_steps="1"
+       radius="0.5"
+       mode="F"
+       method="auto"
+       unit="px"
+       satellites_param="F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1"
+       lpeversion="1"
+       is_visible="true"
+       id="path-effect1010"
+       effect="fillet_chamfer" />
+    <inkscape:path-effect
+       hide_knots="false"
+       only_selected="false"
+       apply_with_radius="true"
+       apply_no_radius="true"
+       use_knot_distance="true"
+       flexible="false"
+       chamfer_steps="1"
+       radius="0.5"
+       mode="F"
+       method="auto"
+       unit="px"
+       satellites_param="F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1 @ F,0,0,1,0,0.13229167,0,1"
+       lpeversion="1"
+       is_visible="true"
+       id="path-effect989"
+       effect="fillet_chamfer" />
+  </defs>
+  <sodipodi:namedview
+     inkscape:window-maximized="1"
+     inkscape:window-y="340"
+     inkscape:window-x="1440"
+     inkscape:window-height="1373"
+     inkscape:window-width="2560"
+     units="px"
+     showgrid="false"
+     inkscape:document-rotation="0"
+     inkscape:current-layer="layer1"
+     inkscape:document-units="mm"
+     inkscape:cy="29.374509"
+     inkscape:cx="-10.431476"
+     inkscape:zoom="11.2"
+     inkscape:pageshadow="2"
+     inkscape:pageopacity="0.0"
+     borderopacity="1.0"
+     bordercolor="#666666"
+     pagecolor="#ffffff"
+     id="base">
+    <inkscape:grid
+       dotted="false"
+       id="grid902"
+       type="xygrid" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata13">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     id="layer1"
+     inkscape:groupmode="layer"
+     inkscape:label="Layer 1">
+    <path
+       d="m 6.3370673,12.637056 c -0.5007028,0 -5.1699157,-2.6957712 -5.42026711,-3.1293926 C 0.66644877,9.074042 0.66644862,3.6824995 0.91680002,3.2488781 1.1671514,2.8152568 5.8363641,0.11948539 6.337067,0.11948538 c 0.5007028,-2e-8 5.169916,2.69577112 5.420267,3.12939252 0.250351,0.4336213 0.250352,5.8251638 0,6.2587852 -0.250351,0.4336214 -4.9195639,3.1293929 -5.4202667,3.1293929 z"
+       inkscape:randomized="0"
+       inkscape:rounded="0.08"
+       inkscape:flatsided="true"
+       sodipodi:arg2="2.0943951"
+       sodipodi:arg1="1.5707963"
+       sodipodi:r2="5.4202676"
+       sodipodi:r1="6.2587852"
+       sodipodi:cy="6.3782705"
+       sodipodi:cx="6.3370669"
+       sodipodi:sides="6"
+       id="path20"
+       style="fill:#729fcf;stroke-width:0.0142755"
+       sodipodi:type="star" />
+    <path
+       sodipodi:type="star"
+       style="fill:#888a85;stroke-width:0.0128537"
+       id="path20-3"
+       sodipodi:sides="6"
+       sodipodi:cx="6.3652418"
+       sodipodi:cy="6.3777179"
+       sodipodi:r1="5.6354737"
+       sodipodi:r2="4.8804641"
+       sodipodi:arg1="1.5707963"
+       sodipodi:arg2="2.0943951"
+       inkscape:flatsided="true"
+       inkscape:rounded="0.08"
+       inkscape:randomized="0"
+       d="m 6.3652422,12.013192 c -0.4508379,0 -4.6550446,-2.4273 -4.8804635,-2.817737 -0.225419,-0.3904371 -0.2254191,-5.2450367 -2e-7,-5.6354738 0.225419,-0.390437 4.4296255,-2.81773694 4.8804634,-2.81773696 0.4508379,-1e-8 4.6550441,2.42729966 4.8804631,2.81773676 0.225419,0.390437 0.225419,5.2450366 0,5.6354737 -0.225418,0.3904371 -4.4296249,2.8177373 -4.8804628,2.8177373 z" />
+    <path
+       sodipodi:type="rect"
+       d="m 4.6302084,3.8364582 5.0270831,0 A 0.13229167,0.13229167 45 0 1 9.7895832,3.9687499 V 4.4979165 A 0.13229167,0.13229167 135 0 1 9.6572915,4.6302082 l -5.0270831,0 A 0.13229167,0.13229167 45 0 1 4.4979167,4.4979165 V 3.9687499 A 0.13229167,0.13229167 135 0 1 4.6302084,3.8364582 Z"
+       inkscape:path-effect="#path-effect989"
+       y="3.8364582"
+       x="4.4979167"
+       height="0.79374999"
+       width="5.2916665"
+       id="rect898"
+       style="fill:#f57900;stroke-width:0.0121433" />
+    <circle
+       r="0.66145831"
+       style="fill:#73d216;stroke-width:0.0221209"
+       id="path860-3"
+       cx="2.778125"
+       cy="4.2333331" />
+    <circle
+       cy="6.4822917"
+       cx="4.6302085"
+       id="path860-3-5"
+       style="fill:#73d216;stroke-width:0.0221209"
+       r="0.66145831" />
+    <circle
+       r="0.66145831"
+       style="fill:#73d216;stroke-width:0.0221209"
+       id="path860-3-5-6"
+       cx="4.6302085"
+       cy="8.9958334" />
+    <path
+       sodipodi:type="rect"
+       d="M 6.4822916,6.0854168 H 9.6572915 A 0.13229167,0.13229167 45 0 1 9.7895832,6.2177085 V 6.7468751 A 0.13229167,0.13229167 135 0 1 9.6572915,6.8791668 H 6.4822916 A 0.13229167,0.13229167 45 0 1 6.3499999,6.7468751 V 6.2177085 A 0.13229167,0.13229167 135 0 1 6.4822916,6.0854168 Z"
+       inkscape:path-effect="#path-effect1010"
+       style="fill:#f57900;stroke-width:0.00979024"
+       id="rect898-2"
+       width="3.4395833"
+       height="0.79374999"
+       x="6.3499999"
+       y="6.0854168" />
+    <path
+       sodipodi:type="rect"
+       d="m 6.4822916,8.598959 3.1749999,0 A 0.13229167,0.13229167 45 0 1 9.7895832,8.7312506 V 9.2604173 A 0.13229167,0.13229167 135 0 1 9.6572915,9.392709 l -3.1749999,0 A 0.13229167,0.13229167 45 0 1 6.3499999,9.2604173 V 8.7312506 A 0.13229167,0.13229167 135 0 1 6.4822916,8.598959 Z"
+       inkscape:path-effect="#path-effect1012"
+       y="8.598959"
+       x="6.3499999"
+       height="0.79374999"
+       width="3.4395833"
+       id="rect898-2-9"
+       style="fill:#f57900;stroke-width:0.00979024" />
+  </g>
+</svg>

docs/quick-start.md

@@ -0,0 +1,18 @@
+---
+outline: none
+---
+
+# Quick start
+
+To run `treefmt` in your project, please follow these steps:
+
+1. [Install] `treefmt`.
+2. Install any formatters you wish to use with `treefmt`.
+3. Run `treefmt --init` to generate a basic configuration file `treefmt.toml`.
+4. Edit the configuration, adding formatters as desired. See [here] for more info on how to configure a formatter.
+5. Run `treefmt` with the needed flags and options. You can check the supported options by executing `treefmt --help`.
+
+In the following sections we will guide you through installing and configuring `treefmt` in detail.
+
+[install]: installation.md
+[here]: formatter-spec.md

docs/usage.md

@@ -0,0 +1,113 @@
+# Usage
+
+You can run treefmt by executing:
+
+`$ treefmt`
+
+or, if it's not in your `$PATH`:
+
+`$ ./treefmt`
+
+Treefmt has the following specification:
+
+```
+treefmt [FLAGS] [OPTIONS] [--] [paths]...
+```
+
+## Flags
+
+`--walk <auto|git|filesystem>`
+
+> The method used to traverse the files within `<tree-root>`.
+> Default is `auto`, where we will detect if the `<tree-root>` is a git repository and use the `git` walker for
+> traversal. If not we will fall back to the `filesystem` walker.
+
+`--allow-missing-formatter`
+
+> Do not exit with an error if some of the configured formatters are missing.
+
+`--clear-cache`
+
+> Reset the evaluation cache. Invalidation should happen automatically if the formatting tool has been updated, or if the files to format have changed. If cache wasn't properly invalidated, you can use this flag to clear the cache.
+
+`--fail-on-change`
+
+> Exit with error if some files require re-formatting. This is useful for your CI if you want to detect if the contributed code was forgotten to be formatted.
+
+`-h, --help`
+
+> Prints available flags and options
+
+`--init`
+
+> Creates a new config file `treefmt.toml`.
+
+`--no-cache`
+
+> Tells `treefmt` to ignore the evaluation cache entirely. With this flag, you can avoid cache invalidation issues, if any. Typically, the machine that is running treefmt in the CI is starting with a fresh environment each time, so any calculated cache is lost. The `--no-cache` flag eliminates unnecessary work in the CI.
+
+`-q, --quiet`
+
+> Don't print output to stderr.
+
+`--stdin`
+
+> Format the content passed in stdin.
+
+`-V, --version`
+
+> Print version information.
+
+`-v, --verbose`
+
+> Change the log verbosity. Log verbosity is based off the number of 'v' used. With one `-v`, your logs will display `[INFO]` and `[ERROR]` messages, while `-vv` will also show `[DEBUG]` messages.
+
+`--config-file <config-file>`
+
+> Run with the specified config file which is not in the project tree.
+
+`-f, --formatters <formatters>...`
+
+> Only apply selected formatters. Defaults to all formatters.
+
+`--tree-root <tree-root>`
+
+> Set the path to the tree root directory where treefmt will look for the files to format. Defaults to the folder holding the `treefmt.toml` file. It’s mostly useful in combination with `--config-file` to specify the project root which won’t coincide with the directory holding `treefmt.toml`.
+
+`-C <work-dir>`
+
+> Run as if `treefmt` was started in `<work-dir>` instead of the current working directory (default: `.`). Equivalent to `cd <work dir>; treefmt`.
+
+## Arguments
+
+`<paths>...`
+
+> Paths to format. Defaults to formatting the whole tree
+
+## CI integration
+
+Typically, you would use treefmt in the CI with the `--fail-on-change` and `--no-cache flags`. Find the explanations above.
+
+You can you set a `treefmt` job in the GitHub pipeline for Ubuntu with nix-shell like this:
+
+```yaml
+name: treefmt
+on:
+    pull_request:
+    push:
+        branches: main
+jobs:
+    formatter:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v1
+            - uses: cachix/install-nix-action@v12
+              with:
+                  nix_path: nixpkgs=channel:nixos-unstable
+            - uses: cachix/cachix-action@v10
+              with:
+                  name: nix-community
+                  authToken: "${{ secrets.CACHIX_AUTH_TOKEN }}"
+            - name: treefmt
+              run: nix-shell --run "treefmt --fail-on-change --no-cache"
+```

docs/vhs/init.tape

@@ -0,0 +1,29 @@
+Require treefmt
+Require nano
+
+Set Shell zsh
+Set FontSize 14
+
+Set Theme "Catppuccin Mocha"
+
+Set Width 720
+Set Height 360
+Set Padding 20
+
+Hide
+Type "TEMP_DIR=$(mktemp -d) && cd $TEMP_DIR && clear"
+Enter
+
+Show
+Type "treefmt --init"
+Enter
+Sleep 2s
+
+Type "nano treefmt.toml"
+Enter
+Sleep 5s
+
+Ctrl+x
+
+Hide
+Type "cd && rm -rf $TEMP_DIR"

docs/vhs/treefmt.tape

@@ -0,0 +1,36 @@
+Require rsync
+Require treefmt
+
+Set Shell zsh
+Set FontSize 11
+
+Set Theme "Catppuccin Mocha"
+
+Set Width 320
+Set Height 220
+Set Padding 20
+
+Hide
+Type "TEMP_DIR=$(mktemp -d) && rsync -av $PRJ_ROOT/test/examples/ $TEMP_DIR && cd $TEMP_DIR && clear"
+Enter
+Type "alias treefmt='treefmt --allow-missing-formatter' && clear"
+Enter
+Show
+
+Type "treefmt -c"
+Sleep 1s
+Enter
+
+Sleep 3s
+Enter
+Enter
+Sleep 1s
+
+Type "treefmt"
+Enter
+
+Sleep 5s
+
+Hide
+Type "cd && rm -rf $TEMP_DIR"
+Enter

flake.lock

@@ -21,6 +21,21 @@
         "type": "github"
       }
     },
+    "flake-compat": {
+      "locked": {
+        "lastModified": 1688025799,
+        "narHash": "sha256-ktpB4dRtnksm9F5WawoIkEneh1nrEvuxb5lJFt1iOyw=",
+        "owner": "nix-community",
+        "repo": "flake-compat",
+        "rev": "8bf105319d44f6b9f0d764efa4fdef9f1cc9ba1c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
     "flake-parts": {
       "inputs": {
         "nixpkgs-lib": "nixpkgs-lib"
@@ -39,21 +54,6 @@
         "type": "github"
       }
     },
-    "flake-root": {
-      "locked": {
-        "lastModified": 1713493429,
-        "narHash": "sha256-ztz8JQkI08tjKnsTpfLqzWoKFQF4JGu2LRz8bkdnYUk=",
-        "owner": "srid",
-        "repo": "flake-root",
-        "rev": "bc748b93b86ee76e2032eecda33440ceb2532fcd",
-        "type": "github"
-      },
-      "original": {
-        "owner": "srid",
-        "repo": "flake-root",
-        "type": "github"
-      }
-    },
     "flake-utils": {
       "inputs": {
         "systems": "systems"
@@ -163,8 +163,8 @@
     "root": {
       "inputs": {
         "devshell": "devshell",
+        "flake-compat": "flake-compat",
         "flake-parts": "flake-parts",
-        "flake-root": "flake-root",
         "gomod2nix": "gomod2nix",
         "nix-filter": "nix-filter",
         "nixpkgs": "nixpkgs",

flake.nix

@@ -1,11 +1,9 @@
 {
-  description = "Treefmt";
+  description = "Treefmt: once CLI to format your repo";
 
   inputs = {
     nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
-
     flake-parts.url = "github:hercules-ci/flake-parts";
-    flake-root.url = "github:srid/flake-root";
     treefmt-nix = {
       # todo switch back to numtide/treefmt-nix once merged
       url = "github:brianmcgee/treefmt-nix/feat/pipelines";
@@ -19,8 +17,8 @@
       url = "github:nix-community/gomod2nix";
       inputs.nixpkgs.follows = "nixpkgs";
     };
-
     nix-filter.url = "github:numtide/nix-filter";
+    flake-compat.url = "github:nix-community/flake-compat";
   };
 
   outputs = inputs @ {flake-parts, ...}:

go.mod

@@ -1,30 +1,30 @@
 module git.numtide.com/numtide/treefmt
 
-go 1.21
+go 1.22
 
 require (
 	github.com/BurntSushi/toml v1.3.2
 	github.com/adrg/xdg v0.4.0
-	github.com/alecthomas/kong v0.8.1
-	github.com/charmbracelet/log v0.3.1
+	github.com/alecthomas/kong v0.9.0
+	github.com/charmbracelet/log v0.4.0
 	github.com/go-git/go-billy/v5 v5.5.0
-	github.com/go-git/go-git/v5 v5.11.0
+	github.com/go-git/go-git/v5 v5.12.0
 	github.com/gobwas/glob v0.2.3
 	github.com/otiai10/copy v1.14.0
-	github.com/stretchr/testify v1.8.4
+	github.com/stretchr/testify v1.9.0
 	github.com/vmihailenco/msgpack/v5 v5.4.1
-	go.etcd.io/bbolt v1.3.8
-	golang.org/x/sync v0.5.0
+	go.etcd.io/bbolt v1.3.9
+	golang.org/x/sync v0.7.0
 )
 
 require (
 	dario.cat/mergo v1.0.0 // indirect
-	github.com/Microsoft/go-winio v0.6.1 // indirect
-	github.com/ProtonMail/go-crypto v0.0.0-20230828082145-3c4c8a2d2371 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
+	github.com/ProtonMail/go-crypto v1.0.0 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
-	github.com/charmbracelet/lipgloss v0.9.1 // indirect
-	github.com/cloudflare/circl v1.3.3 // indirect
-	github.com/cyphar/filepath-securejoin v0.2.4 // indirect
+	github.com/charmbracelet/lipgloss v0.10.0 // indirect
+	github.com/cloudflare/circl v1.3.8 // indirect
+	github.com/cyphar/filepath-securejoin v0.2.5 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/emirpasic/gods v1.18.1 // indirect
 	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
@@ -33,23 +33,23 @@ require (
 	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
 	github.com/kevinburke/ssh_config v1.2.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
-	github.com/mattn/go-isatty v0.0.18 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-runewidth v0.0.15 // indirect
 	github.com/muesli/reflow v0.3.0 // indirect
 	github.com/muesli/termenv v0.15.2 // indirect
 	github.com/pjbgf/sha1cd v0.3.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/rivo/uniseg v0.2.0 // indirect
-	github.com/sergi/go-diff v1.1.0 // indirect
-	github.com/skeema/knownhosts v1.2.1 // indirect
+	github.com/rivo/uniseg v0.4.7 // indirect
+	github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 // indirect
+	github.com/skeema/knownhosts v1.2.2 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect
 	github.com/xanzy/ssh-agent v0.3.3 // indirect
-	golang.org/x/crypto v0.16.0 // indirect
-	golang.org/x/exp v0.0.0-20231006140011-7918f672742d // indirect
-	golang.org/x/mod v0.13.0 // indirect
-	golang.org/x/net v0.19.0 // indirect
-	golang.org/x/sys v0.15.0 // indirect
-	golang.org/x/tools v0.14.0 // indirect
+	golang.org/x/crypto v0.22.0 // indirect
+	golang.org/x/exp v0.0.0-20240416160154-fe59bbe5cc7f // indirect
+	golang.org/x/mod v0.17.0 // indirect
+	golang.org/x/net v0.24.0 // indirect
+	golang.org/x/sys v0.19.0 // indirect
+	golang.org/x/tools v0.20.0 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -5,14 +5,20 @@ github.com/BurntSushi/toml v1.3.2/go.mod h1:CxXYINrC8qIiEnFrOxCa7Jy5BFHlXnUU2pbi
 github.com/Microsoft/go-winio v0.5.2/go.mod h1:WpS1mjBmmwHBEWmogvA2mj8546UReBk4v8QkMxJ6pZY=
 github.com/Microsoft/go-winio v0.6.1 h1:9/kr64B9VUZrLm5YYwbGtUJnMgqWVOdUAXu6Migciow=
 github.com/Microsoft/go-winio v0.6.1/go.mod h1:LRdKpFKfdobln8UmuiYcKPot9D2v6svN5+sAH+4kjUM=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/ProtonMail/go-crypto v0.0.0-20230828082145-3c4c8a2d2371 h1:kkhsdkhsCvIsutKu5zLMgWtgh9YxGCNAw8Ad8hjwfYg=
 github.com/ProtonMail/go-crypto v0.0.0-20230828082145-3c4c8a2d2371/go.mod h1:EjAoLdwvbIOoOQr3ihjnSoLZRtE8azugULFRteWMNc0=
+github.com/ProtonMail/go-crypto v1.0.0 h1:LRuvITjQWX+WIfr930YHG2HNfjR1uOfyf5vE0kC2U78=
+github.com/ProtonMail/go-crypto v1.0.0/go.mod h1:EjAoLdwvbIOoOQr3ihjnSoLZRtE8azugULFRteWMNc0=
 github.com/adrg/xdg v0.4.0 h1:RzRqFcjH4nE5C6oTAxhBtoE2IRyjBSa62SCbyPidvls=
 github.com/adrg/xdg v0.4.0/go.mod h1:N6ag73EX4wyxeaoeHctc1mas01KZgsj5tYiAIwqJE/E=
 github.com/alecthomas/assert/v2 v2.1.0 h1:tbredtNcQnoSd3QBhQWI7QZ3XHOVkw1Moklp2ojoH/0=
 github.com/alecthomas/assert/v2 v2.1.0/go.mod h1:b/+1DI2Q6NckYi+3mXyH3wFb8qG37K/DuK80n7WefXA=
 github.com/alecthomas/kong v0.8.1 h1:acZdn3m4lLRobeh3Zi2S2EpnXTd1mOL6U7xVml+vfkY=
 github.com/alecthomas/kong v0.8.1/go.mod h1:n1iCIO2xS46oE8ZfYCNDqdR0b0wZNrXAIAqro/2132U=
+github.com/alecthomas/kong v0.9.0 h1:G5diXxc85KvoV2f0ZRVuMsi45IrBgx9zDNGNj165aPA=
+github.com/alecthomas/kong v0.9.0/go.mod h1:Y47y5gKfHp1hDc7CH7OeXgLIpp+Q2m1Ni0L5s3bI8Os=
 github.com/alecthomas/repr v0.1.0 h1:ENn2e1+J3k09gyj2shc0dHr/yjaWSHRlrJ4DPMevDqE=
 github.com/alecthomas/repr v0.1.0/go.mod h1:2kn6fqh/zIyPLmm3ugklbEi5hg5wS435eygvNfaDQL8=
 github.com/anmitsu/go-shlex v0.0.0-20200514113438-38f4b401e2be h1:9AeTilPcZAjCFIImctFaOjnTIavg87rW78vTPkQqLI8=
@@ -24,12 +30,20 @@ github.com/aymanbagabas/go-osc52/v2 v2.0.1/go.mod h1:uYgXzlJ7ZpABp8OJ+exZzJJhRNQ
 github.com/bwesterb/go-ristretto v1.2.3/go.mod h1:fUIoIZaG73pV5biE2Blr2xEzDoMj7NFEuV9ekS419A0=
 github.com/charmbracelet/lipgloss v0.9.1 h1:PNyd3jvaJbg4jRHKWXnCj1akQm4rh8dbEzN1p/u1KWg=
 github.com/charmbracelet/lipgloss v0.9.1/go.mod h1:1mPmG4cxScwUQALAAnacHaigiiHB9Pmr+v1VEawJl6I=
+github.com/charmbracelet/lipgloss v0.10.0 h1:KWeXFSexGcfahHX+54URiZGkBFazf70JNMtwg/AFW3s=
+github.com/charmbracelet/lipgloss v0.10.0/go.mod h1:Wig9DSfvANsxqkRsqj6x87irdy123SR4dOXlKa91ciE=
 github.com/charmbracelet/log v0.3.1 h1:TjuY4OBNbxmHWSwO3tosgqs5I3biyY8sQPny/eCMTYw=
 github.com/charmbracelet/log v0.3.1/go.mod h1:OR4E1hutLsax3ZKpXbgUqPtTjQfrh1pG3zwHGWuuq8g=
+github.com/charmbracelet/log v0.4.0 h1:G9bQAcx8rWA2T3pWvx7YtPTPwgqpk7D68BX21IRW8ZM=
+github.com/charmbracelet/log v0.4.0/go.mod h1:63bXt/djrizTec0l11H20t8FDSvA4CRZJ1KH22MdptM=
 github.com/cloudflare/circl v1.3.3 h1:fE/Qz0QdIGqeWfnwq0RE0R7MI51s0M2E4Ga9kq5AEMs=
 github.com/cloudflare/circl v1.3.3/go.mod h1:5XYMA4rFBvNIrhs50XuiBJ15vF2pZn4nnUKZrLbUZFA=
+github.com/cloudflare/circl v1.3.8 h1:j+V8jJt09PoeMFIu2uh5JUyEaIHTXVOHslFoLNAKqwI=
+github.com/cloudflare/circl v1.3.8/go.mod h1:PDRU+oXvdD7KCtgKxW95M5Z8BpSCJXQORiZFnBQS5QU=
 github.com/cyphar/filepath-securejoin v0.2.4 h1:Ugdm7cg7i6ZK6x3xDF1oEu1nfkyfH53EtKeQYTC3kyg=
 github.com/cyphar/filepath-securejoin v0.2.4/go.mod h1:aPGpWjXOXUn2NCNjFvBE6aRxGGx79pTxQpKOJNYHHl4=
+github.com/cyphar/filepath-securejoin v0.2.5 h1:6iR5tXJ/e6tJZzzdMc1km3Sa7RRIVBKAK32O2s7AYfo=
+github.com/cyphar/filepath-securejoin v0.2.5/go.mod h1:aPGpWjXOXUn2NCNjFvBE6aRxGGx79pTxQpKOJNYHHl4=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -39,6 +53,7 @@ github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc
 github.com/emirpasic/gods v1.18.1/go.mod h1:8tpGGwCnJ5H4r6BWwaV6OrWmMoPhUl5jm/FMNAnJvWQ=
 github.com/gliderlabs/ssh v0.3.5 h1:OcaySEmAQJgyYcArR+gGGTHCyE7nvhEMTlYY+Dp8CpY=
 github.com/gliderlabs/ssh v0.3.5/go.mod h1:8XB4KraRrX39qHhT6yxPsHedjA08I/uBVwj4xC+/+z4=
+github.com/gliderlabs/ssh v0.3.7 h1:iV3Bqi942d9huXnzEF2Mt+CY9gLu8DNM4Obd+8bODRE=
 github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 h1:+zs/tPmkDkHx3U66DAb0lQFJrpS6731Oaa12ikc+DiI=
 github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376/go.mod h1:an3vInlBmSxCcxctByoQdvwPiA7DTK7jaaFDBTtu0ic=
 github.com/go-git/go-billy/v5 v5.5.0 h1:yEY4yhzCDuMGSv83oGxiBotRzhwhNr8VZyphhiu+mTU=
@@ -47,6 +62,8 @@ github.com/go-git/go-git-fixtures/v4 v4.3.2-0.20231010084843-55a94097c399 h1:eMj
 github.com/go-git/go-git-fixtures/v4 v4.3.2-0.20231010084843-55a94097c399/go.mod h1:1OCfN199q1Jm3HZlxleg+Dw/mwps2Wbk9frAWm+4FII=
 github.com/go-git/go-git/v5 v5.11.0 h1:XIZc1p+8YzypNr34itUfSvYJcv+eYdTnTvOZ2vD3cA4=
 github.com/go-git/go-git/v5 v5.11.0/go.mod h1:6GFcX2P3NM7FPBfpePbpLd21XxsgdAt+lKqXmCUiUCY=
+github.com/go-git/go-git/v5 v5.12.0 h1:7Md+ndsjrzZxbddRDZjF14qK+NN56sy6wkqaVrjZtys=
+github.com/go-git/go-git/v5 v5.12.0/go.mod h1:FTM9VKtnI2m65hNI/TenDDDnUf2Q9FHnXYjuz9i5OEY=
 github.com/go-logfmt/logfmt v0.6.0 h1:wGYYu3uicYdqXVgoYbvnkrPVXkuLM1p1ifugDMEdRi4=
 github.com/go-logfmt/logfmt v0.6.0/go.mod h1:WYhtIu8zTZfxdn5+rREduYbwxfcBr/Vr6KEVveWlfTs=
 github.com/gobwas/glob v0.2.3 h1:A4xDbljILXROh+kObIiy5kIaPYD8e96x1tgBhUI5J+Y=
@@ -72,6 +89,8 @@ github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69
 github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.18 h1:DOKFKCQ7FNG2L1rbrmstDN4QVRdS89Nkh85u68Uwp98=
 github.com/mattn/go-isatty v0.0.18/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/mattn/go-runewidth v0.0.12/go.mod h1:RAqKPSqVFrSLVXbA8x7dzmKdmGzieGRCM46jaSJTDAk=
 github.com/mattn/go-runewidth v0.0.15 h1:UNAjwbU9l54TA3KzvqLGxwWjHmMgBUVhBiTjelZgg3U=
 github.com/mattn/go-runewidth v0.0.15/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w=
@@ -94,19 +113,26 @@ github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZN
 github.com/rivo/uniseg v0.1.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
 github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=
+github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88=
 github.com/rogpeppe/go-internal v1.11.0 h1:cWPaGQEPrBb5/AsnsZesgZZ9yb1OQ+GOISoDNXVBh4M=
 github.com/rogpeppe/go-internal v1.11.0/go.mod h1:ddIwULY96R17DhadqLgMfk9H9tvdUzkipdSkR5nkCZA=
 github.com/sergi/go-diff v1.1.0 h1:we8PVUC3FE2uYfodKH/nBHMSetSfHDR6scGdBi+erh0=
 github.com/sergi/go-diff v1.1.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=
+github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 h1:n661drycOFuPLCN3Uc8sB6B/s6Z4t2xvBgU1htSHuq8=
+github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
 github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
 github.com/skeema/knownhosts v1.2.1 h1:SHWdIUa82uGZz+F+47k8SY4QhhI291cXCpopT1lK2AQ=
 github.com/skeema/knownhosts v1.2.1/go.mod h1:xYbVRSPxqBZFrdmDyMmsOs+uX1UZC3nTN3ThzgDxUwo=
+github.com/skeema/knownhosts v1.2.2 h1:Iug2P4fLmDw9f41PB6thxUkNUkJzB5i+1/exaj40L3A=
+github.com/skeema/knownhosts v1.2.2/go.mod h1:xYbVRSPxqBZFrdmDyMmsOs+uX1UZC3nTN3ThzgDxUwo=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs=
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/vmihailenco/msgpack/v5 v5.4.1 h1:cQriyiUvjTwOHg8QZaPihLWeRAAVoCpE00IUPn0Bjt8=
 github.com/vmihailenco/msgpack/v5 v5.4.1/go.mod h1:GaZTsDaehaPpQVyxrf5mtQlH+pc21PIudVV/E3rRQok=
 github.com/vmihailenco/tagparser/v2 v2.0.0 h1:y09buUbR+b5aycVFQs/g70pqKVZNBmxwAhO7/IwNM9g=
@@ -116,6 +142,8 @@ github.com/xanzy/ssh-agent v0.3.3/go.mod h1:6dzNDKs0J9rVPHPhaGCukekBHKqfl+L3KghI
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.etcd.io/bbolt v1.3.8 h1:xs88BrvEv273UsB79e0hcVrlUWmS0a8upikMFhSyAtA=
 go.etcd.io/bbolt v1.3.8/go.mod h1:N9Mkw9X8x5fupy0IKsmuqVtoGDyxsaDlbk4Rd05IAQw=
+go.etcd.io/bbolt v1.3.9 h1:8x7aARPEXiXbHmtUwAIv7eV2fQFHrLLavdiJ3uzJXoI=
+go.etcd.io/bbolt v1.3.9/go.mod h1:zaO32+Ti0PK1ivdPtgMESzuzL2VPoIG1PCQNvOdo/dE=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
@@ -123,12 +151,18 @@ golang.org/x/crypto v0.3.1-0.20221117191849-2c476679df9a/go.mod h1:hebNnKkNXi2Uz
 golang.org/x/crypto v0.7.0/go.mod h1:pYwdfH91IfpZVANVyUOhSIPZaFoJGxTFbZhFTx+dXZU=
 golang.org/x/crypto v0.16.0 h1:mMMrFzRSCF0GvB7Ne27XVtVAaXLrPmgPC7/v0tkwHaY=
 golang.org/x/crypto v0.16.0/go.mod h1:gCAAfMLgwOJRpTjQ2zCCt2OcSfYMTeZVSRtQlPC7Nq4=
+golang.org/x/crypto v0.22.0 h1:g1v0xeRhjcugydODzvb3mEM9SQ0HGp9s/nh3COQ/C30=
+golang.org/x/crypto v0.22.0/go.mod h1:vr6Su+7cTlO45qkww3VDJlzDn0ctJvRgYbC2NvXHt+M=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d h1:jtJma62tbqLibJ5sFQz8bKtEM8rJBtfilJ2qTU199MI=
 golang.org/x/exp v0.0.0-20231006140011-7918f672742d/go.mod h1:ldy0pHrwJyGW56pPQzzkH36rKxoZW1tw7ZJpeKx+hdo=
+golang.org/x/exp v0.0.0-20240416160154-fe59bbe5cc7f h1:99ci1mjWVBWwJiEKYY6jWa4d2nTQVIEhZIptnrVb1XY=
+golang.org/x/exp v0.0.0-20240416160154-fe59bbe5cc7f/go.mod h1:/lliqkxwWAhPjf5oSOIJup2XcqJaw8RGS6k3TGEc7GI=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.13.0 h1:I/DsJXRlw/8l/0c24sM9yb0T4z9liZTduXvdAWYiysY=
 golang.org/x/mod v0.13.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
+golang.org/x/mod v0.17.0 h1:zY54UmvipHiNd+pm+m0x9KhZ9hl1/7QNMyxXbc6ICqA=
+golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
@@ -138,11 +172,15 @@ golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
 golang.org/x/net v0.8.0/go.mod h1:QVkue5JL9kW//ek3r6jTKnTFis1tRmNAW2P1shuFdJc=
 golang.org/x/net v0.19.0 h1:zTwKpTd2XuCqf8huc7Fo2iSy+4RHPd10s4KzeTnVr1c=
 golang.org/x/net v0.19.0/go.mod h1:CfAk/cbD4CthTvqiEl8NpboMuiuOYsAr/7NOjZJtv1U=
+golang.org/x/net v0.24.0 h1:1PcaxkF854Fu3+lvBIx5SYn9wRlBzzcnHZSiaFFAb0w=
+golang.org/x/net v0.24.0/go.mod h1:2Q7sJY5mzlzWjKtYUEXSlBWCdyaioyXzRB2RtU8KVE8=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.5.0 h1:60k92dhOjHxJkrqnwsfl8KuaHbn/5dl0lUPUklKo3qE=
 golang.org/x/sync v0.5.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M=
+golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -159,6 +197,8 @@ golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.15.0 h1:h48lPFYpsTvQJZF4EKyI4aLHaev3CxivZmv7yZig9pc=
 golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.19.0 h1:q5f1RH2jigJ1MoAWp2KTp3gm5zAGFUTarQZ5U386+4o=
+golang.org/x/sys v0.19.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/term v0.2.0/go.mod h1:TVmDHMZPmdnySmBfhjOoOdhjzdE1h4u1VwSiw2l1Nuc=
@@ -181,6 +221,8 @@ golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
 golang.org/x/tools v0.14.0 h1:jvNa2pY0M4r62jkRQ6RwEZZyPcymeL9XZMLBbV7U2nc=
 golang.org/x/tools v0.14.0/go.mod h1:uYBEerGOWcJyEORxN+Ek8+TT266gXkNlHdJBwexUsBg=
+golang.org/x/tools v0.20.0 h1:hz/CVckiOxybQvFw6h7b/q80NTr9IUQb4s1IIzW7KNY=
+golang.org/x/tools v0.20.0/go.mod h1:WvitBU7JJf6A4jOdg4S1tviW9bhUxkgeCui/0JHctQg=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -190,6 +232,7 @@ gopkg.in/warnings.v0 v0.1.2 h1:wFXVbFY8DY5/xOe1ECiWdKCzZlxgshcYVNkBHstARME=
 gopkg.in/warnings.v0 v0.1.2/go.mod h1:jksf8JmL6Qr/oQM2OXTHunEvvTAsrWBLb6OOjuVWRNI=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

gomod2nix.toml

@@ -8,32 +8,32 @@ schema = 3
     version = "v1.3.2"
     hash = "sha256-FIwyH67KryRWI9Bk4R8s1zFP0IgKR4L66wNQJYQZLeg="
   [mod."github.com/Microsoft/go-winio"]
-    version = "v0.6.1"
-    hash = "sha256-BL0BVaHtmPKQts/711W59AbHXjGKqFS4ZTal0RYnR9I="
+    version = "v0.6.2"
+    hash = "sha256-tVNWDUMILZbJvarcl/E7tpSnkn7urqgSHa2Eaka5vSU="
   [mod."github.com/ProtonMail/go-crypto"]
-    version = "v0.0.0-20230828082145-3c4c8a2d2371"
-    hash = "sha256-YxAaQgQoTOhD8hE+aT+T8ytKKxcQW6tgoL2MAU7nTvo="
+    version = "v1.0.0"
+    hash = "sha256-Gflazvyv+457FpUTtPafJ+SdolYSalpsU0tragTxNi8="
   [mod."github.com/adrg/xdg"]
     version = "v0.4.0"
     hash = "sha256-zGjkdUQmrVqD6rMO9oDY+TeJCpuqnHyvkPCaXDlac/U="
   [mod."github.com/alecthomas/kong"]
-    version = "v0.8.1"
-    hash = "sha256-170mjSrLNC+0W1KhXltaa+YWYgt5gJQEcfssepcyh4E="
+    version = "v0.9.0"
+    hash = "sha256-5tojaBT73EB/IY8MewNjzJnNTQ+5jSw2Nxe3IjLSwXA="
   [mod."github.com/aymanbagabas/go-osc52/v2"]
     version = "v2.0.1"
     hash = "sha256-6Bp0jBZ6npvsYcKZGHHIUSVSTAMEyieweAX2YAKDjjg="
   [mod."github.com/charmbracelet/lipgloss"]
-    version = "v0.9.1"
-    hash = "sha256-AHbabOymgDRIXsMBgJHS25/GgBWT54oGbd15EBWKeZc="
+    version = "v0.10.0"
+    hash = "sha256-JZD1iVeizYe0mp3qQcJbUZdYN6HP/DNC67ja79DTe6s="
   [mod."github.com/charmbracelet/log"]
-    version = "v0.3.1"
-    hash = "sha256-Er60POPID2eNrRZnBHxoI4yHn0mIKnXYftGKSslbXx0="
+    version = "v0.4.0"
+    hash = "sha256-VQerB44vC646n3fe3haJ3DHa9L5+GRhCfDfm1p3QnZk="
   [mod."github.com/cloudflare/circl"]
-    version = "v1.3.3"
-    hash = "sha256-ItdVkU53Ep01553/tJ4MdAwoTpPljRxiBW9sAd7p0xI="
+    version = "v1.3.8"
+    hash = "sha256-6FbUbOjD8UDb2DIUzVCtI6S+Ja7Dk1pQLc0j0SWZaCk="
   [mod."github.com/cyphar/filepath-securejoin"]
-    version = "v0.2.4"
-    hash = "sha256-heCD0xMxlwnHCHcRBgTjVexHOLyWI2zRW3E8NFKoLzk="
+    version = "v0.2.5"
+    hash = "sha256-Hb9fRUHnMJJwy7XuHRG2l0YiTKh/5jUz2YJVdYScIfE="
   [mod."github.com/davecgh/go-spew"]
     version = "v1.1.1"
     hash = "sha256-nhzSUrE1fCkN0+RL04N4h8jWmRFPPPWbCuDc7Ss0akI="
@@ -47,8 +47,8 @@ schema = 3
     version = "v5.5.0"
     hash = "sha256-4XUoD2bOCMCdu83egb/y8kY/Fm0s1rWgPMtiahh38OQ="
   [mod."github.com/go-git/go-git/v5"]
-    version = "v5.11.0"
-    hash = "sha256-2yUM/FlV+nYxacVynJCnDZeMub4Iu8JL2WBHmlnwOkE="
+    version = "v5.12.0"
+    hash = "sha256-mD8EWOQ25FtKBWVSQhQ8V1Rr0tC/ySFZQ9GMDLRqwQU="
   [mod."github.com/go-logfmt/logfmt"]
     version = "v0.6.0"
     hash = "sha256-RtIG2qARd5sT10WQ7F3LR8YJhS8exs+KiuUiVf75bWg="
@@ -68,8 +68,8 @@ schema = 3
     version = "v1.2.0"
     hash = "sha256-Gg9dDJFCTaHrKHRR1SrJgZ8fWieJkybljybkI9x0gyE="
   [mod."github.com/mattn/go-isatty"]
-    version = "v0.0.18"
-    hash = "sha256-QpIn0DSggtBn2ocyj0RlXDKLK5F5KZG1/ogzrqBCjF8="
+    version = "v0.0.20"
+    hash = "sha256-qhw9hWtU5wnyFyuMbKx+7RB8ckQaFQ8D+8GKPkN3HHQ="
   [mod."github.com/mattn/go-runewidth"]
     version = "v0.0.15"
     hash = "sha256-WP39EU2UrQbByYfnwrkBDoKN7xzXsBssDq3pNryBGm0="
@@ -89,17 +89,17 @@ schema = 3
     version = "v1.0.0"
     hash = "sha256-/FtmHnaGjdvEIKAJtrUfEhV7EVo5A/eYrtdnUkuxLDA="
   [mod."github.com/rivo/uniseg"]
-    version = "v0.2.0"
-    hash = "sha256-GLj0jiGrT03Ept4V6FXCN1yeZ/b6PpS3MEXK6rYQ8Eg="
+    version = "v0.4.7"
+    hash = "sha256-rDcdNYH6ZD8KouyyiZCUEy8JrjOQoAkxHBhugrfHjFo="
   [mod."github.com/sergi/go-diff"]
-    version = "v1.1.0"
-    hash = "sha256-8NJMabldpf40uwQN20T6QXx5KORDibCBJL02KD661xY="
+    version = "v1.3.2-0.20230802210424-5b0b94c5c0d3"
+    hash = "sha256-UcLU83CPMbSoKI8RLvLJ7nvGaE2xRSL1RjoHCVkMzUM="
   [mod."github.com/skeema/knownhosts"]
-    version = "v1.2.1"
-    hash = "sha256-u0jB6ahTdGa+SvcIvPNRLnbSHvgmW9X/ThRq0nWQrJs="
+    version = "v1.2.2"
+    hash = "sha256-kSYIrpQZbCJg7pgjJYiz2jPo6RWSGB1XyFz/1lZ4LPc="
   [mod."github.com/stretchr/testify"]
-    version = "v1.8.4"
-    hash = "sha256-MoOmRzbz9QgiJ+OOBo5h5/LbilhJfRUryvzHJmXAWjo="
+    version = "v1.9.0"
+    hash = "sha256-uUp/On+1nK+lARkTVtb5RxlW15zxtw2kaAFuIASA+J0="
   [mod."github.com/vmihailenco/msgpack/v5"]
     version = "v5.4.1"
     hash = "sha256-pDplX6xU6UpNLcFbO1pRREW5vCnSPvSU+ojAwFDv3Hk="
@@ -110,29 +110,29 @@ schema = 3
     version = "v0.3.3"
     hash = "sha256-l3pGB6IdzcPA/HLk93sSN6NM2pKPy+bVOoacR5RC2+c="
   [mod."go.etcd.io/bbolt"]
-    version = "v1.3.8"
-    hash = "sha256-ekKy8198B2GfPldHLYZnvNjID6x07dUPYKgFx84TgVs="
+    version = "v1.3.9"
+    hash = "sha256-98cKiMZcxl11laO3IiRHnhSgh7mEjl0iKlPxsSPdbww="
   [mod."golang.org/x/crypto"]
-    version = "v0.16.0"
-    hash = "sha256-DgSVOnXRK8GF01p5rLtq4qPBcglwEoOk8qhW2EGfJfA="
+    version = "v0.22.0"
+    hash = "sha256-2+u9nd32+Bi7EEv7QFc12CRTbfV7DApNv+yKIr7+lTw="
   [mod."golang.org/x/exp"]
-    version = "v0.0.0-20231006140011-7918f672742d"
-    hash = "sha256-2SO1etTQ6UCUhADR5sgvDEDLHcj77pJKCIa/8mGDbAo="
+    version = "v0.0.0-20240416160154-fe59bbe5cc7f"
+    hash = "sha256-168CD9hlLJaQ7stQk/ztlP3zgaWXUMbIHa38gAeRRs4="
   [mod."golang.org/x/mod"]
-    version = "v0.13.0"
-    hash = "sha256-qh/YmxS0auZEiKzqdn+v84qs31SpkGIJn9rqKLjdKVU="
+    version = "v0.17.0"
+    hash = "sha256-CLaPeF6uTFuRDv4oHwOQE6MCMvrzkUjWN3NuyywZjKU="
   [mod."golang.org/x/net"]
-    version = "v0.19.0"
-    hash = "sha256-3M5rKEvJx4cO/q+06cGjR5sxF5JpnUWY0+fQttrWdT4="
+    version = "v0.24.0"
+    hash = "sha256-w1c21ljta5wNIyel9CSIn/crPzwOCRofNKhqmfs4aEQ="
   [mod."golang.org/x/sync"]
-    version = "v0.5.0"
-    hash = "sha256-EAKeODSsct5HhXPmpWJfulKSCkuUu6kkDttnjyZMNcI="
+    version = "v0.7.0"
+    hash = "sha256-2ETllEu2GDWoOd/yMkOkLC2hWBpKzbVZ8LhjLu0d2A8="
   [mod."golang.org/x/sys"]
-    version = "v0.15.0"
-    hash = "sha256-n7TlABF6179RzGq3gctPDKDPRtDfnwPdjNCMm8ps2KY="
+    version = "v0.19.0"
+    hash = "sha256-cmuL31TYLJmDm/fDnI2Sn0wB88cpdOHV1+urorsJWx4="
   [mod."golang.org/x/tools"]
-    version = "v0.14.0"
-    hash = "sha256-BC/AesMg7LpIg0/e4a7Ab37rfyP2KaWBFrsonIp+JbE="
+    version = "v0.20.0"
+    hash = "sha256-g5T5FrNPO/cf2W1lc+/93FcFB3HftPjqI72FueD9Wt8="
   [mod."gopkg.in/warnings.v0"]
     version = "v0.1.2"
     hash = "sha256-ATVL9yEmgYbkJ1DkltDGRn/auGAjqGOfjQyBYyUo8s8="

nix/default.nix

@@ -1,8 +1,8 @@
-{inputs, ...}: {
+{...}: {
   imports = [
-    inputs.flake-root.flakeModule
     ./checks.nix
     ./devshell.nix
+    ./docs.nix
     ./nixpkgs.nix
     ./packages.nix
     ./treefmt.nix

nix/docs.nix

@@ -0,0 +1,72 @@
+_: {
+  perSystem = {
+    pkgs,
+    self',
+    ...
+  }: {
+    packages.docs = pkgs.buildNpmPackage {
+      pname = "treefmt-docs";
+      inherit (self'.packages.default) version;
+
+      src = ../docs;
+      npmDepsHash = "sha256-J9qTWueOcSBq7qRec6YdTuWI2VlVQ0q6AynDLovf6s0=";
+
+      # we have to use a custom build phase because vitepress is doing something funky with the ttty
+      buildPhase = ''
+        cat | npm run build 2>&1 | cat
+      '';
+
+      installPhase = ''
+        runHook preInstall
+        cp -rv .vitepress/dist/ $out
+        runHook postInstall
+      '';
+    };
+
+    devshells.default = {
+      packages = [
+        pkgs.nodejs
+      ];
+
+      commands = let
+        category = "docs";
+      in [
+        {
+          inherit category;
+          name = "docs:dev";
+          help = "serve docs for local development";
+          command = "cd $PRJ_ROOT/docs && npm run dev";
+        }
+        {
+          inherit category;
+          name = "docs:build";
+          help = "create a production build of docs";
+          command = "cd $PRJ_ROOT/docs && npm run build";
+        }
+        {
+          inherit category;
+          name = "docs:preview";
+          help = "preview a production build of docs";
+          command = "cd $PRJ_ROOT/docs && npm run preview";
+        }
+        {
+          inherit category;
+          name = "vhs";
+          help = "generate terminal gifs";
+
+          package = pkgs.writeShellApplication {
+            name = "gif";
+            runtimeInputs =
+              [
+                self'.packages.treefmt
+                pkgs.rsync
+                pkgs.vhs
+              ]
+              ++ (import ./formatters.nix pkgs);
+            text = ''vhs "$@"'';
+          };
+        }
+      ];
+    };
+  };
+}

nix/packages.nix

@@ -25,6 +25,7 @@
             root = ../.;
             exclude = [
               "nix"
+              "docs"
             ];
           };
 

nix/treefmt.nix

@@ -8,9 +8,9 @@
     ...
   }: {
     treefmt.config = {
-      inherit (config.flake-root) projectRootFile;
       flakeCheck = true;
       flakeFormatter = true;
+      projectRootFile = "flake.nix";
 
       package = self'.packages.default;
 

shell.nix

@@ -0,0 +1,17 @@
+# This file provides backward compatibility to nix < 2.4 clients
+{system ? builtins.currentSystem}: let
+  lock = builtins.fromJSON (builtins.readFile ./flake.lock);
+
+  inherit (lock.nodes.flake-compat.locked) owner repo rev narHash;
+
+  flake-compat = fetchTarball {
+    url = "https://github.com/${owner}/${repo}/archive/${rev}.tar.gz";
+    sha256 = narHash;
+  };
+
+  flake = import flake-compat {
+    inherit system;
+    src = ./.;
+  };
+in
+  flake.shellNix