{"id":15959254,"url":"https://github.com/chrissimpkins/recurse","last_synced_at":"2025-06-10T17:07:35.245Z","repository":{"id":36977709,"uuid":"255418293","full_name":"chrissimpkins/recurse","owner":"chrissimpkins","description":"Cross-platform recursive directory traversal file management tool","archived":false,"fork":false,"pushed_at":"2023-03-27T04:57:30.000Z","size":766,"stargazers_count":2,"open_issues_count":8,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-07T06:02:59.091Z","etag":null,"topics":["commandline","commandline-tool","directory","file","system","text"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrissimpkins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"github":"chrissimpkins"}},"created_at":"2020-04-13T19:07:12.000Z","updated_at":"2023-09-08T18:05:54.000Z","dependencies_parsed_at":"2024-01-14T00:21:04.441Z","dependency_job_id":"38467e7c-c60d-40fa-8611-0bdd31496d43","html_url":"https://github.com/chrissimpkins/recurse","commit_stats":{"total_commits":218,"total_committers":4,"mean_commits":54.5,"dds":0.4036697247706422,"last_synced_commit":"dd68515d7e1fd6773dace331c918f00ccfbcb9c0"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrissimpkins%2Frecurse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrissimpkins%2Frecurse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrissimpkins%2Frecurse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrissimpkins%2Frecurse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrissimpkins","download_url":"https://codeload.github.com/chrissimpkins/recurse/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrissimpkins%2Frecurse/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259073136,"owners_count":22801109,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["commandline","commandline-tool","directory","file","system","text"],"created_at":"2024-10-07T14:40:57.754Z","updated_at":"2025-06-10T17:07:35.218Z","avatar_url":"https://github.com/chrissimpkins.png","language":"Rust","funding_links":["https://github.com/sponsors/chrissimpkins"],"categories":[],"sub_categories":[],"readme":"# recurse\n\n## A cross-platform recursive directory traversal file management tool\n\n![Version](https://img.shields.io/github/v/release/chrissimpkins/recurse?sort=semver)\n[![GNU/Linux CI](https://github.com/chrissimpkins/recurse/workflows/GNU/Linux%20CI/badge.svg)](https://github.com/chrissimpkins/recurse/actions?query=workflow%3A%22GNU%2FLinux+CI%22)\n[![macOS CI](https://github.com/chrissimpkins/recurse/workflows/macOS%20CI/badge.svg)](https://github.com/chrissimpkins/recurse/actions?query=workflow%3A%22macOS+CI%22)\n[![Windows CI](https://github.com/chrissimpkins/recurse/workflows/Windows%20CI/badge.svg)](https://github.com/chrissimpkins/recurse/actions?query=workflow%3A%22Windows+CI%22)\n[![codecov](https://codecov.io/gh/chrissimpkins/recurse/branch/master/graph/badge.svg)](https://codecov.io/gh/chrissimpkins/recurse)\n\n## About\n\nThe `recurse` executable is a cross-platform command line tool for file management with *default* recursive directory traversal and regular expression pattern matching support.  It is built in Rust and tested against the stable, beta, and nightly Rust toolchains on GNU/Linux, macOS, and Windows platforms.\n\nFeatures are available through sub-commands of the `recurse` executable. Support currently includes:\n\n- `recurse contains`: identify valid UTF-8 encoded text file paths with contents that match regular expression patterns\n- `recurse find`: identify regular expression pattern match line and byte offsets in valid UTF-8 encoded text files\n- `recurse walk`: recursive directory traversal file listings\n\nThe following features are in development:\n\n- [*coming in v0.4.0*] `recurse replace`: replace strings in text files that match regular expression patterns (issue #6)\n- [*coming in v0.5.0*] add optional canonical Unicode normalization support for text input to sub-commands that support text matching (issue #8)\n\nSee the [Usage section](#usage) below for additional details.\n\nSee the [FAQ.md](FAQ.md) for answers to frequently asked questions.\n\n## Installation\n\n### With `cargo` from crates.io\n\nUse `cargo` to install the `recurse` executable from crates.io:\n\n```\n$ cargo install recurse\n```\n\n### With `cargo` from the master branch of the repository\n\nClone the git repository, compile, and install the executable with the following commands:\n\n```\n$ git clone https://github.com/chrissimpkins/recurse.git\n$ cd recurse\n$ cargo install --path .\n```\n\n## Usage\n\nView the help documentation for any sub-command on the command line with the syntax:\n\n```\n$ recurse [SUB-COMMAND] --help\n```\n\nThe help menu displays available options and required arguments.\n\nRecursive directory traversal is the default behavior across all sub-commands. \n\nThe regular expression syntax support is documented [here](https://docs.rs/regex/#syntax).\n\n### [`contains` sub-command]()\n\n#### `contains` Syntax\n\n```\n$ recurse contains [OPTIONS] [REGEX] [START PATH]\n```\n\nThe contains sub-command's default behavior is to list all text file paths with one or more valid UTF-8 encoded Unicode scalar values that match a regular expression pattern `[REGEX]`.  Hidden paths are excluded by default and are defined as a directory or file path that begins with a period (e.g., `.hidden` directory or `.hidden.txt` file).  All directory and file paths below a hidden directory are considered hidden.  Directory traversal proceeds to the max depth below the user-specified start path `[START PATH]`.\n\n#### `contains` Options\n\nCommand line options modify the default behavior. Supported options for the `contains` sub-command are:\n\n- `-a | --all`: Include hidden file and directory paths\n- `-e | --ext [EXTENSION]`: Filter on paths that include an EXTENSION string.  Enter an EXTENSION string argument to define the extension filter.  The EXTENSION argument may be defined with or without a period character (e.g., `txt` or `.txt`)\n- `--maxdepth [DEPTH]`: maximum depth to extend traversal of file system sub-directory structure.  Enter an integer value for DEPTH to limit the directory traversal.\n- `--mindepth [DEPTH]`: minimum depth to begin traversal of file system sub-directory structure.  Enter an integer value for DEPTH to limit the directory traversal.\n- `--symlinks`: Follow symbolic links\n\n### [`find` sub-command]()\n\n#### `find` Syntax\n\n```\n$ recurse find [OPTIONS] [REGEX] [START PATH]\n```\n\nThe `find` sub-command's default behavior is to list all lines in text files with valid UTF-8 encoded Unicode scalar values that match a regular expression pattern `[REGEX]`.  The report includes the following data for each line in a file with a match:\n\n```\n[FILEPATH] [LINE NUMBER]:[START BYTE OFFSET INDEX]-[END BYTE OFFSET INDEX] [ MATCHED STRING ]\n```\n\nHere is an example of a match result on the regular expression pattern `[Rr]ecurse` in this repository:\n\n```\n./src/command/find.rs 12:11-18 [ Recurse ]\n```\n\nNote that the byte offsets will not map 1:1 to \"character offsets\" when multi-byte encoded characters are in or before the matched string in a given line of text.\n\nHidden paths are excluded by default and are defined as a directory or file path that begins with a period (e.g., `.hidden` directory or `.hiddent.txt` file).  All directory and file paths below a hidden directory are considered hidden.  Directory traversal proceeds to the max depth below the user-specified start path `[START PATH]`.\n\n#### `find` Options\n\nCommand line options modify the default behavior. Supported options for the `find` sub-command are:\n\n- `-a | --all`: Include hidden file and directory paths\n- `-e | --ext [EXTENSION]`: Filter on paths that include an EXTENSION string.  Enter an EXTENSION string argument to define the extension filter.  The EXTENSION argument may be defined with or without a period character (e.g., `txt` or `.txt`)\n- `--maxdepth [DEPTH]`: maximum depth to extend traversal of file system sub-directory structure.  Enter an integer value for DEPTH to limit the directory traversal.\n- `--mindepth [DEPTH]`: minimum depth to begin traversal of file system sub-directory structure.  Enter an integer value for DEPTH to limit the directory traversal.\n- `--symlinks`: Follow symbolic links\n\n### [`walk` sub-command]()\n\n#### `walk` Syntax\n\n```\n$ recurse walk [OPTIONS] [START PATH]\n```\n\nThe walk sub-command's default behavior is to list all file paths that are not hidden in the standard output stream.  Hidden paths are defined as a directory or file that begins with a period (e.g., `.hidden` directory or `.hidden.txt` file).  All directory and file paths below a hidden directory path are considered hidden.  Directory traversal proceeds to the max depth below the user-specified start path `[START PATH]`.\n\n#### `walk` Options\n\nCommand line options modify the default behavior. Supported options for the `walk` sub-command are:\n\n- `-a | --all`: Include hidden file and directory paths\n- `-d | --dir`: Filter on directory paths only, do not list file paths\n- `-e | --ext [EXTENSION]`: Filter on paths that include an EXTENSION string.  Enter an EXTENSION string argument to define the extension filter.  The EXTENSION argument may be defined with or without a period character (e.g., `txt` or `.txt`)\n- `--maxdepth [DEPTH]`: maximum depth to extend traversal of file system sub-directory structure.  Enter an integer value for DEPTH to limit the directory traversal.\n- `--mindepth [DEPTH]`: minimum depth to begin traversal of file system sub-directory structure.  Enter an integer value for DEPTH to limit the directory traversal.\n- `--symlinks`: Follow symbolic links\n\n## Contributing\n\nPlease submit new issues on [the GitHub issue tracker](https://github.com/chrissimpkins/recurse/issues).\n\nContributions under the Apache License, v2.0 are welcomed.  Please open a pull request with your proposal for changes.  \n\n## License\n\nApache License, v2.0.  See [LICENSE.md](LICENSE.md) for the full text of the license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrissimpkins%2Frecurse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrissimpkins%2Frecurse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrissimpkins%2Frecurse/lists"}