Many ways to start: from a template, from scratch (online or locally), or from code you already have
1 Where a repository comes from
Route A — the repository exists on GitHub and you have rights to contribute.
A.1 clone → create a branch → modify, stage, commit, push → pull request → merge → repeat. This is the working loop, and it is where every other route ends up. Use it when the repository is yours or belongs to a collaborator in the MML.
Route B — nothing exists yet, and you want to start a new project.
Route C — the repository exists on GitHub, but you do NOT have rights to contribute (typical for a public repository).
C.1 fork it to your account or organization — that is, create your own copy of the repository on GitHub — then clone your copy → A.1.
2 The one idea: two copies, one history
Git is not GitHub. Understanding this single distinction removes about half of the confusion beginners have.
The local repository lives in a folder on your laptop, in a hidden .git sub-directory. This is where you work, and Git works perfectly well here with no internet at all.
The remote repository lives on GitHub. It is the shared, backed-up copy — the one your colleagues can see and the one that survives a dead laptop.
They are connected throughorigin, the nickname your local repository gives the remote. Once your local repository knows the address of the remote, push sends your commits up and pull brings other people’s commits down.
ImportantCommitting saves a snapshot locally
Only push puts your commit on GitHub. Work is not backed up, not reviewable, and not inheritable until it has been pushed.
Both copies — your laptop and GitHub — hold the same chain of commits.
They fall out of step only in one direction at a time: you commit locally and the remote does not know yet, or a colleague pushes and your laptop does not know yet. push and pull are the two moves that put them back in step.
2.1 One person, one branch
Start with the simplest possible setup: one repository, one branch called main, one person. There is a main on GitHub and a main on your laptop, and they are two copies of the same chain of commits.
flowchart TB
subgraph GH["GitHub — the shared copy — branch origin/main"]
direction LR
R1(["C1<br/>load the data"]) --> R2(["C2<br/>clean the age variable"])
R2 --> R3(["C3<br/>first regression"])
R3 -.-> R4(["C4<br/><i>not here yet</i>"])
end
subgraph PC["Your laptop — the local copy — branch main, inside .git"]
direction LR
L1(["C1<br/>load the data"]) --> L2(["C2<br/>clean the age variable"])
L2 --> L3(["C3<br/>first regression"])
L3 --> L4(["C4<br/>add region dummies"])
end
L4 ==>|"<b>git push</b><br/>your new commit goes up"| R4
R3 ==>|"<b>git clone</b> once, then <b>git pull</b><br/>their commits come down"| L3
classDef ghost stroke-dasharray:5 5
class R4 ghost
Figure 1: One person, one branch. Every commit exists in both copies of main; push sends yours up, pull brings theirs down.
Read it left to right and the two chains are identical. Read it bottom to top and you see the only thing that ever differs: a commit you have made but not yet pushed. That gap is what git status means when it says “your branch is ahead of origin/main by 1 commit”.
Alone on main, this always works. Nobody can change the remote behind your back, so push always succeeds.
2.2 Two people, one branch — where it breaks
Add a second person and keep the single main branch, and this picture stops being safe. Both clone at C3, both commit their own work, and whoever pushes second gets rejected. That collision — and the branch-plus-pull-request workflow that prevents it — is the whole subject of Git branching: an introduction. Read that page next.
3 New repository decision tree
Two questions decide your route.
Does the repository already exist on GitHub?
If it does, do you have rights to contribute to it?
Every route ends in the same place — the A.1 working loop. The routes differ only in how you get a repository to loop on.
flowchart TD
Q1{"Does the repository<br/>already exist on GitHub?"}
Q1 -->|"Yes"| Q2{"Do you have rights<br/>to contribute to it?"}
Q2 -->|"Yes — yours, or the Lab's"| CLONE["<b>git clone</b><br/>copy it to your laptop"]
Q2 -->|"No — a public repo"| C1["<b>Route C.1</b><br/><b>fork</b> it into your own account"]
C1 --> CLONE
Q1 -->|"No — new project"| B1["<b>Route B.1</b><br/>create from a <b>template</b><br/>(<code>mmlTemplate</code>)"]
Q1 -->|"No — new project"| B2["<b>Route B.2</b><br/>create a new <b>empty repository</b>"]
Q1 -->|"No — code already<br/>on your laptop"| B3["<b>Route B.3</b><br/><code>git init</code> locally"]
B1 --> CLONE
B2 --> CLONE
B3 --> UP["create an empty repo on GitHub<br/><code>git remote add</code> → <code>git push -u</code>"]
CLONE --> LOOP["<b>Route A.1 — the working loop</b><br/>branch → modify → stage → commit → push<br/>→ pull request → merge → repeat"]
UP --> LOOP
Figure 2: All routes converge on the A.1 loop. Only B.3 starts on your laptop; everything else starts on GitHub and reaches you through clone.
4 Settings for every new repository
Whichever route created the repository, apply this checklist once, on GitHub, before you start working. It is the short form of Version control: Git + GitHub; read that page for the reasoning.
5 MML practice: B.1 — a new repository from a template
A template repository is a ready-made starting point. Creating from it gives you a new, independent repository that already contains the template’s files but not its commit history.
On GitHub, press the + in the top-right corner → New repository.
Set the owner, name and visibility, then apply the rest of the settings checklist.
Tick Add a README file so the repository has a first commit and can be cloned straight away. Leave that box unticked only if you are going to push an existing local folder into it — see Route B.3.
7 MML practice: C.1 — fork a repository you cannot write to
A fork is your own copy of somebody else’s repository, under your own account or organization. You can commit and push to a fork freely; sending your work back to the original happens through a pull request from your fork.
Open the repository on GitHub and press Fork → choose the owner.
Clone your fork, not the original — otherwise your pushes will be rejected.
Inside the MML you rarely need this: you are added to the repository directly, which is Route A. Forking is for contributing to public projects.
8 Clone the remote repository to your laptop
Cloning downloads every file and every commit, creates the folder for you, and sets origin to the address you cloned from. Do it once per repository, per machine.
Command Palette (Ctrl+Shift+P) → Git: Clone, then paste the repository URL, or type to search the repositories you have access to after signing in to GitHub.
Choose the parent folder when Positron asks where to put it — it creates the project folder itself.
cd ~/projects # the PARENT foldergit clone https://github.com/worldbank/gnbFIA2026.git # creates gnbFIA2026/cd gnbFIA2026git remote -v# origin is already wired upgit log --oneline# the history came with it
WarningNever run git init inside a folder you cloned
The clone already created the repository. A second git init, or a repository nested inside another one, hides your commits from the outer repository and is confusing to undo.
9 MML practice: B.3 — turn an existing folder into a repository
You have a folder of do-files that has never been under version control. Here the local repository comes first and the remote is bolted on afterwards.
Four steps, in this order.
9.1 1. Turn the folder into a repository and make a first commit
Write .gitignorebefore anything is staged. Once a data file is committed it stays in the history even after you delete it.
cd ~/projects/hh-surveygit initgit branch -M main # make sure the branch is called main, not master# write .gitignore FIRST — *.dta, *.log, *.xlsx, data/ ...git add .gitignoregit commit -m"Add .gitignore before tracking any project files"git status # check what is still untracked, then add code file by file
File → Add local repository, pick the folder, and press create a repository when it reports the folder is not a repository yet.
Same New repository form as B.2, with one difference: do not tick “Add a README”, “.gitignore” or “licence”. Those options create a first commit on GitHub, and joining that to the history you just made locally is a fight you do not need on day one.
cd ~/projects/hh-surveygit remote add origin https://github.com/worldbank/<your-repo>.gitgit push -u origin main # first push: send main and remember where it goesgit remote -v# confirm origin points where you expect
After the first push, plain git push and git pull know where to go.
Press Publish repository, choose the owner and visibility, and confirm.
The repository now exists on GitHub, so give it the MML team, the description and the topics — the settings checklist.
10 Common gotchas
Write .gitignore before your first commit, and extend it whenever a new output format appears in the project. Removing a large file from history afterwards is far harder than never adding it.
Never stage everything at once.git add . sweeps up logs, data and temporary files. Add files by name and read git status before each commit.
Data does not go in Git. Microdata is archived read-only on SharePoint and read from there — see Data management and archiving.
Do not nest repositories. No git init inside a clone, and no repository inside another repository’s folder.
Clone from the parent folder.git clone creates the project folder itself; running it inside an existing project buries one repository in another.
Fork, then clone the fork. Cloning the original when you have no write rights leaves you unable to push.
11 Exercises (at home)
Two exercises, one per route you will actually use. Do them in order.
Refresh the repository page on GitHub and confirm both commits are visible with their diffs.
Open one issue describing what you would do next in this project.
11.2 Exercise 2 — Move your past work into a Git repository
Take one finished project of your own off a laptop folder or a shared drive and put the code under version control, leaving the data where it belongs. This is Route B.3 applied to real work, and it has its own page: Exercise: move your past work into Git.
12 Learn by doing: interactive practice
Reading about commits and branches only gets you so far. These run in the browser, need nothing installed, and cannot damage a real repository — so experiment freely.
The single best half-hour you can spend on Git. You type real Git commands and watch the commit graph move in front of you, level by level.
Do the Introduction Sequence (Main tab) to understand commits, branches, merging and rebasing.
Do Push & Pull — Git Remotes (Remote tab) to see the two copies, one history idea from Figure 1 animated: clone, push, pull, and origin/main moving.
The sandbox accepts any command, so you can test “what happens if…” without risking your project.
GitHub Skills — short guided courses that run inside a real GitHub repository, so you practise the GitHub half: pull requests, reviews, issues, merge conflicts. Start with Introduction to GitHub.
Git — learn — the official starting point, with the free Pro Git book, videos and reference documentation. Use it when you want the model rather than the moves.