help rcd
-------------------------------------------------------------------------------

Title

     recursively traverse directories and execute
     any command in or for each one of them

Syntax

        rcd [directory_name], [verbose] [depth(integer >= 1)]
                 [dirfilter(regular expression)] [: command]

Description

    rcd expects a directory name otherwise the current working directory is
    used.  rcd proceeds to recursively visit all subdirectories starting
    there.  rcd will display what directories it goes to in verbose mode,
    obey a maximum depth if one is specified and it will optionally run a
    command in each directory if desired.  Which directories the submitted
    command are run in can be selected by using the dirfilter() option.

    rcd may be thought of as a recursor.  A typical example of what you can
    do using it is:
 
    . rcd . : dir "data"

    which would result in visiting every subdirectory starting where you are
    wanting to see the Stata datafiles in each one of them.

    Another way to achieve the same thing would be to use the returned macros
    that rcd generates:
 
    . rcd .
    . forvalues i = 1(1)`r(tdirs)'{
    . dir "`r(ndir`i')'`c(dirsep)'*dta"
    . }


Options

    verbose specifies to print the directories that rcd visits.  By default,
    if rcd is invoked with no directory specified or options specified, then
    rcd runs in verbose mode.

    depth specifies an integer value greater than or equal to 1 (one) to
    limit how far down the directory tree rcd will go. depth(1) specifies not
    to look in subdirectories.

    dirfilter specifies regular expression to limit what directories the
    specified command will be run in.  If you want to see what directories
    your command will be run in, use rcd and specify to run pwd like so:
 
    . rcd , dirfilter(data) : pwd

Remarks
    Since rcd runs whatever Stata command and changes directories in the
    process, if there is a lot printed to the results window and you get
    tired of clicking more to continue and quit, then your current directory
    may not be where you started.  To quickly get back to the directory you
    were in when you invoked rcd just use the returned local macro r(sdir)
    like so:
 
    . cd "`r(sdir)'"

Examples

    Only look in directories whose names contain the word "data":
 
    . rcd . , dirfilter(data)

    An example from the realm of managing your files and your data can be
    constructed by using the grep command:
 
    . rcd .
    . return list
    . forvalues i = 1(1)`r(tdirs)'{
    . grep Family Children, path("`r(ndir`i')'`c(dirsep)'data")
    . }

    The code above locates and lists Stata datafiles to either use or
    describe all or part of each dataset found in the current directory or
    any of its subdirectories whose variable names or labels contain either
    of the words "Family" or "Children".
 
    Another way to do the same thing by listing as you go would be:
 
    . rcd . : grep Family Children

Saved results

    rcd saves the following in r():
 

    Macros         
      r(sdir)             directory rcd was invoked in
      r(tdirs)            total number of directories searched
      r(ndir1)            name of the first directory searched
      r(ndir2)            name of the second directory searched

 Author
    Nikos Askitas
    IDSC of IZA
    IZA, Bonn Germany
    nikos@iza.org

    Dan Blanchette
    Center of Entrepreneurship and Innovation
    Duke University's Fuqua School of Business
    Dan.Blanchette@Duke.edu

Also see

    Online:  help for cd, dir