Git and GitHub for Stata Data Projects — Day Two: Branching, Collaboration, and Merging

Three people, one project: branches, issues, pull requests, rotated reviews, and resolving conflicts

1 Why branches (the five-minute case)

On Day One you worked alone on a single main branch: edit, commit, push, repeat. That is perfect for one person, but the moment two or three people touch the same project, everyone pushing straight to main becomes chaos — half-finished work lands on top of half-finished work.

A branch solves this. A branch is a private line of development that splits off from main. You can commit freely on your branch without disturbing anyone else, and only when your piece is finished and reviewed does it come back into main. Think of main as the clean, always-working version of the project, and branches as the workshops where new work happens safely off to the side.

Today three people build one dataset together. Each person owns one module, works on their own branch, and merges back through review. Along the way we meet conflicts — and learn that most of them are nothing to fear.

Our project, continued. We keep the hh-survey project from Day One, but now it is richer. The raw data has several modules: general household information, an education module, a consumption module, and an income module, all at the individual or household level. Our shared goal today: clean each module and merge everything into one final individual-level dataset, where each person carries their education, income, and their household’s consumption.

2 Setup: cloning and the username-keyed path block

Everyone starts from the same shared repository. Each person clones it to their own machine:

git clone <the shared repository URL>

Now the first practical problem. The data sits in a different folder on each person’s computer, so the do-file needs each person’s own working-directory path. We solve this with a conditional block keyed on the username near the top of the master do-file:

if "`c(username)'" == "aigerim" {
    global root "C:/Users/aigerim/hh-survey"
}
if "`c(username)'" == "daniyar" {
    global root "/home/daniyar/projects/hh-survey"
}
if "`c(username)'" == "saule" {
    global root "/Users/saule/work/hh-survey"
}

Because usernames are unique across the institution, each person’s branch runs only their own line at runtime — the paths never collide logically.

Our first, gentle conflict. When three people each add their own if-branch to the same spot in the same section, Git may still flag a conflict — not because anyone is wrong, but because the edits land on adjacent lines and Git only sees text, not Stata logic. This is the perfect first conflict: the resolution is simply keep all three blocks. It teaches the most important mindset of the day — a conflict is not an accusation. Sometimes it just means two people wrote next to each other.

3 One issue, one branch, one module

The work is organised by issues. Before anyone writes code, we open one issue per module, so the plan is visible and each task has a home:

  • Issue 1 — Clean the education module (individual level).
  • Issue 2 — Clean the consumption module (household total).
  • Issue 3 — Clean the income module (individual and household).

Each person takes one issue and creates a branch named after it:

git switch -c clean-education      # create and move onto a new branch
# ...edit the education section of the do-file...
git add .
git commit -m "Clean education module: recode levels, drop invalid grades"
git push -u origin clean-education

The three cleaning tasks live in different sections of the same do-file. Because they touch separate sections, they will merge back into main without conflict — this is the confidence-building stage. Everyone works in parallel, commits on their own branch, and pushes.

Practice now. Take your module. Create your branch, do the cleaning in your section, commit in small logical steps, and push your branch to GitHub. Do not touch main directly.

4 Pull requests and rotated reviews

A branch does not merge itself. To bring your work into main, you open a pull request (PR) — a proposal that says “please review these commits and merge them.” A PR shows the full diff of your branch, links to its issue, and gives a space to discuss.

The rule that makes this professional: nobody merges their own work. We rotate the reviewer around the circle, so each person reviews someone else’s PR:

  • Person A reviews and merges B’s pull request.
  • Person B reviews and merges C’s pull request.
  • Person C reviews and merges A’s pull request.

Reviewing means reading the diff, checking it does what its issue asked, leaving a comment, and then merging. When a PR merges, its issue is closed — often automatically by writing “Closes #1” in the PR description.

4.1 Calling each other by name

Collaboration is not just merging code — it is getting the right person’s attention at the right moment. On GitHub you do this with an at-mention: typing the at-sign immediately followed by someone’s username inside an issue or pull-request comment sends them a notification and links them into the thread. For example, in your PR description you might write “@daniyar this touches the education merge you wrote — can you review?”, or in an issue, “@saule I think the consumption totals here need your eyes.”

Two habits to build today:

  • In a pull request, name the reviewer you are handing off to, so the rotation is explicit and nobody wonders whose turn it is.
  • In an issue or comment, mention the person who owns the relevant module when a question or problem concerns their work, instead of hoping they notice.

The lesson: mentions turn a silent list of tasks into a conversation, and they are how professional teams pull each other’s attention to exactly the line, issue, or decision that needs it.

Because the three modules sit in separate sections, all three PRs merge cleanly. After the last merge, main holds everyone’s cleaning work together.

Practice now. Open a pull request for your branch, link it to your issue, and at-mention the person assigned to review you so they are notified. Then review the PR you were assigned: read the diff, leave one comment that at-mentions its author, and merge it. Watch the linked issue close.

5 The final consolidation — and a real conflict

Now the harder, more realistic step. Someone must add the final consolidation code that joins the three cleaned modules into one individual-level dataset — merging education, income, and household consumption onto each person.

Here we deliberately have two people edit the same merge lines at the same time, on different branches. When the second PR tries to merge, Git cannot decide which version wins, so it raises a genuine conflict — the emotional peak of the day. Unlike the username block, this one needs a human to think.

Resolving it, step by step:

git switch main
git pull                      # get the latest main
git switch consolidation
git merge main                # bring main's changes in; conflict appears

Git marks the clashing region with <<<<<<<, =======, and >>>>>>>. You open the file, read both versions, decide what the correct combined code should be, delete the markers, keep the right result, then:

git add clean_analyze.do
git commit                    # records the resolved merge
git push

The lesson: a real conflict is resolved by understanding both sides and writing the correct combined version — not by blindly picking one.

Live demo, then reproduce. The instructor resolves this conflict on screen. Then every participant runs git switch main, git pull, and executes the full do-file end to end to confirm the final dataset reproduces identically on their own machine.

6 Day Two recap

By the end of today you should be able to:

  1. Explain why branches keep main clean while parallel work happens safely.
  2. Set up a username-keyed path block and resolve the gentle conflict it can cause by keeping everyone’s block.
  3. Open an issue, create a branch for it, and do focused work in your own module.
  4. Open a pull request, and review and merge someone else’s PR — never your own.
  5. Use at-mentions in issues and pull requests to call a specific teammate’s attention to the work that concerns them.
  6. Resolve a real merge conflict by reading both sides and writing the correct combined result.
  7. Pull the merged main and reproduce the final dataset end to end.

Group challenge (homework). Repeat the whole cycle on a fresh set of modules of your own choosing: open three issues, work three branches, rotate three reviews, and engineer — then resolve — one deliberate conflict in the consolidation step. When main reproduces the final dataset for everyone, you have run a complete collaborative Git workflow from start to finish.