Search

Searches the filesystem on the remote machine.

distant fs search 'hello.*'

Flags

• --target <TARGET>: indicates whether to search paths or the contents of files. --target path will search paths whereas --target contents will search the contents of files. By default, this searches the contents of files.
• --include <REGEX>: specifies additional regex to use to limit which paths are searched to only those that match the given regex.
• --exclude <REGEX>: specifies additional regex to use to limit which paths are searched to only those that do not match the given regex.
• --upward: indicates that we should search upward versus recursively downward. What this does is search the target and then moves up to the parent directory and searches its immediate children. This continues until either a match is found or the depth is reached.
• --follow-symbolic-links: indicates that symbolic links will be traversed while searching. By default, they are not traversed.
• --limit <N>: indicates to stop searching after N results are found. By default, there is no limit when searching.
• --max-depth <MAX>: indicates the maximum depth to search (recursively or upward) with 0 meaning only the current file (or directory when upward).
• --pagination <N>: indicates how many results to match during a search before printing them. By default, a search will wait until finished before printing results.
• --ignore-hidden: indicates that hidden files will be skipped when searching. On Unix systems, hidden files and folders are denoted with a dot in front of their name such as .hidden.txt.
• --use-ignore-files: will read .ignore files that are used by ripgrep and The Silver Searcher to determine which files and directories ignore.
• --use-parent-ignore-files: will read .ignore files from parent directories that are used by ripgrep and The Silver Searcher to determine which files and directories to ignore.
• --use-git-ignore-files: will read .gitignore files to determine which files and directories to ignore.
• --use-global-git-ignore-files: will read global .gitignore files to determine which files and directories to ignore.
• --use-git-exclude-files: will read .git/info/exclude files to determine which files and directories to ignore.

Examples

Explicit Path

Typically, searching is best limited to a specific directory, such as a specific project on a remote machine:

distant fs search 'hello.*' /path/to/project

Behave like ripgrep

Ripgrep provides a lot of exclusions out of the box when searching to avoid looking at unnecessary files. Distant does not enable any of those restrictions by default, so to match ripgrep, you should provide the following flags:

distant fs search \
    --ignore-hidden \
    --use-ignore-files \
    --use-parent-ignore-files \
    --use-git-ignore-files \
    --use-global-git-ignore-files \
    --use-git-exclude-files \
    'hello.*'

Looking for a match upward

When trying to determine if you are in a project directory, a common practice is to look for a specific file such as a Cargo.toml. An easy way to do this is to use --upward alongside --limit 1 with a path target to find the file if it exists:

distant fs search \
    --upward \
    --limit 1 \
    --target path \
    'Cargo.toml'

Notes

• Relative paths resolve to the current working directory of the server.
• If no explicit paths are provided, this will search the current working directory.

distant fs search --help

Search files & directories on the remote machine

Usage: distant fs search [OPTIONS] <pattern> [PATHS]...

Arguments:
  <pattern>
          Condition to meet to be considered a match

  [PATHS]...
          Paths in which to perform the query

          [default: .]

Options:
      --cache <CACHE>
          Location to store cached data

          [default: /home/runner/.cache/distant/cache.toml]

      --log-level <LOG_LEVEL>
          Log level to use throughout the application

          [possible values: off, error, warn, info, debug, trace]

      --connection <CONNECTION>
          Specify a connection being managed

      --log-file <LOG_FILE>
          Path to file to use for logging

      --config <CONFIG_PATH>
          Configuration file to load instead of the default paths

      --unix-socket <UNIX_SOCKET>
          Override the path to the Unix socket used by the manager (unix-only)

      --windows-pipe <WINDOWS_PIPE>
          Override the name of the local named Windows pipe used by the manager (windows-only)

      --target <TARGET>
          Kind of data to examine using condition

          [default: contents]

          Possible values:
          - path:     Checks path of file, directory, or symlink
          - contents: Checks contents of files

      --include <INCLUDE>
          Regex to use to filter paths being searched to only those that match the include condition

      --exclude <EXCLUDE>
          Regex to use to filter paths being searched to only those that do not match the exclude condition

      --upward
          Search upward through parent directories rather than the traditional downward search that recurses through all children directories.

          Note that this will use maximum depth to apply to the reverse direction, and will only look through each ancestor directory's immediate entries. In other words, this will not result in recursing through sibling directories.

          An upward search will ALWAYS search the contents of a directory, so this means providing a path to a directory will search its entries EVEN if the max_depth is 0.

      --follow-symbolic-links
          Search should follow symbolic links

      --limit <LIMIT>
          Maximum results to return before stopping the query

      --max-depth <MAX_DEPTH>
          Maximum depth (directories) to search

          The smallest depth is 0 and always corresponds to the path given to the new function on this type. Its direct descendents have depth 1, and their descendents have depth 2, and so on.

          Note that this will not simply filter the entries of the iterator, but it will actually avoid descending into directories when the depth is exceeded.

      --pagination <PAGINATION>
          Amount of results to batch before sending back excluding final submission that will always include the remaining results even if less than pagination request

      --ignore-hidden
          If true, will skip searching hidden files

      --use-ignore-files
          If true, will read `.ignore` files that are used by `ripgrep` and `The Silver Searcher` to determine which files and directories to not search

      --use-parent-ignore-files
          If true, will read `.ignore` files from parent directories that are used by `ripgrep` and `The Silver Searcher` to determine which files and directories to not search

      --use-git-ignore-files
          If true, will read `.gitignore` files to determine which files and directories to not search

      --use-global-git-ignore-files
          If true, will read global `.gitignore` files to determine which files and directories to not search

      --use-git-exclude-files
          If true, will read `.git/info/exclude` files to determine which files and directories to not search

  -h, --help
          Print help (see a summary with '-h')