Recap: Where We Left Off

Forks vs Branches: Key Differences

Four Common Collaboration Workflows

For most research group projects: Feature branch workflow is the right balance.
For contributing to someone else’s repo: Fork & PR workflow.

See Advanced Topics for Gitflow details.

Workflow 1: Centralized

Everyone commits directly to main. Simple, but fragile.

Person A:  edit → commit → push → main ✓
Person B:  edit → commit → push → main ✗ (conflict!)

When it works:

• Solo researcher
• Very small team with near-zero overlap
• Quick one-off fixes

When it breaks:

• Two people edit the same file at the same time
• A mistake goes straight to the shared version
• No review step before changes take effect

Good Practices: When and How to Commit

Commit one logical change at a time

• Each commit should do one thing and be describable in a single sentence
• Don’t bundle unrelated edits (e.g., fixing a typo + restructuring a script)

Commit when the work is in a coherent state

• After completing a self-contained step: added a function, wrote a section, fixed a specific bug
• Not mid-sentence, not with broken code that won’t run
• Think: “If I had to revert to this commit, would it make sense?”

How often?

• More often is better than less — small commits are easier to review and revert
• A few commits per work session is normal; dozens is fine too
• Avoid “one giant commit at the end of the day”

Good Practices: Branches and Reviews

Branch naming

feature/add-exclusion-criteria
fix/typo-in-consent-form
docs/update-readme-methods

Use a prefix (feature/, fix/, docs/) so the purpose is clear at a glance.

Keep branches short-lived

• Merge or rebase against main frequently to avoid drift
• Delete branches after merging — they clutter the repo and create confusion

Review culture

• A review comment is not a criticism — it is a question or a suggestion
• Respond to every comment, even if just “Done” or “Disagree, here’s why”
• Approve when you are satisfied, not just when you are tired of reviewing

Good Practices: PR / MR Frequency

Not per commit, not per day — per logical unit of work

• Open a PR / MR when a self-contained piece of work is ready for review
• This might be a few commits or a few dozen — size matters more than time

Signs it’s time to open a PR / MR

• A feature, fix, or section is complete and coherent on its own
• You want feedback before going further
• The branch has diverged enough that merging later would be painful

Keep PRs / MRs small and focused

• One PR per feature / fix / task — not one PR for everything done this week
• Smaller PRs are reviewed faster and more carefully
• Large PRs (“mega-PR”) tend to get rubber-stamped

Rules of thumb

Anatomy of a Good PR / MR

Merge Strategies

For research work: merge commit is usually fine and most transparent.

Merge Conflicts: What They Are and How to Resolve Them

A conflict occurs when two branches changed the same lines of the same file differently.

VS Code — opens a visual editor automatically:

• Click Resolve in Merge Editor on the conflicted file
• Choose Accept Current, Accept Incoming, or Accept Both
• Save → click Complete Merge in the editor toolbar

GitHub Desktop — highlights conflicted files in red:

• Click Open in editor next to the conflicted file
• VS Code opens with the merge editor (same as above)
• After saving, return to GitHub Desktop → the file is now staged → Commit merge

RStudio — Git pane shows conflicted files with an orange U marker:

• Open the file — conflict markers (<<<<<<<, =======, >>>>>>>) are visible
• Edit manually to keep the correct version, delete the markers
• Stage the file in the Git pane → Commit

Project Structure for Shared Repositories

A clear structure reduces confusion for everyone:

my-project/
├── README.md          ← what is this, how to use it
├── data/
│   ├── raw/           ← never modified, version controlled
│   └── processed/
├── scripts/           ← analysis code
├── docs/              ← notes, pre-registrations, papers
├── results/           ← outputs (often in .gitignore)
└── CONTRIBUTING.md    ← how to contribute (for shared repos)

GitHub vs gitlab.nrw: Key Differences

Recommendation for CRC 1252:
Use gitlab.nrw for unpublished data and analysis; GitHub for public dissemination.

Common Pitfalls and How to Avoid Them

Further Reading

Beginner-friendly

• GitHub Skills: Introduction to GitHub — interactive, browser-based exercises
• GitLab tutorial: Make your first Git commit — step-by-step with screenshots
• git.nrw beginner level guide

Going deeper

• Pro Git (free book) — ch. 3 (branching), ch. 5 (distributed workflows)
• Atlassian Git tutorials — branching, merging, rebasing explained with visuals
• Oh Shit, Git!?! — plain-English fixes for common mistakes

For research specifically

• Happy Git and GitHub for the useR — Jenny Bryan’s practical guide, R-focused but broadly applicable
• The Turing Way: Version Control — research-oriented best practices
• Software Carpentry: Version Control with Git — self-paced lesson used in workshops worldwide