Written and maintained by CASRAI Editorial Board
Last updated
A Stata do-file is reproducible when someone else — or you, six months from now — can run it against a clean copy of the raw data and get exactly the same results, with no manual steps filled in from memory. Working interactively in the Data Editor or typing commands one at a time into the Command window doesn’t leave that record: whatever isn’t in the do-file itself has to be reconstructed by hand. This guide covers the header block every reproducible do-file needs (version, clear all, set more off, log using), Stata’s comment styles, portable file paths, and how to run a do-file the way a collaborator or a script actually would — not just the way it happened to work the first time you tested it.
Why an interactive session isn’t reproducible
Stata lets you work two ways at once: point-and-click through menus and dialogs, or type commands directly into the Command window. Both execute immediately and both can leave data transformed in memory in ways nothing durable records. Close Stata, and the only trace of a menu-driven session is whatever ended up in the dataset itself — not the steps that produced it. A do-file (a plain-text .do file containing a sequence of Stata commands, opened and run in the Do-file Editor) is the artefact that survives, but only if it’s written to run cleanly from a fresh Stata session against the original data, top to bottom, with no leftover objects and no undocumented in-session edits it silently depends on.
Start every do-file the same way: the header block
A reproducible do-file opens with a small block of commands whose only job is to guarantee it starts from a known, empty state — not whatever happened to be left in memory from the last thing you ran.
version 18
clear all
set more off
capture log close
log using "analysis.log", replace text
versionpins the do-file to the syntax and behavior of a specific Stata release (here, 18). Stata’s command syntax and default behavior have changed across major versions; a do-file with noversionstatement is silently interpreted using whatever version happens to be installed when someone runs it, which is exactly the kind of dependency a reproducible file shouldn’t have.clear alldrops the dataset in memory along with matrices, scalars, stored estimates, and cached ado-files — a more complete reset than plainclear, which by default clears only the data. Runningclear allfirst means the do-file can’t accidentally succeed because of an object left over from an earlier, unrelated session.set more offdisables the--more--pagination prompt that otherwise pauses long output and waits for a keypress — harmless when you’re watching the screen, but it will hang a do-file run unattended or in batch mode.log using "analysis.log", replace textopens a log that captures every command and result for the run. The.logextension (with thetextoption) writes plain text; leave the extension off, or use.smcl, and Stata writes its own formatted SMCL log instead, readable in the Viewer but not in a plain text editor.replaceoverwrites a log file left over from a previous run instead of erroring on a duplicate name. Thecapture log closeline immediately above it closes any log already open —capturesuppresses the error Stata would otherwise raise if no log was open, which matters because a do-file re-run after a previous failed attempt often has one dangling.
Comments: four styles, different jobs
Stata supports several comment forms, and a reproducible do-file uses more than the bare minimum — comments are what let someone who isn’t you understand why a step exists, not just what it does.
* A line starting with an asterisk is a whole-line comment.
di "hello" // a double-slash comments out everything to the end of the line
/* a slash-star block comment
can span several lines, and can also
sit in the middle of a line of code */
regress y x1 x2 ///
if sample == 1 // triple-slash joins this line to the next
* and // both comment out the rest of a line but read differently in practice: * reads as a section marker or note sitting on its own line, while // reads as an aside on a line of real code. /* ... */ is the only form that can wrap inside a single physical line or span multiple lines, which makes it useful for temporarily disabling a block of commands during debugging. /// is not a comment at all in the usual sense — it’s a line-continuation marker that tells Stata the next physical line is part of the same logical command, which keeps a long command (a regression with many covariates, a complex if condition) readable across several lines instead of one unbroken one.
Working directory and portable file paths
A do-file with an absolute path like C:UsersjsmithDesktopprojectdata.dta hard-coded into a use command only runs on the machine it was written on. Set the working directory once, near the top of the file, and reference everything else relative to it:
cd "/path/to/project"
use "data/raw/survey.dta", clear
For a project with more than one person running the same do-files from different local paths, a common convention is a local or global macro holding the project root, set once per machine (sometimes in a separate, machine-specific do-file that isn’t shared), with every other path in the project built from it — so the shared do-files themselves never contain a path specific to one computer.
Ending the file: close the log
A do-file that opens a log should also close it, so the file is complete and readable the moment the run finishes rather than left open and inaccessible until Stata itself closes:
log close
A complete template
version 18
clear all
set more off
capture log close
log using "analysis.log", replace text
* Project: [name]
* Author: [name]
* Purpose: [one line]
cd "/path/to/project"
use "data/raw/survey.dta", clear
* --- data cleaning ---
drop if missing(outcome)
label variable outcome "Primary outcome"
* --- analysis ---
regress outcome predictor1 predictor2
* --- export results ---
outreg2 using "results/table1", replace
log close
Every reproducible do-file follows the same shape: a fixed header, a clean load of the raw data, cleaning steps that never overwrite the raw file itself, the analysis, and a closed log — run start to finish with nothing manual in between.
Running a do-file the way it will actually be reproduced
Typing do "analysis.do" into the Command window, or clicking the Do-file Editor’s run icon, both work — but they also run inside whatever state your own Stata session was already in, which is exactly the untested path. A real reproducibility check runs the file the way someone else would: a fresh Stata session, or headless from the command line.
On Windows, from a terminal:
StataMP-64 /e do "analysis.do"/e runs the do-file without opening the interactive interface and without requiring a click to exit when it finishes; /b runs it the same way but leaves a dialog to dismiss at the end. On Mac and Linux, the terminal equivalent is stata -b do analysis.do. Either way, Stata writes a log of the run (named after the do-file unless a log using command inside it specifies otherwise) and exits without anyone watching the screen — the closest thing to proving the file actually reproduces on its own.
Structuring a multi-file project: a master do-file
Once a project has more than one do-file — cleaning, then analysis, then figures — a master do-file that calls the others in order keeps the run order itself documented and reproducible, rather than relying on someone remembering “run cleaning.do, then analysis.do, then figures.do”:
version 18
clear all
set more off
global projdir "/path/to/project"
cd "$projdir"
do "code/01_clean.do"
do "code/02_analyze.do"
do "code/03_figures.do"
Each sub-file can still open and close its own log; the master file’s job is only to fix the sequence and the shared project path in one place, so it never has to be duplicated across files that might drift out of sync with each other.
What’s the difference between clear and clear all?
Plain clear drops only the dataset currently in memory. clear all additionally drops matrices, scalars, stored estimation results, constraints, and cached ado-files, resetting Stata closer to how it was when it first started. A reproducible do-file’s header uses clear all specifically so a leftover object from an earlier, unrelated do-file can’t silently affect the run.
Do I need set more off in every do-file?
If the do-file will only ever be run interactively by someone watching the screen, it’s optional. It becomes necessary the moment the file might run unattended or in batch mode — without it, a long output can leave the run paused indefinitely at a --more-- prompt nobody is there to dismiss.
What’s the difference between a .log and a .smcl log file?
Both record everything a do-file’s run produced. A .smcl file (Stata’s default if no extension or the text option is specified) uses Stata’s own markup and is readable in the Viewer, with formatting Stata renders. A .log file with the text option is plain text, readable in any editor and easier to diff, search, or version-control alongside the do-file itself.
Does commenting out an old block of code count as version control?
No. Commented-out code accumulates inside a single file and gives no record of when or why a change was made, and it’s easy to lose track of which commented block was the last working version. A real version-control system (tracking the do-file itself, e.g. with Git) records that history properly; commenting-out is, at best, a stopgap inside a single file and shouldn’t substitute for it on any file more than a few dozen lines long.
This mirrors the same reproducibility problem CASRAI’s guide to SPSS syntax files covers for SPSS: the point-and-click interface in either package leaves no durable record, and the fix in both cases is the same — a plain-text command file that runs cleanly against unmodified raw data. For choosing between the two packages, see CASRAI’s SPSS vs. Stata comparison, or R vs. Stata if a fully open-source, script-based alternative is in scope. A reproducible do-file is one part of a larger picture; see CASRAI’s guides to writing a data availability statement and to reproducibility infrastructure (workflows, containers, and code sharing) for what surrounds the do-file itself. For specific Stata procedures written the way this guide’s template expects, see CASRAI’s guides to labeling variables and values, running a t-test, regression, merging datasets, the append command, and reshaping data from wide to long in Stata.
