NAME
    RepRoot - the simplest way to find the root directory of your source
    code repository

VERSION
    Version 0.01

SYNOPSIS
    In the root of your source code repository:

        touch .reproot

    In your perl script:

        use RepRoot;

        my $schema = "$RepRoot::ROOT/data/sql/schema.sql";
        ...

DESCRIPTION
    When RepRoot is first loaded, it determines which directory your script
    lives in and looks in there for a file named .reproot. If it doesn't
    find it there, it will search up the path, one level at a time, until it
    finds it or errors out. When the .reproot file is found, the
    $RepRoot::ROOT variable is set to that path.

    Additionally, if the .reproot file is more than 0 bytes, the file's
    contents will be excuted using the perl "do" function, allowing for
    additional custom configuration (such as "use lib" statements to add
    your repository libraries to the perl include path).

BUT WHY?
    Let's look at a typical scenario where RepRoot would be useful.

    Your company has a source code repository with a fairly standard layout:

        > find project_x/
        project_x/bin/
        project_x/bin/foo.pl
        project_x/data/
        project_x/data/sql/
        project_x/data/sql/schema.sql
        project_x/docs/
        project_x/lib/
        project_x/lib/perl/
        project_x/lib/perl/MyCustomLib.pm

    You have some custom perl libraries under lib/perl/, some perl scripts
    under bin/, and a file containing your database schema in
    data/sql/schema.sql.

    In order to access the perl libraries you have to include something like
    this at the top of every perl script:

        use lib "../lib/perl";

    Similar problem is you want to access the schema file:

        my $schema_file = "../data/sql/schema.sql";

    The problems are:

     - it's ugly
     - the path is relative and depends on where the script lies within the repository,
       which means it must be updated if the script is moved

    You can use RepRoot to solve the problem by doing the following:

    1) create a .reproot file in the root of the repository (in the
    hypothetical case, that would be directly under project_x/)

    2) add some code to .reproot to include the path to your custom perl
    libs:

        use lib "$RepRoot::ROOT/lib/perl";
        1;

    3) use RepRoot in your perl scripts:

        use RepRoot;
        use MyCustomLib;
        my $schema_file = "$RepRoot::ROOT/data/sql/schema.sql";

    Don't forget that if you include anything at all in .reproot (if
    filesize > 0 bytes), the contents will be executed, and the last value
    must be true or it will fail. So, just like when you write a perl
    module, make sure to stick a "1;" on a line by itself at the end.

AUTHOR
    Written by Ofer Nave <ofer@netapt.com>. Sponsered by Shopzilla, Inc.
    (formerly BizRate.com).

BUGS
    Please report any bugs or feature requests to "bug-reproot at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RepRoot>. I will be
    notified, and then you'll automatically be notified of progress on your
    bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc RepRoot

    You can also look for information at:

    * AnnoCPAN: Annotated CPAN documentation
        <http://annocpan.org/dist/RepRoot>

    * CPAN Ratings
        <http://cpanratings.perl.org/d/RepRoot>

    * RT: CPAN's request tracker
        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RepRoot>

    * Search CPAN
        <http://search.cpan.org/dist/RepRoot>

COPYRIGHT & LICENSE
    Copyright 2006 by Shopzilla, Inc, all rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See http://www.perl.com/perl/misc/Artistic.html