*! version 1.2 20240222

help file for repado

Title

repado - a command to handle ado-file dependencies

Syntax

repado using adopath , [nostrict lessverbose]

options

using adopath The file path to the ado-folder to use

nostrict Use nostrict mode instead of the default strict mode

lessverbose Have less explanatory details in the output

Description

This command is used to make sure that all users in a project use the exact same version of the commands the project code requires. This is done by creating a folder that we will call the ado-folder. This folder should be shared with the rest of the code of the project. This will work no matter how the files are shared. It can be using a syncing service like DropBox, a Git repository, a network drive, an external hard drive, a .zip folder etc.

Using repado in the strict mode, means that no other commands can be used apart from Stata's built in commands and the commands in the shared ado-folder.
The commands that users have installed on their computers will not be available.
These settings are restored next time Stata is restarted.

Using repado in the nostrict mode, means that built-commands and the commands ado-folder are available to the script in addition to any command any user has installed on their computer. However, if a command is installed on a user's computer that has the same name as a command in the ado-folder, then the exact version of the command in the ado-folder will be used.
These settings are restored next time Stata is restarted.

While it might seem more convenient to use the nostrict as default as it makes more command available to the user, we strongly recommend that for all projects that are expected to be reproducible, you use the strict mode. This is because if you run a script without "command ... is unrecognized" errors in strict mode, then you are guaranteed that all commands that script requires are indeed in the ado-folder. If you share the ado-folder with the rest of your code, then you know anyone reproducing your code will run your code using the exact same version of your dependencies.

Options

using adopath is used to specify where the ado-folder is located within the project folder. To make this reproducible across computers we recommend using a reproducible way of setting the root paths.
By sharing the folder adopath points to through OneDrive/DropBox etc.,
a network drive or a Git repository, you can set up a project environment
where all project dependencies are stable across all users.

nostrict is used to switch to the nostrict mode
instead of the default strict mode.
See the Description section above for a description of
the differences between the two modes.

lessverbose is used to reduce the output that this command produces. The default without this option is that this command outputs how the adopaths has been modified and how that makes running your code different.

Note on old and undocumented but still supported options

In earlier versions of repado, adopath(adopath)
and mode({ strict | nostrict }) were two documented options.
These two options are replaced by using adopath and nostrict,
but they are still supported for the sake of backward compatibility.

Examples

Example 1

In this example, the ado-folder is a folder called ado in the folder that the global myproj is pointing to.

repado using "${myproj}/ado"

Example 2

Similarly to example 1, in this example,
the ado-folder is a folder called ado in the folder
that the global myproj is pointing to.
In this example the nostrict mode is used.

repado using "${myproj}/ado", nostrict

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.

Authors

DIME Analytics, The World Bank dimenalytics@worldbank.org