/ 
File-FindRoot-0.003
/ File::FindRoot

NAME

File::FindRoot - Find the directory that's the root for a project

SYNOPSIS

use File::FindRoot;

Start looking in the current directory and in each ancestor directory until you find one that contains the relative path. Return that directory:

my $dir = File::FindRoot->dir_contains( $rel_path );
unless( defined $dir ) { ... }

Or matches a pattern:

my $dir = File::FindRoot->dir_contains( qr/$patten/ );

Start in a different directory:

my $dir = File::FindRoot->dir_contains( $file, { start_at => $path } );

Limit the number of ancestors checked:

my $dir = File::FindRoot->dir_contains( $file, { limit => $n } );

DESCRIPTION

Lately I've done a number of things where a program deep in a project had to find its project config file or library directory.

File::FindRoot->dir_contains( REL_PATH [, OPTIONS] )

Returns the directory that contains REL_PATH, and the empty list otherwise.

  • callback - (default: check that path exists) a subroutine that returns true if the current directory is the one you want based on whatever you decide.

  • debug - (default: 0) if true, output progress information. If you do not specify a value, it uses the defined value of the FILE_FINDROOT_DEBUG environment variable, or finally, 0.

  • debug_fh - (default: STDERR) the output filehandle for debugging info

  • limit - (default: inf) the maximum number of ancestors to inspect.

  • start_at - (default: current working directory) the directory in which to start looking. If the string is not a directory, such as a filename, it uses the directory name of the path. Any value is turned into an absolute path.

The callback argument takes a code reference with three positional parameters: the current candidate directory, the passed REL_PATH argument, and the OPTIONS hash:

my $coderef = sub ( $candidate_dir, $target, $options ) { ... };
File::FindRoot->dir_contains( '.git', { callback => $coderef });

If you don't specify a callback argument, if uses one that catfiles the directory and target and returns the value of -e on the result:

my $coderef = sub ($candidate_dir, $target, $options) {
	-e File::Spec->catfile($candidate_dir, $target)
	};

TO DO

SEE ALSO

SOURCE AVAILABILITY

This source is in Github:

http://github.com/briandfoy/file-findroot

AUTHOR

brian d foy, <briandfoy@pobox.com>

COPYRIGHT AND LICENSE

Copyright © 2026-2026, brian d foy, All Rights Reserved.

You may redistribute this under the terms of the Artistic License 2.0.