Exercise: move your past work into Git

Take one finished project of your own, put the code under version control, and have a colleague prove it still runs

1 Start from the end

This exercise is not finished when your code is on GitHub. It is finished when you have opened an issue that asks a named colleague from the team to clone your repository, review it, and confirm that it reproduces — and they have answered.

That final issue is the deliverable. Everything before it exists to make it answerable. If the data location is missing, if the paths only work on your laptop, if one step lives in your head and nowhere else, your reviewer finds out in ten minutes and writes it in the issue. That is the point: version control is worth nothing until somebody other than you can run the work.

NoteThe shape of the exercise
  1. Copy one finished project of your own.
  2. Put the code under Git; leave the data where it belongs.
  3. Push it to github.com/worldbank.
  4. Say in the README where the data lives.
  5. Open an issue listing what is not yet reproducible.
  6. Open the hand-over issue: @a colleague, please reproduce this.
  7. Do the same for the colleague who asks you.

This is Route B.3 applied to real work: the folder exists first, the repository comes second.

ImportantWe drive Git from the editor, not the command line

In the MML the normal way to use Git is the Source Control view in Positron / VS Code — the same panel in both, because Positron is built on VS Code. Every step below shows the buttons first and links to the VS Code documentation.

Start here: VS Code — Source Control overview and the Source control quickstart.

The Git command line tab is kept for reference — the commands are what the buttons run, and they are what every tutorial on the internet will show you. You do not have to type them.

NoteBefore you start

2 Step 1 — Pick the project and copy it

Choose a small, finished project: one you understand and no longer have to deliver. A project still in flight is a bad first migration, because you will be tempted to fix the analysis and the version control at the same time.

Pick one a colleague has a realistic chance of running. Remember that a stranger to this project has to reproduce it at the end.

Work on a copy of the folder, never on the original. If the migration goes wrong, you delete the copy and start again.

Copy the folder in Windows Explorer, then open the copy in Positron: File → Open Folder. Everything from here happens inside that window.

3 Step 2 — Write .gitignore first

Before the repository exists, before anything is staged. Once a data file is committed it stays in the history even after you delete it, and removing it afterwards is far harder than never adding it.

Create the file with File → New File, name it .gitignore, and put it in the root of the project folder.

A starting point for a Stata project:

# data — never in Git
*.dta
*.dat
*.sav
*.csv
data/

# outputs and logs
*.log
*.smcl
*.xlsx
*.pdf
outputs/

# Office and OS litter
~$*
.DS_Store
Thumbs.db

Adjust it to your project, and keep adjusting it as new output formats appear.

Warning.csv and .xlsx cut both ways

Ignoring them protects you from committing results and microdata extracts. But small hand-made inputs — a parameter table, a country list — should be in Git. In Positron, right-click an ignored file in the Explorer and it offers no way in; the honest fix is a narrower ignore rule, or git add -f <file> once from the terminal.

4 Step 3 — Turn the folder into a repository and commit .gitignore alone

  • Open the Source Control view — the branching icon in the activity bar, or Ctrl+Shift+G.
  • Press Initialize Repository. Every file in the folder now appears under Changes.
  • Check the branch name in the status bar, bottom-left. If it says master, open the Command Palette (Ctrl+Shift+P) → Git: Rename Branch → main.
  • Hover .gitignore in the Changes list and press + to stage only that file.
  • Type the message Add .gitignore before tracking any project files in the box at the top and press Commit (Ctrl+Enter).
  • Reference: initialize a repository in a local folder, stage and commit.
git init
git branch -M main                  # make sure the branch is called main, not master
git add .gitignore
git commit -m "Add .gitignore before tracking any project files"

The first commit contains nothing but the ignore rules. That is deliberate: from this point on, the Changes list only shows you files that are genuinely candidates for tracking.

5 Step 4 — Add your code, one file at a time

Never stage everything at once. Stage files by name, and give each commit a message that says what the file does.

  • Read the Changes list top to bottom before staging anything. It is the same information as git status.
  • Click a file to open the diff — old version left, new version right — and confirm it is what you think it is.
  • Stage one file with the + next to it, write its message, press Commit. Repeat file by file.
  • The ⋯ menu at the top of the panel has Discard All Changes right next to Stage All Changes; read before you click.
  • Reference: make changes and review, Source Control overview.
git status                          # what is Git offering to track?
git add code/01_clean.do
git commit -m "Add cleaning: harmonize household IDs and drop duplicates"
git add code/02_analysis.do
git commit -m "Add wage regression with region fixed effects"

Never git add . — it sweeps up logs, data and temporary files.

