Title

cdsave -- Create ado file that changes the working directory

Add url()

Add user()

General syntax

cdsave [cd]project [ ,
note(string)
datapath(path-name)
autorun(command-name)
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. Since the name begins with
S_ it is not removed when you run clear all or
macro drop _all.

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.

Overview

cdsave creates an ado file named cdproject
that changes your working directory.
Importantly, the command is save in your PERSONAL directory so that any time
you enter a command created cdsave Stata can find the command
regardless of your current working directory.
For more information, run help adopath).
The ado file can optionally be used to
annotates what the ado file does, create a global with your data directory,
and automatically run a command when the cdproject is run.

Note: The commands that are created must 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 AAA uses working directory d:/aaa/work while
project BBB uses working directory d:/bbb/work.

Begin by changing your working directory to d:/aaa/work.
To create the command cdaaa to change the working directory
to d:/aaa/work:

. cdsave aaa

command cdaaa 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:

. cdaaa

d:/aaa

Next, change the working directory to d:/bbb and running
cdsave bbb to create cdbbb.ado which changes
the working directory to d:/bbb.

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.

A global for a data directory

By default, Stata's use command will load a dataset from the working
directory. While that is my preferred method, there are situations in
which this is not possible, such as when local policies require source datasets
to be located on the LAN. Or, you might want to load some datasets from
the web, but not want to type the long web address each time.

The datapath(path-name) option lets you enter a path to your data
that is placed in the global S_cddata when you cd* command is
run. For example:

.cdsave data, datapath(d:/data) note(Data path in d:/data)

command cddata saved in your personal directory

To see the globals that are created by cddata:

. cddata

d:\dropbox\active\changewd 2017\work

. cdinfo

S_cdcmd: cddata

S_cdauto:

S_cddata: d:/data/

S_cdnote: Data path in d:/data

S_cdwd: d:/dropbox/active/changewd 2017/work

I can use the data global to load a dataset:

use "$mydata", clear

TODO: comment on how this leads to a robust do-file.

You can use the data() option for specifying a url. For example,

cdsave web, data(http://www.indiana.edu/~jslsoc/stata/spex_data/)

You could load some datasets from the web, with others from the working directory,
such as:

use "$binlfp4", clear

output omitted

use nomocc4, clear

Three points about data paths.

1. All paths are saved using / which works in Win, Mac, and Unix.

2. S_cddata ends with /. This is done so if the global S_cddata
is not defined, use "$dataset" ,replace
will still work.

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 created by cdsave.
This can be a Stata command or the name of an ado file you have created
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)

Command cdautoload saved in your personal directory

When I run the command:

. cdautoload

d:\dropbox\active\changewd 2017\work

(binlfp4.dta | Mroz data on labor force participation of women | 2014-10-20)

Controlling the starting working directory

You can change the working directory in which Stata starts, but there is
not a simple way to do this. If you periodically change the starting
directory to be that of the project you are working on, this is a
nuisance. You can use cdsave to automate this process. The
starting working directory is set when you install Stata. There are
several ways to change it that vary across operating systems.

Getting Started with Stata (Windows) provides one, geeky method:
" You can have Stata start in any directory you desire. If necessary, delete the parameter
/UseRegistryStartin from your Target field.
Then change the Start in field of Stata’s Properties Sheet to
the location you would like Stata to have as its default working directory."
In Mac, the starting working directory is the working directory you
were using when you last quit Stata. In Unix, neither the Windows or Mac
methods work.

All three operating systems let you set the starting
directory in profile.do located in the the STATA
directory; run sysdir to find the location. You can add the following
command to profile.do, or create the file if it does not exist,
to let the command cdstart that you create with cdsave set
your initial working directory.

cdstart

This command will run each time Stata starts and will set the working
directory. For example, suppose you want the starting working
directory to by d:/aaa/work. Navigate to that directory with:

cd d:/aaa/work

The create cdstart:

cdsave start, note(Default working directory

Stata will run cdstart when it is started and cdstart will
change the working directory to d:/aaa/work.

You can easily change the starting directory without editing profile.do.
For example, I use a different working directory for each project and prefer
to have Stata start in the working directory used for the project
I am focusing on. Suppose the project AAA is on hold and I want to focus on
project BBB with working directory d:/aaa/work. All I need to do is:

cd d:/bbb/work

cdsave start, note(Default working directory) replace

If you want Stata to start by reminding you of the cd* commands you
have created, add these lines to profile.do:

. 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.

Programming notes

1. Since cdsave creates ado files that are saved in PERSONAL
(run adopath to locate this directory), Stata will find these commands
as long as you have a PERSONAL directory. This is created by default when
Stata is installed. If not, TODO EXPLAIN HOW TO ADD IT

2. The names of globals begin with S_cd. Globals that begin with S_
are not removed with macro drop _all since S_ globals are designed
to hold information created by Stata describing your version of Stata.
The names include _cd to make it less likely they will interfer with
globals created by Stata.

3. You can edit the cd*.ado files to add additional features for a
specific project. Or, you can use the autorun() feature to run
an ado file that does other things (e.g., create a web path global in
addition to the data path global.)

The cd* command create the following 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_cdwd working directory set by cd* command.

Citation

J. Scott Long. 2017.
changewd: Managing working directories for projects.

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