*! version 1.2 20240222

help file for reproot

Title

reproot - Command for managing root file paths.

Syntax

reproot , project(string) roots(string) [ prefix(string) clear]

options

project(string) The project name to search roots for.

roots(string) The root name(s) to search for.

prefix(string) Adds a project-specific prefix to root globals.

clear Always search for roots even if already loaded.

reproot is a framework for automatically handling file paths across
teams without requiring project-specific setup from individual users.
Each user needs to set up reproot once on their computer (see the next paragraph).
Afterward, users can automatically load root paths with
no manual setup in all projects using reproot on that computer.

reproot works by having the team save a root file in root folders required in the project.
Such root folders could be the root of a Git clone folder,
the root of a OneDrive/DropBox folder where data is shared,
or the root of a project folder on a network drive where files are shared, etc.
As long as the folder is accessible from the file system,
a root can be placed in that folder.
File paths to specific files can then be expressed in the code as
relative paths from any of those roots.

To avoid searching the entire file system for roots (which would take too much time),
each user needs to configure a reproot-env file.
This file lists which folders and how many sub-folders of those folders
reproot should search for root files.
This setup should make the search take less than a second.

The reproot-env file should be created in the folder that
Stata outputs when running the code cd ~.
This location can be accessed by all users without having to set any root paths first.

Read more about setting up this file in
this article.
The rest of this help file will focus on how to use this command once those files are set up.

Options

project(string) indicates the name of the current project. When searching for root files, only root files for this project will be considered. Use a project name that will remain unique across all team members' computers.

roots(string) indicates which roots are expected to be found for this project.
The command creates a global based on the root name of that root
if that root folder is found.
The content of the global will be the file path to the location of the root file.
This command does not set globals for roots not listed here,
even if such roots for this project were found.
Unless the clear option is used,
the command does not overwrite any global that already existed before running the command.
Finally, the command tests that there is a global named after each root and
that all of them are non-empty.

prefix(string) allows the user to set a project-specific global prefix.
This is strongly recommended to ensure that a global from another project
is not mistaken as a global for the current project.
Unless the clear option is used,
a global already set with a common name, such as data or code,
will be interpreted as a root global with that name for the current project.
The prefix() option allows a project-specific prefix that is set to all globals.
So, if prefix("abc_") is used, then the globals data and code
will be set to abc_data and abc_code.

clear overwrites globals that already exist with the name that reproot would creaet.
This is all the roots listed in roots() with
the prefix() prepended if that option is used.
The default behavior is to not search for roots that are already set up.
If all globals are already set, then the command does not execute the search for roots.

Examples

These examples demonstrate how to include reproot in the do-file.
See this article
for information on how to set up the .yaml files this command needs to run.

Example 1.

In this example, the command searches the search paths indicated in
the reproot-env.yaml file for root files for the project my_proj.
Then it sets the globals data and clone to the file location where
root files with those names for this project are found.

reproot , project("my_proj") roots("data clone")

Feedback, bug reports and contributions

Read more about the commands in this package at https://worldbank.github.io/repkit.

Please provide any feed back by opening and issue at https://github.com/worldbank/repkit.

PRs with suggestions for improvements are also greatly appreciated.

Authors

LSMS Team, The World Bank lsms@worldbank.org
DIME Analytics, The World Bank dimenalytics@worldbank.org