“Add file” and “update” are not messages. The commit log is the only place the reason for a change is recorded — see “Commit messages are documentation” in Version control: Git + GitHub.

ImportantCheckpoint: no data in the repository

Read the whole Changes and Staged Changes list. If a .dta, a log or a results workbook appears there, stop and fix .gitignore before committing anything else.

If one has already been committed, the cheapest fix at this stage is to delete the copy of the folder and restart from Step 2. That is precisely why you are working on a copy.

6 Step 5 — Create the repository on GitHub and push

Name it by the MML naming rules and apply the settings checklist: owner worldbank, MML team as Maintain, About and Topics filled in.

  • In the Source Control view press Publish Branch.
  • Choose the owner — worldbank, not your personal account — the repository name, and private or internal visibility.
  • Positron creates the repository on GitHub and pushes your commits in one step; no remote add needed.
  • After that, the button becomes Sync Changes: it pulls and pushes together, every time you have committed something.
  • Reference: working with GitHub in VS Code, sync with the server.

Create an empty repository on GitHub first — do not tick “Add a README”, “.gitignore” or “licence”, because your history already has a first commit.

git remote add origin https://github.com/worldbank/<your-repo>.git
git push -u origin main
git remote -v                       # confirm origin points where you expect

Then open the repository page on GitHub and confirm two things: the code is there, and the microdata is not.

7 Step 6 — Say where the data lives

A repository with no data is only useful if it says how to get the data. This is the step your reviewer will judge you on, so write it for them and not for yourself.

Edit README.md so a colleague who has never opened this project can find the inputs:

  • the SharePoint location, spelled out in full;
  • the survey and its round, and the vintage of the extract;
  • who owns access, and how to request it;
  • where the code expects the data to sit once they have it, and which line of which do-file sets that path.

Rules for where data is archived and how it is referenced are in Data management and archiving.

Commit and Sync Changes.

8 Step 7 — Record what is still not reproducible

Migrating to Git does not make an old project reproducible. Hard-coded paths, manual steps, undocumented parameters and results produced by hand all survive the move intact.

Open one issue on the repository listing what would have to change for the project to meet the code reproducibility practices. Be specific — one bullet per problem, naming the file.

  • Repository page → Issues → New issue.
  • Title it Reproducibility gaps and list one bullet per problem.
  • The GitHub Pull Requests and Issues extension adds an Issues view in the Source Control sidebar, with Create Issue — and you can turn a TODO comment in a do-file straight into an issue from the editor.
  • Reference: VS Code — issues.

That issue is your to-do list the next time this project comes back, and it is honest context for the person you are about to ask for a review.

9 Step 8 — Hand it over: ask a colleague to reproduce it

This is the step the whole exercise exists for.

Open a second issue, titled something like Review and reproduce: <project name>, and at-mention the colleague who agreed to review you — typing @ and their GitHub username notifies them and links them into the thread. Assign the issue to them as well, so it appears in their list and not only in their inbox.

Write it so it can be answered without a meeting:

  • What the project does, in two sentences.
  • What to run, in order — the master do-file, and any step that must be run by hand.
  • Where the data is and how to request access (point at the README section from Step 6).
  • What the correct output looks like — the table, the number, the file — so the reviewer can tell success from failure.
  • What you already know is broken — link the Step 7 issue.
  • The question you want answered: “does this run end to end on your machine, and do you get the same numbers?”
TipExample

@colleague-username could you review this and check it reproduces?

code/00_master.do runs the whole thing; the data comes from the SharePoint folder linked in the README (ask @data-owner for access). A clean run writes outputs/table1.xlsx — the poverty headcount in row 4 should be 21.3.

Known gaps are in #1. Please comment here with what broke, or close this issue if the numbers match.

The issue stays open until your reviewer answers. Their answer is what tells you whether the migration worked.

10 Step 9 — Be the reviewer

You owe the same to whoever asks you, and this half teaches more than your own migration does.

  • Clone their repository — Command Palette → Git: Clone (reference).
  • Get the data where their README says it lives, and put it where their code expects it.
  • Run their code without changing it and without asking them anything. The moment you have to ask, that is a finding: write it in the issue instead of asking in chat.
  • Comment on the issue with what happened: what ran, what broke, at which line, and whether the numbers matched.
  • If it reproduced, say so and close the issue. If it did not, leave it open and at-mention the author.
NoteA failed reproduction is a successful exercise

Most first migrations do not reproduce on someone else’s machine. That is the finding, not a failure — it is exactly the list of things that would have been lost if the project had been inherited instead of reviewed. It is also the starting point for the day-two exercise on re-structuring your own project.

11 What “done” looks like

12 Where to read more