closest

A lightweight command-line tool that searches the current directory or parent directories for specific files and returns the closest path.

Why closest?

Many tools only look for configuration files in the current directory or in the home directory, but not in parent directories. This makes it difficult to use these tools in monorepos or nested project structures.

closest solves this problem by finding the nearest matching file in the directory hierarchy, making it easy to:

• Use tools with configuration files in parent directories
• Find configuration files in monorepo structures
• Locate files without knowing their exact location
• Troubleshoot configuration inheritance

Installation

Download binary

Download the latest binary from GitHub Releases.

# Example for Linux (amd64)
curl -L https://github.com/corrupt952/closest/releases/latest/download/closest_linux_amd64.tar.gz | tar xz
sudo mv closest /usr/local/bin/

Nix

# Run without installing
nix run github:corrupt952/closest -- help

# Install into your profile
nix profile install github:corrupt952/closest

Builds from source on the current main; closest version reports the commit hash it was built from.

Install via aqua

If you use aqua, you can install closest with:

aqua g -i corrupt952/closest

Build from source

git clone https://github.com/corrupt952/closest.git
cd closest
go build

Usage

Usage: closest [search] [options] [pattern]
Commands:
  search [-a] [-r] <pattern>    Find the closest matching file
  version                       Print closest version
Options (search):
  -a    Search all files[default: false]
  -r    Use regex pattern for matching[default: false]

search is the default command: closest .envrc and closest search .envrc are equivalent. To search for a file literally named search, version, help, or commands, spell out the search command explicitly (e.g. closest search version).

Exit Codes

The tool uses the following exit codes:

• 0: Success - Files were found and output
• 1: Error - An error occurred (file not found, invalid regex, permission denied, etc.)
• 2: Usage error - Wrong number of arguments to search or version

Basic Usage

Find the closest file matching a specific name:

closest search .tflint.hcl
# Output: /path/to/closest/.tflint.hcl

Find all matching files from current directory to root:

closest search -a .envrc
# Output: 
# /current/path/.envrc
# /current/.envrc
# /home/user/.envrc

Find files using regex patterns:

closest search -r ".*\.ya?ml$"
# Output: /path/to/closest/config.yaml

Examples

Example 1: Using with tflint

tflint only references .tflint.hcl in the current or home directory. With closest, you can use project-specific settings from parent directories in a monorepo.

Directory structure:

/
└── home
    └── app
        └── terraform
            ├── .tflint.hcl
            └── example-service
                ├── production
                └── staging # <- current directory

Run tflint with the closest configuration:

tflint --config $(closest search .tflint.hcl)

Example 2: Troubleshooting direnv configuration

When using direnv, you might want to find all .envrc files that affect the current directory. The -a option helps with troubleshooting by showing all relevant files.

Directory structure:

/
└── home
    └── app
        ├── .envrc
        └── terraform
            ├── .envrc
            └── example-service
                ├── .envrc
                ├── production  # <- current directory
                |   └── .envrc
                └── staging

Find all .envrc files from current directory to root:

closest search -a .envrc

Output:

/home/app/terraform/example-service/production/.envrc
/home/app/terraform/example-service/.envrc
/home/app/terraform/.envrc
/home/app/.envrc

Note: Command options must come before the filename. For example, closest search .envrc -a doesn't work.

Error Handling

closest provides clear error messages for common issues:

• File not found: When no matching files are found in the directory hierarchy

  Error: file not found: config.json
  

• Invalid regex pattern: When the provided regex pattern is invalid

  Error: invalid regex pattern: error parsing regexp: missing closing ]: `[abc`
  

• Permission denied: When the tool cannot access a directory due to permission issues

  Error: failed to read directory /path/to/restricted: permission denied
  

• Missing pattern argument: When no search pattern is provided

  search [-a] [-r] <pattern>: Find the closest matching file
  

Example 3: Finding configuration files with regex

Sometimes you need to find configuration files that might have different extensions. The -r option enables regex pattern matching for flexible searches.

Find the closest YAML configuration file:

closest search -r ".*\.ya?ml$"

Find all YAML files in the directory hierarchy:

closest search -a -r ".*\.ya?ml$"

Output:

/home/app/terraform/example-service/production/config.yaml
/home/app/terraform/example-service/terraform.yaml
/home/app/terraform/main.yml
/home/app/config.yml

Troubleshooting

Common Issues

1. No files found

   • Check if the file exists in any parent directory
   • Verify the spelling and case of the filename (filesystems may be case-sensitive)
   • If using regex, ensure the pattern is correct

2. Permission errors

   • Ensure you have read permissions for all directories in the path
   • Try running with elevated privileges if necessary

3. Regex not matching

   • Test your regex pattern with a regex testing tool
   • Remember to escape special characters
   • For complex patterns, start simple and build up

Debugging Tips

• Use the -a flag to see all matching files, which can help identify if files exist but aren't where expected
• For regex issues, try simplifying your pattern first, then make it more specific

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

For detailed information about the development setup, workflow, and release process, please see the CONTRIBUTING.md file.

License

This project is licensed under the MIT License - see the LICENSE file for details.