reproot
Title
reproot - Command for managing root file paths.
Syntax
reproot , project(string) roots(string) [ optroots(string) prefix(string) clear verbose]
| options | Description |
|---|---|
| project(string) | The project name to search roots for |
| roots(string) | Required root name(s) to search for |
| optroots(string) | Optional root name(s) to also search for |
| prefix(string) | Adds a project-specific prefix to root globals |
| clear | Always search for roots even if already loaded |
| verbose | More verbose output about roots found |
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 in this option (or in optroots() - see below), even if such roots for this project were found. Unless the clear option is used, the command does not overwrite any global that already had content 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.
optroots(string) allows the users to set optional roots. They will be treated the same way as the roots in roots() with the one exception that no error is thrown if this root is not found.
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 create. 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.
verbose makes the command output more information about what roots were found. This option is helpful for debugging when trying to figure out what roots are found and not found.
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 these commands on this repo where this package is developed. Please provide any feedback by opening an issue. PRs with suggestions for improvements are also greatly appreciated.