18  Collaborating with Others

This chapter covers how to work on projects with collaborators using Git and GitHub.

18.1 Sharing a Project

18.1.1 Giving Access

On GitHub:

  1. Go to repository Settings → Collaborators
  2. Click Add people
  3. Enter collaborator’s GitHub username or email
  4. They’ll receive an invitation

18.1.2 Collaborator Setup

Your collaborator clones the repo:

git clone https://github.com/USERNAME/project-name.git
cd project-name

Then sets up environments:

# Python
conda env create -f environment.yml
conda activate project-name

# R (in R console)
renv::restore()

18.2 The Collaboration Workflow

18.2.1 Before Starting Work

Always pull the latest changes:

git pull

Check for environment updates:

# Python - check if environment.yml changed
conda env update -f environment.yml

# R - check renv status
# renv::status()
# renv::restore()

18.2.2 Making Changes

  1. Pull latest changes
  2. Do your work
  3. Stage and commit
  4. Push
git pull
# ... make changes ...
git add .
git commit -m "Add analysis for condition B"
git push

18.2.3 When Collaborators Push

If someone pushed while you were working:

git pull
# May need to resolve conflicts (see below)
git push

18.3 Branching Workflow

For larger changes, use branches:

18.3.1 Create a Branch

git checkout -b my-feature

18.3.2 Work on the Branch

# Make changes, commit as usual
git add .
git commit -m "Add new analysis"

18.3.3 Push the Branch

git push -u origin my-feature

18.3.4 Create a Pull Request

  1. Go to the repository on GitHub
  2. Click Compare & pull request
  3. Add description of changes
  4. Request review from collaborator
  5. Merge when approved

18.3.5 After Merging

git checkout main
git pull
git branch -d my-feature  # Delete local branch

18.4 Handling Merge Conflicts

Conflicts happen when two people change the same lines.

WarningClaude Code

Claude Code can explain merge conflicts and help you resolve them safely.

I have a merge conflict in analysis.qmd with these conflict markers: [paste the conflicting section]. My collaborator changed the threshold. Which should I keep?

Show the conflict markers and explain the context. Claude can help you understand what each version does and decide how to resolve it.

18.4.1 Recognizing a Conflict

git pull
# CONFLICT (content): Merge conflict in analysis.R
# Automatic merge failed; fix conflicts and then commit.

18.4.2 Resolving Conflicts

Open the conflicted file. You’ll see markers:

<<<<<<< HEAD
# Your version
result <- calculate_mean(data)
=======
# Their version
result <- calculate_median(data)
>>>>>>> origin/main

Edit to keep what you want:

# Keep both approaches, or choose one
result_mean <- calculate_mean(data)
result_median <- calculate_median(data)

Remove the conflict markers, then:

git add analysis.R
git commit -m "Resolve merge conflict in analysis.R"
git push

18.5 Environment Synchronization

18.5.1 When You Add Packages

Python:

conda install new-package
conda env export > environment.yml
git add environment.yml
git commit -m "Add new-package to environment"
git push

R:

install.packages("new-package")
renv::snapshot()
git add renv.lock
git commit -m "Add new-package to renv"
git push

18.5.2 When Collaborator Adds Packages

After pulling:

Python:

conda env update -f environment.yml

R:

renv::restore()

18.6 Best Practices

18.6.1 Communicate

  • Tell collaborators what you’re working on
  • Avoid working on the same files simultaneously
  • Use issues to track tasks

18.6.2 Commit Often

Small, frequent commits are easier to merge than large changes.

18.6.3 Pull Before Push

git pull
git push

This catches conflicts early.

18.6.4 Use .gitignore

Ensure everyone has the same .gitignore to avoid committing:

  • Large data files
  • Personal IDE settings
  • System files

18.6.5 Document Changes

Update README and documentation when you change:

  • How to run the analysis
  • Environment dependencies
  • Data requirements

18.7 Working with GitHub Issues

18.7.1 Creating Issues

Use issues to track:

  • Bugs to fix
  • Features to add
  • Questions to resolve

Click New Issue on GitHub and describe the task.

18.7.2 Referencing Issues in Commits

Link commits to issues:

git commit -m "Fix normalization bug (closes #12)"

This automatically closes the issue when merged.

18.8 Forking (For External Collaborators)

If someone isn’t a direct collaborator:

  1. They fork the repo (creates their copy)
  2. They make changes in their fork
  3. They open a pull request to your repo
  4. You review and merge

This is common for open-source contributions.

18.9 Checklist for Collaboration

Starting a collaborative project:

Daily workflow: