release: version 0.5.0

chore: wow shiny new cargo-dist CI
find: Implement -newerXY (#342 )
2026-06-10 15:48:30 -07:00 · 2024-04-04 00:17:25 +02:00 · 2024-04-04 00:08:20 +02:00 · 2024-04-03 18:56:58 +02:00 · 2024-04-03 17:57:10 +02:00 · 2024-04-03 17:50:13 +02:00
54 changed files with 2659 additions and 954 deletions
@@ -1,23 +0,0 @@
-os: Visual Studio 2015
-
-version: "{build}"
-
-environment:
-  matrix:
-    - channel: stable
-      target: x86_64-pc-windows-msvc
-    - channel: nightly
-      target: x86_64-pc-windows-msvc
-
-install:
-  - appveyor DownloadFile https://win.rustup.rs/ -FileName rustup-init.exe
-  - rustup-init -yv --default-toolchain %channel% --default-host %target%
-  - set PATH=%PATH%;%USERPROFILE%\.cargo\bin
-  - rustc -vV && cargo -vV
-
-build_script:
-  - cargo build --verbose
-
-test_script:
-  - cargo test --verbose
-
@@ -10,7 +10,7 @@ jobs:
      matrix:
        os: [ubuntu-latest, macOS-latest, windows-latest]
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - name: Install `rust` toolchain
        run: |
          ## Install `rust` toolchain
@@ -18,7 +18,7 @@ jobs:
          rustup default stable

      # For bindgen: https://github.com/rust-lang/rust-bindgen/issues/1797
-      - uses: KyleMayes/install-llvm-action@v1
+      - uses: KyleMayes/install-llvm-action@v2
        if: matrix.os == 'windows-latest'
        with:
          version: "11.0"
@@ -28,7 +28,7 @@ jobs:

      - name: Check
        run: |
-          cargo check
+          cargo check --all --all-features

  test:
    name: cargo test
@@ -37,7 +37,7 @@ jobs:
      matrix:
        os: [ubuntu-latest, macOS-latest, windows-latest]
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - name: Install `rust` toolchain
        run: |
          ## Install `rust` toolchain
@@ -45,7 +45,7 @@ jobs:
          rustup default stable

      # For bindgen: https://github.com/rust-lang/rust-bindgen/issues/1797
-      - uses: KyleMayes/install-llvm-action@v1
+      - uses: KyleMayes/install-llvm-action@v2
        if: matrix.os == 'windows-latest'
        with:
          version: "11.0"
@@ -61,7 +61,7 @@ jobs:
    name: cargo fmt --all -- --check
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - name: Install `rust` toolchain
        run: |
          ## Install `rust` toolchain
@@ -77,7 +77,7 @@ jobs:
    name: cargo clippy -- -D warnings
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - name: Install `rust` toolchain
        run: |
          ## Install `rust` toolchain
@@ -101,7 +101,7 @@ jobs:
          - "--all-features"
    steps:
      - name: Checkout source code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4

      - name: Install `rust` toolchain
        run: |
@@ -138,15 +138,16 @@ jobs:
              --service-name "GitHub Actions" \
              --service-number ${{ github.run_id }}
      - name: Upload coverage as artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
        with:
          name: lcov.info
          # path: ${{ steps.grcov.outputs.report }}
          path: lcov.info

      - name: Upload coverage to codecov.io
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
          # file: ${{ steps.grcov.outputs.report }}
          file: lcov.info
          fail_ci_if_error: true
@@ -8,11 +8,11 @@ jobs:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout findutils
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
      with:
        path: findutils
    - name: Checkout GNU findutils
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
      with:
        repository: gnu-mirror-unofficial/findutils
        path: findutils.gnu
@@ -38,19 +38,21 @@ jobs:
    - name: Extract testing info
      shell: bash
      run: |
-    - uses: actions/upload-artifact@v3
+    - name: Upload gnu-test-report
+      uses: actions/upload-artifact@v4
      with:
        name: gnu-test-report
        path: |
          findutils.gnu/find/testsuite/*.log
          findutils.gnu/xargs/testsuite/*.log
          findutils.gnu/tests/**/*.log
-    - uses: actions/upload-artifact@v3
+    - name: Upload gnu-result
+      uses: actions/upload-artifact@v4
      with:
        name: gnu-result
        path: gnu-result.json
    - name: Download the result
-      uses: dawidd6/action-download-artifact@v2
+      uses: dawidd6/action-download-artifact@v3
      with:
        workflow: compat.yml
        workflow_conclusion: completed
@@ -59,7 +61,7 @@ jobs:
        branch: main
        path: dl
    - name: Download the log
-      uses: dawidd6/action-download-artifact@v2
+      uses: dawidd6/action-download-artifact@v3
      with:
        workflow: compat.yml
        workflow_conclusion: completed
@@ -82,15 +84,15 @@ jobs:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout findutils
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
      with:
        path: findutils
    - name: Checkout BFS
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
      with:
        repository: tavianator/bfs
        path: bfs
-        ref: '2.6.2'
+        ref: '3.1.3'
    - name: Install `rust` toolchain
      run: |
        ## Install `rust` toolchain
@@ -108,16 +110,18 @@ jobs:
      run: |
        cd findutils
        bash util/build-bfs.sh ||:
-    - uses: actions/upload-artifact@v3
+    - name: Upload bfs-test-report
+      uses: actions/upload-artifact@v4
      with:
        name: bfs-test-report
        path: bfs/tests.log
-    - uses: actions/upload-artifact@v3
+    - name: Upload bfs-result
+      uses: actions/upload-artifact@v4
      with:
        name: bfs-result
        path: bfs-result.json
    - name: Download the result
-      uses: dawidd6/action-download-artifact@v2
+      uses: dawidd6/action-download-artifact@v3
      with:
        workflow: compat.yml
        workflow_conclusion: completed
@@ -126,7 +130,7 @@ jobs:
        branch: main
        path: dl
    - name: Download the log
-      uses: dawidd6/action-download-artifact@v2
+      uses: dawidd6/action-download-artifact@v3
      with:
        workflow: compat.yml
        workflow_conclusion: completed
@@ -0,0 +1,266 @@
+# Copyright 2022-2023, axodotdev
+# SPDX-License-Identifier: MIT or Apache-2.0
+#
+# CI that:
+#
+# * checks for a Git Tag that looks like a release
+# * builds artifacts with cargo-dist (archives, installers, hashes)
+# * uploads those artifacts to temporary workflow zip
+# * on success, uploads the artifacts to a Github Release
+#
+# Note that the Github Release will be created with a generated
+# title/body based on your changelogs.
+
+name: Release
+
+permissions:
+  contents: write
+
+# This task will run whenever you push a git tag that looks like a version
+# like "1.0.0", "v0.1.0-prerelease.1", "my-app/0.1.0", "releases/v1.0.0", etc.
+# Various formats will be parsed into a VERSION and an optional PACKAGE_NAME, where
+# PACKAGE_NAME must be the name of a Cargo package in your workspace, and VERSION
+# must be a Cargo-style SemVer Version (must have at least major.minor.patch).
+#
+# If PACKAGE_NAME is specified, then the announcement will be for that
+# package (erroring out if it doesn't have the given version or isn't cargo-dist-able).
+#
+# If PACKAGE_NAME isn't specified, then the announcement will be for all
+# (cargo-dist-able) packages in the workspace with that version (this mode is
+# intended for workspaces with only one dist-able package, or with all dist-able
+# packages versioned/released in lockstep).
+#
+# If you push multiple tags at once, separate instances of this workflow will
+# spin up, creating an independent announcement for each one. However Github
+# will hard limit this to 3 tags per commit, as it will assume more tags is a
+# mistake.
+#
+# If there's a prerelease-style suffix to the version, then the release(s)
+# will be marked as a prerelease.
+on:
+  push:
+    tags:
+      - '**[0-9]+.[0-9]+.[0-9]+*'
+  pull_request:
+
+jobs:
+  # Run 'cargo dist plan' (or host) to determine what tasks we need to do
+  plan:
+    runs-on: ubuntu-latest
+    outputs:
+      val: ${{ steps.plan.outputs.manifest }}
+      tag: ${{ !github.event.pull_request && github.ref_name || '' }}
+      tag-flag: ${{ !github.event.pull_request && format('--tag={0}', github.ref_name) || '' }}
+      publishing: ${{ !github.event.pull_request }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install cargo-dist
+        # we specify bash to get pipefail; it guards against the `curl` command
+        # failing. otherwise `sh` won't catch that `curl` returned non-0
+        shell: bash
+        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.12.0/cargo-dist-installer.sh | sh"
+      # sure would be cool if github gave us proper conditionals...
+      # so here's a doubly-nested ternary-via-truthiness to try to provide the best possible
+      # functionality based on whether this is a pull_request, and whether it's from a fork.
+      # (PRs run on the *source* but secrets are usually on the *target* -- that's *good*
+      # but also really annoying to build CI around when it needs secrets to work right.)
+      - id: plan
+        run: |
+          cargo dist ${{ (!github.event.pull_request && format('host --steps=create --tag={0}', github.ref_name)) || 'plan' }} --output-format=json > plan-dist-manifest.json
+          echo "cargo dist ran successfully"
+          cat plan-dist-manifest.json
+          echo "manifest=$(jq -c "." plan-dist-manifest.json)" >> "$GITHUB_OUTPUT"
+      - name: "Upload dist-manifest.json"
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifacts-plan-dist-manifest
+          path: plan-dist-manifest.json
+
+  # Build and packages all the platform-specific things
+  build-local-artifacts:
+    name: build-local-artifacts (${{ join(matrix.targets, ', ') }})
+    # Let the initial task tell us to not run (currently very blunt)
+    needs:
+      - plan
+    if: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix.include != null && (needs.plan.outputs.publishing == 'true' || fromJson(needs.plan.outputs.val).ci.github.pr_run_mode == 'upload') }}
+    strategy:
+      fail-fast: false
+      # Target platforms/runners are computed by cargo-dist in create-release.
+      # Each member of the matrix has the following arguments:
+      #
+      # - runner: the github runner
+      # - dist-args: cli flags to pass to cargo dist
+      # - install-dist: expression to run to install cargo-dist on the runner
+      #
+      # Typically there will be:
+      # - 1 "global" task that builds universal installers
+      # - N "local" tasks that build each platform's binaries and platform-specific installers
+      matrix: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix }}
+    runs-on: ${{ matrix.runner }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      BUILD_MANIFEST_NAME: target/distrib/${{ join(matrix.targets, '-') }}-dist-manifest.json
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: swatinem/rust-cache@v2
+      - name: Install cargo-dist
+        run: ${{ matrix.install_dist }}
+      # Get the dist-manifest
+      - name: Fetch local artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      - name: Install dependencies
+        run: |
+          ${{ matrix.packages_install }}
+      - name: Build artifacts
+        run: |
+          # Actually do builds and make zips and whatnot
+          cargo dist build ${{ needs.plan.outputs.tag-flag }} --print=linkage --output-format=json ${{ matrix.dist_args }} > dist-manifest.json
+          echo "cargo dist ran successfully"
+      - id: cargo-dist
+        name: Post-build
+        # We force bash here just because github makes it really hard to get values up
+        # to "real" actions without writing to env-vars, and writing to env-vars has
+        # inconsistent syntax between shell and powershell.
+        shell: bash
+        run: |
+          # Parse out what we just built and upload it to scratch storage
+          echo "paths<<EOF" >> "$GITHUB_OUTPUT"
+          jq --raw-output ".artifacts[]?.path | select( . != null )" dist-manifest.json >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+          cp dist-manifest.json "$BUILD_MANIFEST_NAME"
+      - name: "Upload artifacts"
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifacts-build-local-${{ join(matrix.targets, '_') }}
+          path: |
+            ${{ steps.cargo-dist.outputs.paths }}
+            ${{ env.BUILD_MANIFEST_NAME }}
+
+  # Build and package all the platform-agnostic(ish) things
+  build-global-artifacts:
+    needs:
+      - plan
+      - build-local-artifacts
+    runs-on: "ubuntu-20.04"
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      BUILD_MANIFEST_NAME: target/distrib/global-dist-manifest.json
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install cargo-dist
+        shell: bash
+        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.12.0/cargo-dist-installer.sh | sh"
+      # Get all the local artifacts for the global tasks to use (for e.g. checksums)
+      - name: Fetch local artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      - id: cargo-dist
+        shell: bash
+        run: |
+          cargo dist build ${{ needs.plan.outputs.tag-flag }} --output-format=json "--artifacts=global" > dist-manifest.json
+          echo "cargo dist ran successfully"
+
+          # Parse out what we just built and upload it to scratch storage
+          echo "paths<<EOF" >> "$GITHUB_OUTPUT"
+          jq --raw-output ".artifacts[]?.path | select( . != null )" dist-manifest.json >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+          cp dist-manifest.json "$BUILD_MANIFEST_NAME"
+      - name: "Upload artifacts"
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifacts-build-global
+          path: |
+            ${{ steps.cargo-dist.outputs.paths }}
+            ${{ env.BUILD_MANIFEST_NAME }}
+  # Determines if we should publish/announce
+  host:
+    needs:
+      - plan
+      - build-local-artifacts
+      - build-global-artifacts
+    # Only run if we're "publishing", and only if local and global didn't fail (skipped is fine)
+    if: ${{ always() && needs.plan.outputs.publishing == 'true' && (needs.build-global-artifacts.result == 'skipped' || needs.build-global-artifacts.result == 'success') && (needs.build-local-artifacts.result == 'skipped' || needs.build-local-artifacts.result == 'success') }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    runs-on: "ubuntu-20.04"
+    outputs:
+      val: ${{ steps.host.outputs.manifest }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install cargo-dist
+        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.12.0/cargo-dist-installer.sh | sh"
+      # Fetch artifacts from scratch-storage
+      - name: Fetch artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      # This is a harmless no-op for Github Releases, hosting for that happens in "announce"
+      - id: host
+        shell: bash
+        run: |
+          cargo dist host ${{ needs.plan.outputs.tag-flag }} --steps=upload --steps=release --output-format=json > dist-manifest.json
+          echo "artifacts uploaded and released successfully"
+          cat dist-manifest.json
+          echo "manifest=$(jq -c "." dist-manifest.json)" >> "$GITHUB_OUTPUT"
+      - name: "Upload dist-manifest.json"
+        uses: actions/upload-artifact@v4
+        with:
+          # Overwrite the previous copy
+          name: artifacts-dist-manifest
+          path: dist-manifest.json
+
+  # Create a Github Release while uploading all files to it
+  announce:
+    needs:
+      - plan
+      - host
+    # use "always() && ..." to allow us to wait for all publish jobs while
+    # still allowing individual publish jobs to skip themselves (for prereleases).
+    # "host" however must run to completion, no skipping allowed!
+    if: ${{ always() && needs.host.result == 'success' }}
+    runs-on: "ubuntu-20.04"
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: "Download Github Artifacts"
+        uses: actions/download-artifact@v4
+        with:
+          pattern: artifacts-*
+          path: artifacts
+          merge-multiple: true
+      - name: Cleanup
+        run: |
+          # Remove the granular manifests
+          rm -f artifacts/*-dist-manifest.json
+      - name: Create Github Release
+        uses: ncipollo/release-action@v1
+        with:
+          tag: ${{ needs.plan.outputs.tag }}
+          name: ${{ fromJson(needs.host.outputs.val).announcement_title }}
+          body: ${{ fromJson(needs.host.outputs.val).announcement_github_body }}
+          prerelease: ${{ fromJson(needs.host.outputs.val).announcement_is_prerelease }}
+          artifacts: "artifacts/*"
@@ -4,3 +4,4 @@ target
 .cargo
 .settings
 test_data/links/link-*
+/public/
@@ -0,0 +1,17 @@
+repos:
+-   repo: local
+    hooks:
+    -   id: rust-linting
+        name: Rust linting
+        description: Run cargo fmt on files included in the commit.
+        entry: cargo +nightly fmt --
+        pass_filenames: true
+        types: [file, rust]
+        language: system
+    -   id: rust-clippy
+        name: Rust clippy
+        description: Run cargo clippy on files included in the commit.
+        entry: cargo +nightly clippy --workspace --all-targets --all-features --
+        pass_filenames: false
+        types: [file, rust]
+        language: system
@@ -1,33 +0,0 @@
-language: rust
-
-sudo: false
-os:
-  - linux
-  - osx
-rust:
-  - stable
-  - nightly
-
-matrix:
-  fast_finish: true
-
-branches:
-  only:
-    - master
-
-cache: cargo
-
-before_cache: |
-  if [[ "$TRAVIS_RUST_VERSION" = nightly ]]; then
-    RUSTFLAGS="--cfg procmacro2_semver_exempt" cargo install cargo-tarpaulin -f
-  fi
-
-script:
-  - cargo build --verbose
-  - cargo test --verbose
-
-after_script: |
-  if [[ "$TRAVIS_OS_NAME" = linux && "$TRAVIS_RUST_VERSION" = nightly ]]; then
-    cargo tarpaulin --out Xml
-    bash <(curl -s https://codecov.io/bash)
-  fi
@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socioeconomic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+sylvestre@debian.org.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.
@@ -0,0 +1,264 @@
+<!-- spell-checker:ignore reimplementing toybox RUNTEST CARGOFLAGS nextest embeddable Rustonomicon rustdoc's -->
+
+# Contributing to findutils
+
+Hi! Welcome to uutils/findutils!
+
+Thanks for wanting to contribute to this project! This document explains
+everything you need to know to contribute. Before you start make sure to also
+check out these documents:
+
+- Our community's [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
+- [DEVELOPMENT.md](./DEVELOPMENT.md) for setting up your development
+  environment.
+
+Now follows a very important warning:
+
+> [!WARNING]
+> uutils is original code and cannot contain any code from GNU or
+> other implementations. This means that **we cannot accept any changes based on
+> the GNU source code**. To make sure that cannot happen, **you cannot link to
+> the GNU source code** either. It is however possible to look at other implementations
+> under a BSD or MIT license like [Apple's implementation](https://opensource.apple.com/source/file_cmds/)
+> or [OpenBSD](https://github.com/openbsd/src/tree/master/bin).
+
+Finally, feel free to join our [Discord](https://discord.gg/wQVJbvJ)!
+
+<!-- TODO: Getting Oriented -->
+
+## Design Goals
+
+We have the following goals with our development:
+
+- **Compatible**: The utilities should be a drop-in replacement for the GNU
+  coreutils.
+- **Cross-platform**: All utilities should run on as many of the supported
+  platforms as possible.
+- **Reliable**: The utilities should never unexpectedly fail.
+- **Performant**: Our utilities should be written in fast idiomatic Rust. We aim
+  to match or exceed the performance of the GNU utilities.
+- **Well-tested**: We should have a lot of tests to be able to guarantee
+  reliability and compatibility.
+
+## How to Help
+
+There are several ways to help and writing code is just one of them. Reporting
+issues and writing documentation are just as important as writing code.
+
+### Reporting Issues
+
+We can't fix bugs we don't know about, so good issues are super helpful! Here
+are some tips for writing good issues:
+
+- If you find a bug, make sure it's still a problem on the `main` branch.
+- Search through the existing issues to see whether it has already been
+  reported.
+- Make sure to include all relevant information, such as:
+  - Which version of uutils did you check?
+  - Which version of GNU coreutils are you comparing with?
+  - What platform are you on?
+- Provide a way to reliably reproduce the issue.
+- Be as specific as possible!
+
+### Writing Documentation
+
+There's never enough documentation. If you come across any documentation that
+could be improved, feel free to submit a PR for it!
+
+### Writing Code
+
+If you want to submit a PR, make sure that you've discussed the solution with
+the maintainers beforehand. We want to avoid situations where you put a lot of
+work into a fix that we can't merge! If there's no issue for what you're trying
+to fix yet, make one _before_ you start working on the PR.
+
+Generally, we try to follow what GNU is doing in terms of options and behavior.
+It is recommended to look at the GNU findtils manual
+([on the web](https://www.gnu.org/software/findutils/manual/html_node/index.html),
+or locally using `info <utility>`). It is more in depth than the man pages and
+provides a good description of available features and their implementation
+details. But remember, you cannot look at the GNU source code!
+
+Also remember that we can only merge PRs which pass our test suite, follow
+rustfmt, and do not have any warnings from clippy. See
+[DEVELOPMENT.md](./DEVELOPMENT.md) for more information. Be sure to also read
+about our [Rust style](#our-rust-style).
+
+## Our Rust Style
+
+We want uutils to be written in idiomatic Rust, so here are some guidelines to
+follow. Some of these are aspirational, meaning that we don't do them correctly
+everywhere in the code. If you find violations of the advice below, feel free to
+submit a patch!
+
+### Don't `panic!`
+
+The coreutils should be very reliable. This means that we should never `panic!`.
+Therefore, you should avoid using `.unwrap()` and `panic!`. Sometimes the use of
+`unreachable!` can be justified with a comment explaining why that code is
+unreachable.
+
+### Don't `exit`
+
+We want uutils to be embeddable in other programs. This means that no function
+in uutils should exit the program. Doing so would also lead to code with more
+confusing control flow. Avoid therefore `std::process::exit` and similar
+functions which exit the program early.
+
+### `unsafe`
+
+uutils cannot be entirely safe, because we have to call out to `libc` and do
+syscalls. However, we still want to limit our use of `unsafe`. We generally only
+accept `unsafe` for FFI, with very few exceptions. Note that performance is very
+rarely a valid argument for using `unsafe`.
+
+If you still need to write code with `unsafe`, make sure to read the
+[Rustonomicon](https://doc.rust-lang.org/nomicon/intro.html) and annotate the
+calls with `// SAFETY:` comments explaining why the use of `unsafe` is sound.
+
+### Macros
+
+Macros can be a great tool, but they are also usually hard to understand. They
+should be used sparingly. Make sure to explore simpler options before you reach
+for a solution involving macros.
+
+### `str`, `OsStr` & `Path`
+
+Rust has many string-like types, and sometimes it's hard to choose the right
+one. It's tempting to use `str` (and `String`) for everything, but that is not
+always the right choice for uutils, because we need to support invalid UTF-8,
+just like the GNU coreutils. For example, paths on Linux might not be valid
+UTF-8! Whenever we are dealing with paths, we should therefore stick with
+`OsStr` and `Path`. Make sure that you only convert to `str`/`String` if you
+know that something is always valid UTF-8. If you need more operations on
+`OsStr`, you can use the [`bstr`](https://docs.rs/bstr/latest/bstr/) crate.
+
+### Doc-comments
+
+We use rustdoc for our documentation, so it's best to follow
+[rustdoc's guidelines](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components).
+Make sure that your documentation is not just repeating the name of the
+function, but actually giving more useful information. Rustdoc recommends the
+following structure:
+
+```
+[short sentence explaining what it is]
+
+[more detailed explanation]
+
+[at least one code example that users can copy/paste to try it]
+
+[even more advanced explanations if necessary]
+```
+
+### Other comments
+
+Comments should be written to _explain_ the code, not to _describe_ the code.
+Try to focus on explaining _why_ the code is the way it is. If you feel like you
+have to describe the code, that's usually a sign that you could improve the
+naming of variables and functions.
+
+If you edit a piece of code, make sure to update any comments that need to
+change as a result. The only thing worse than having no comments is having
+outdated comments!
+
+## Git Etiquette
+
+To ensure easy collaboration, we have guidelines for using Git and GitHub.
+
+### Commits
+
+- Make small and atomic commits.
+- Keep a clean history of commits.
+- Write informative commit messages.
+- Annotate your commit message with the component you're editing. For example:
+  `cp: do not overwrite on with -i` or `uucore: add support for FreeBSD`.
+- Do not unnecessarily move items around in the code. This makes the changes
+  much harder to review. If you do need to move things around, do that in a
+  separate commit.
+
+### Commit messages
+
+You can read this section in the Git book to learn how to write good commit
+messages: https://git-scm.com/book/ch5-2.html.
+
+In addition, here are a few examples for a summary line when committing to
+uutils:
+
+- commit for a single utility
+
+```
+nohup: cleanup and refactor
+```
+
+- commit for a utility's tests
+
+```
+tests/rm: test new feature
+```
+
+Beyond changes to an individual utility or its tests, other summary lines for
+non-utility modules include:
+
+```
+README: add help
+uucore: add new modules
+uutils: add new utility
+gitignore: add temporary files
+```
+
+### PRs
+
+- Make the titles of PRs descriptive.
+  - This means describing the problem you solve. For example, do not write
+    `Fix #1234`, but `ls: fix version sort order`.
+  - You can prefix the title with the utility the PR concerns.
+- Keep PRs small and self-contained. A set of small PRs is much more likely to
+  get merged quickly than one large PR.
+- Make sure the CI passes (up to intermittently failing tests).
+- You know your code best, that's why it's best if you can solve merge conflicts
+  on your branch yourself.
+  - It's up to you whether you want to use `git merge main` or
+    `git rebase main`.
+  - Feel free to ask for help with merge conflicts.
+- You do not need to ping maintainers to request a review, but it's fine to do
+  so if you don't get a response within a few days.
+
+## Platforms
+
+We take pride in supporting many operating systems and architectures. Any code
+you contribute must at least compile without warnings for all platforms in the
+CI. However, you can use `#[cfg(...)]` attributes to create platform dependent
+features.
+
+**Tip:** For Windows, Microsoft provides some images (VMWare, Hyper-V,
+VirtualBox and Parallels) for development:
+<https://developer.microsoft.com/windows/downloads/virtual-machines/>
+
+## Licensing
+
+uutils is distributed under the terms of the MIT License; see the `LICENSE` file
+for details. This is a permissive license, which allows the software to be used
+with few restrictions.
+
+Copyrights in the uutils project are retained by their contributors, and no
+copyright assignment is required to contribute.
+
+If you wish to add or change dependencies as part of a contribution to the
+project, a tool like `cargo-license` can be used to show their license details.
+The following types of license are acceptable:
+
+- MIT License
+- Dual- or tri-license with an MIT License option ("Apache-2.0 or MIT" is a
+  popular combination)
+- "MIT equivalent" license (2-clause BSD, 3-clause BSD, ISC)
+- License less restrictive than the MIT License (CC0 1.0 Universal)
+- Apache License version 2.0
+
+Licenses we will not use:
+
+- An ambiguous license, or no license
+- Strongly reciprocal licenses (GNU GPL, GNU LGPL)
+
+If you wish to add a reference but it doesn't meet these requirements, please
+raise an issue to describe the dependency.
@@ -1,31 +1,32 @@
 [package]
 name = "findutils"
-version = "0.3.0"
+version = "0.5.0"
 homepage = "https://github.com/uutils/findutils"
 repository = "https://github.com/uutils/findutils"
-edition = "2018"
+edition = "2021"
 license = "MIT"
 readme = "README.md"
 description = "Rust implementation of GNU findutils"
 authors = ["uutils developers"]

 [dependencies]
-chrono = "0.4"
-clap = "2.34"
+chrono = "0.4.37"
+clap = "4.5"
 faccess = "0.2.4"
-walkdir = "2.3"
+walkdir = "2.5"
 regex = "1.7"
-once_cell = "1.17"
-onig = "6.4"
-uucore = { version = "0.0.12", features = ["entries", "fs", "fsext", "mode"] }
+once_cell = "1.19"
+onig = { version = "6.4", default-features = false }
+uucore = { version = "0.0.25", features = ["entries", "fs", "fsext", "mode"] }

 [dev-dependencies]
 assert_cmd = "2"
 filetime = "0.2"
-nix = "0.26"
-predicates = "2"
-serial_test = "1.0"
+nix = { version = "0.28", features = ["fs"] }
+predicates = "3"
+serial_test = "3.0"
 tempfile = "3"
+pretty_assertions = "1.4.0"

 [[bin]]
 name = "find"
@@ -38,3 +39,21 @@ path = "src/xargs/main.rs"
 [[bin]]
 name = "testing-commandline"
 path = "src/testing/commandline/main.rs"
+
+# The profile that 'cargo dist' will build with
+[profile.dist]
+inherits = "release"
+lto = "thin"
+
+# Config for 'cargo dist'
+[workspace.metadata.dist]
+# The preferred cargo-dist version to use in CI (Cargo.toml SemVer syntax)
+cargo-dist-version = "0.12.0"
+# CI backends to support
+ci = ["github"]
+# The installers to generate for each app
+installers = []
+# Target platforms to build apps for (Rust target-triple syntax)
+targets = ["aarch64-apple-darwin", "x86_64-apple-darwin", "x86_64-unknown-linux-gnu", "x86_64-pc-windows-msvc"]
+# Publish jobs to run in CI
+pr-run-mode = "plan"
@@ -0,0 +1,156 @@
+<!-- spell-checker:ignore (flags) Ccodegen Coverflow Cpanic Zinstrument Zpanic reimplementing toybox RUNTEST CARGOFLAGS nextest prereq autopoint gettext texinfo automake findutils shellenv libexec gnubin toolchains gsed -->
+
+# Setting up your local development environment
+
+For contributing rules and best practices please refer to [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Before you start
+
+For this guide we assume that you already have a GitHub account and have `git` and your favorite code editor or IDE installed and configured.
+Before you start working on findutils, please follow these steps:
+
+1. Fork the [findutils repository](https://github.com/uutils/findutils) to your GitHub account.
+***Tip:*** See [this GitHub guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for more information on this step.
+2. Clone that fork to your local development environment:
+
+```shell
+git clone https://github.com/YOUR-GITHUB-ACCOUNT/findutils
+cd findutils
+```
+
+## Tools
+
+You will need the tools mentioned in this section to build and test your code changes locally.
+This section will explain how to install and configure these tools.
+We also have an extensive CI that uses these tools and will check your code before it can be merged.
+The next section [Testing](#testing) will explain how to run those checks locally to avoid waiting for the CI.
+
+### Rust toolchain
+
+[Install Rust](https://www.rust-lang.org/tools/install)
+
+If you're using rustup to install and manage your Rust toolchains, `clippy` and `rustfmt` are usually already installed. If you are using one of the alternative methods, please make sure to install them manually. See following sub-sections for their usage: [clippy](#clippy) [rustfmt](#rustfmt).
+
+***Tip*** You might also need to add 'llvm-tools' component if you are going to [generate code coverage reports locally](#code-coverage-report):
+
+```shell
+rustup component add llvm-tools-preview
+```
+
+### pre-commit hooks
+
+A configuration for `pre-commit` is provided in the repository. It allows
+automatically checking every git commit you make to ensure it compiles, and
+passes `clippy` and `rustfmt` without warnings.
+
+To use the provided hook:
+
+1. [Install `pre-commit`](https://pre-commit.com/#install)
+1. Run `pre-commit install` while in the repository directory
+
+Your git commits will then automatically be checked. If a check fails, an error
+message will explain why, and your commit will be canceled. You can then make
+the suggested changes, and run `git commit ...` again.
+
+**NOTE: On MacOS** the pre-commit hooks are currently broken. There are workarounds involving switching to unstable nightly Rust and components.
+
+### clippy
+
+```shell
+cargo clippy --all-targets --all-features
+```
+
+The `msrv` key in the clippy configuration file `clippy.toml` is used to disable
+lints pertaining to newer features by specifying the minimum supported Rust
+version (MSRV).
+
+### rustfmt
+
+```shell
+cargo fmt --all
+```
+
+### cargo-deny
+
+This project uses [cargo-deny](https://github.com/EmbarkStudios/cargo-deny/) to
+detect duplicate dependencies, checks licenses, etc. To run it locally, first
+install it and then run with:
+
+```shell
+cargo deny --all-features check all
+```
+
+### Markdown linter
+
+We use [markdownlint](https://github.com/DavidAnson/markdownlint) to lint the
+Markdown files in the repository.
+
+### Spell checker
+
+We use `cspell` as spell checker for all files in the project. If you are using
+VS Code, you can install the
+[code spell checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
+extension to enable spell checking within your editor. Otherwise, you can
+install [cspell](https://cspell.org/) separately.
+
+If you want to make the spell checker ignore a word, you can add
+
+```rust
+// spell-checker:ignore word_to_ignore
+```
+
+at the top of the file.
+
+## Testing
+
+Just like with building, we follow the standard procedure for testing using
+Cargo:
+
+```shell
+cargo test
+```
+
+## Code coverage report
+
+Code coverage report can be generated using [grcov](https://github.com/mozilla/grcov).
+
+### Using Nightly Rust
+
+To generate [gcov-based](https://github.com/mozilla/grcov#example-how-to-generate-gcda-files-for-a-rust-project) coverage report
+
+```shell
+export CARGO_INCREMENTAL=0
+export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort"
+export RUSTDOCFLAGS="-Cpanic=abort"
+cargo build <options...>
+cargo test <options...>
+grcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing --ignore build.rs --excl-br-line "^\s*((debug_)?assert(_eq|_ne)?\#\[derive\()" -o ./target/debug/coverage/
+# open target/debug/coverage/index.html in browser
+```
+
+if changes are not reflected in the report then run `cargo clean` and run the above commands.
+
+### Using Stable Rust
+
+If you are using stable version of Rust that doesn't enable code coverage instrumentation by default
+then add `-Z-Zinstrument-coverage` flag to `RUSTFLAGS` env variable specified above.
+
+## Tips for setting up on Mac
+
+### C Compiler and linker
+
+On MacOS you'll need to install C compiler & linker:
+
+```shell
+xcode-select --install
+```
+
+## Tips for setting up on Windows
+
+### MSVC build tools
+
+On Windows you'll need the MSVC build tools for Visual Studio 2013 or later.
+
+If you are using `rustup-init.exe` to install Rust toolchain, it will guide you through the process of downloading and installing these prerequisites.
+
+Otherwise please follow [this guide](https://learn.microsoft.com/en-us/windows/dev-environment/rust/setup).
@@ -1,10 +1,13 @@
 # findutils

 [![Crates.io](https://img.shields.io/crates/v/findutils.svg)](https://crates.io/crates/findutils)
+[![Discord](https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord&longCache=true&style=flat)](https://discord.gg/wQVJbvJ)
+[![License](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/uutils/findutils/blob/main/LICENSE)
 [![dependency status](https://deps.rs/repo/github/uutils/findutils/status.svg)](https://deps.rs/repo/github/uutils/findutils)
 [![codecov](https://codecov.io/gh/uutils/findutils/branch/master/graph/badge.svg)](https://codecov.io/gh/uutils/findutils)

-Rust implementation of [GNU findutils](https://www.gnu.org/software/findutils/).
+Rust implementation of [GNU findutils](https://www.gnu.org/software/findutils/): `xargs`, `find`, `locate` and `updatedb`.
+The goal is to be a full drop-in replacement of the original commands.

 ## Run the GNU testsuite on rust/findutils:

@@ -20,4 +23,15 @@ bash util/build-gnu.sh tests/misc/help-version.sh
 ![Evolution over time - GNU testsuite](https://github.com/uutils/findutils-tracking/blob/main/gnu-results.png?raw=true)
 ![Evolution over time - BFS testsuite](https://github.com/uutils/findutils-tracking/blob/main/bfs-results.png?raw=true)

+## Build/run with BFS
+
+[bfs](https://github.com/tavianator/bfs) is a variant of the UNIX find command that operates breadth-first rather than depth-first.
+
+```
+bash util/build-bfs.sh
+
+# To run a specific test:
+bash util/build-bfs.sh posix/basic
+```
+
 For more details, see https://github.com/uutils/findutils-tracking/
@@ -0,0 +1,10 @@
+[book]
+authors = ["Terts Diepraam"]
+language = "en"
+multilingual = false
+src = "src"
+title = "findutils"
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]
@@ -0,0 +1,9 @@
+# Summary
+
+[Introduction](index.md)
+* [Installation](installation.md)
+* [Build from source](build.md)
+* [Platform support](platforms.md)
+* [Contributing](contributing.md)
+* [GNU test coverage](test_coverage.md)
+* [Extensions](extensions.md)
@@ -0,0 +1,3 @@
+# Build from source
+
+TODO
@@ -0,0 +1,3 @@
+<!-- markdownlint-disable MD041 -->
+
+{{ #include ../../CONTRIBUTING.md }}
@@ -0,0 +1,3 @@
+# Extensions
+
+TODO
@@ -0,0 +1,49 @@
+<!-- markdownlint-disable MD041 -->
+
+{{#include logo.svg}}
+
+<!-- markdownlint-disable MD033 -->
+
+<style>
+    /* Make the logo a bit bigger and center */
+    #logo {
+        height: 200px;
+        width: 100%;
+    }
+
+    /* This is necessary to get the <use> tags to obey the CSS styles below */
+    g, polygon {
+        fill: inherit;
+        stroke: inherit;
+    }
+
+    /* Set the circle to the foreground color of the theme */
+    #gear circle {
+        stroke: var(--fg);
+    }
+
+    /* Set the stroke of polygons and the copies (via use) */
+    #gear polygon,
+    #gear use {
+        fill: var(--fg);
+        stroke: var(--fg);
+    }
+</style>
+
+# uutils findutils Documentation
+
+The uutils findutils project reimplements the GNU findutils in Rust. It is available for Linux, Windows, Mac
+and other platforms.
+
+uutils is licensed under the
+[MIT License](https://github.com/uutils/findutils/blob/main/LICENSE).
+
+## Useful links
+
+- [Releases](https://github.com/uutils/findutils/releases)
+- [Source Code](https://github.com/uutils/findutils)
+- [Issues](https://github.com/uutils/findutils/issues)
+- [Discord](https://discord.gg/wQVJbvJ)
+
+> Note: This manual is automatically generated from the source code and is a
+> work in progress.
@@ -0,0 +1,64 @@
+<!-- spell-checker:ignore pacman pamac nixpkgs openmandriva conda winget openembedded yocto bblayers bitbake -->
+
+# Installation
+
+This is a list of uutils packages in various distributions and package managers.
+Note that these are packaged by third-parties and the packages might contain
+patches.
+
+You can also [build findutils from source](build.md).
+
+<!-- toc -->
+
+## Cargo
+
+[![crates.io package](https://repology.org/badge/version-for-repo/crates_io/rust:findutils.svg)](https://crates.io/crates/findutils)
+
+```shell
+cargo install findutils
+```
+
+## Linux
+
+### Debian
+
+[![Debian 13 package](https://repology.org/badge/version-for-repo/debian_13/rust:findutils.svg)](https://packages.debian.org/trixie/source/rust-findutils)
+
+[![Debian Unstable package](https://repology.org/badge/version-for-repo/debian_unstable/rust:findutils.svg)](https://packages.debian.org/sid/source/rust-findutils)
+
+```shell
+apt install rust-findutils
+# To use it:
+export PATH=/usr/lib/cargo/bin/findutils:$PATH
+```
+
+### Gentoo
+
+[![Gentoo package](https://repology.org/badge/version-for-repo/gentoo/uutils-findutils.svg)](https://packages.gentoo.org/packages/sys-apps/uutils-findutils)
+
+```shell
+emerge -pv sys-apps/uutils-findutils
+```
+
+## MacOS
+
+### Homebrew
+
+[![Homebrew package](https://repology.org/badge/version-for-repo/homebrew/uutils-findutils.svg)](https://formulae.brew.sh/formula/uutils-findutils)
+
+```shell
+brew install uutils-findutils
+```
+
+
+## FreeBSD
+
+[![FreeBSD port](https://repology.org/badge/version-for-repo/freebsd/rust-findutils.svg)](https://repology.org/project/rust-findutils/versions)
+
+```sh
+pkg install rust-findutils
+```
+
+## Windows
+
+As far as we are aware, `findutils` has not been packaged for any package managers on Windows yet.
--- a/Show More
+++ b/Show More