Title

cdsave -- Create an ado file to changes the working directory
and set up the project environment. 2017-08-13

Add url()

Add user()

General syntax

cdsave [cd]project [ ,
note(string)
autorun(command-name)
datapath(path-name)
url(web-address)
user(string)
noslash ]
details
replace

Options

autorun(command) is the command that will be run when
cd*project is run.

datapath(path-name) is the path where data is stored. The
path is stored in the global S_cddata.

url(web-address) is a web address where data is stored. The
URL is stored in the global S_cdurl.

noslash will not add an ending slash to paths or URLS.

user(string) can be a path, web address, or other information.
The string is stored in the global S_cduser.

details will display the globals being created.

note(string) adds a note to describe the command being created.

replace if the ado file exists, replace it.

Since names of the globals begin with
S_ they are not removed by clear all or
macro drop _all. To remove then, macro drop global-name.

Overview

cdsave creates an ado file named cdproject
that changes your working directory.
The commands are save in your PERSONAL directory so that any time
you enter a command created cdsave Stata will find the command
regardless of your current working directory.
The cd* ado file can optionally be used to
annotates what the ado file does, create a global with your data directory,
automatically run a command when the cdproject is run, and other
things..

Note: The created commands start with cd. You can enter
the project with cd at the start of the name, or the cd
will be added automatically.

By creating multiple
cd* commands, you can easily
have different working directories for each
project with optional data locations for each project. The command
cdlist lists your cdproject commands along with
the the working directory it sets or optionally lists the note you
added to describe the command. The command
cdinfo displays the S_cd* macros created by the command.
The command cddrop deletes selected cdproject commands
from PERSONAL.

Changing directories with cd* commands

A simple example using two projects explains the most basic use of
cd* commands.
Suppose that project A uses working directory d:/projectA/work,
while project B uses working directory d:/projectB/work.

Change your working directory to d:/projectA/work
To create the command cdprojecta to change the working directory
to d:/projectA/work:

. cdsave projecta

command {cmd:cdprojecta saved in your personal directory

Since the command is saved in your personal directory, Stata will find it
when you run the command from any working directory:

. cdprojecta

d:/projecta/work

Next, change the working directory to d:/projectB/work
and runn cdsave projectb to create cdprojectb.ado which changes
the working directory to d:/projectB/work

Keeping track of cd* commands

The note() option along the cdlist command help you keep track
of the commands you create. By default, cdlist lists the names of
all cd* commands and the working directory they set:

. cdlist

cdaaa - d:/aaa/work/

cdbbb - d:/bbb/work/

cddesk - c:/Users/jslong/Desktop/

cdicpsr - d:/icpsr2017/work/

If you prefer, you can use the note() option with cdsave
to document what the command does. For example, cdsave aaa, note(Project A).
If a note has been saved with a command, it is listed instead
of the path for the working directory:

. cdlist

cdaaa - Project A

cdbbb - d:/bbb/work/

cddesk - Desktop

cdicpsr - ICPSR CDA Class 2017

cdtemp - scratch directory

The cdinfo command and cdlist, details provide more detailed
information about other features used with creating comamnds.

Using globals for datasets not in the working directory

By default, the use command loads a dataset from the working
directory. If you want to load datasets from a different directory
or a web address, yu can use the globals create by the cd* commands--assuming
you added these options when creating the command.

To load a dataset from the path specified by the data() option
in cdsave,

use "$mydata", clear

To load a dataset from the URL specified by the url() option
in cdsave,

use "$mydata", clear

Three points about data paths.

1. By default paths and URLS are saved using /, not \.
The forward slash works in Win, Mac, and Unix.

2. S_cddata and S_cdurl ends with / so that
if the globals are not defined,
use "$dataset" ,replace
will still work. The cdsave, noslash option will not automatically
add an ending slash.

3. Quotes are needed when specifying the path in case there are spaces in
the path name.

Automatically running a command for each project

The autorun(command) lets you specify a command that is run
as the last command in the cd* command.
This can be a Stata command or the name of an ado file you create
to initialize the project. As a simple example, suppose you always wanted
to load a specific dataset when you loaded your project. I can
create the command:

. cdsave cdautoload, autorun(use binlfp4, clear)

To automatically load a dataset. Or, I can run a do file:

. cdsave cdautoload, autorun(do myproject.do)

Controlling the starting working directory

You can create the command cdstart with cdsave and then
add cdstart to your profile.do to make the directory
set by cmdstart the starting directory in Stata.
You can replace the existing cdstart to have Stata begin in
a different directory.

In profile.do you can add cdlist to start Stata with a list
of the cd* commands. You can click on the command names, shown in blue,
to run the command.

These commands are suggested to prevent errors if any of the cd* commands
are not installed:

. capture noisily cdlist

. noisily di _new ". cdstart"

. capture noisily cdstart

This will list all available cd* commands and then change to the
directory specified in cdstart.

Globals

The cd* command use these globals:

S_cdcmd name of cd* command.

S_cdauto command to be automatically
run on completion of cd* command.

S_cddata data directory path.

S_cdurl web address.

S_cduser any string.

S_cdwd working directory set by cd* command.

Citation

J. Scott Long. 2017.
A workflow for managing projects and working directories in Stata.

http://www.indiana.edu/~jslsoc/