ETC5513: Collaborative and Reproducible Practices

Workshop 5

Author

Michael Lydeamore

Published

3 April 2025

🧭 Quarto Cross-Referencing and .gitignore Workshop

In this workshop, you’ll learn:

  1. How to cross-reference sections, figures, code chunks, and tables in Quarto.
  2. How to use a .gitignore file to keep unnecessary files out of your Git repository.
library(ggplot2)
library(palmerpenguins)

✍️ Part 1: Cross-Referencing in Quarto

Quarto lets you easily refer to other parts of your document, like code, figures, and sections — just like in academic papers.

Let’s walk through some examples using the palmerpenguins dataset.

🔗 1. Referencing Sections

Any heading can be cross-referenced by adding an ID to it:

## Data Cleaning {#sec-cleaning}

Now you can refer to it elsewhere like this:

See Section @sec-cleaning for details on how the data was prepared.

🖼️ 2. Referencing Figures

To reference a figure, give it a label and caption:

```{r}
#| label: fig-bill
#| fig-cap: "Bill length vs flipper length"
ggplot(penguins, aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point()
```

Then reference it:

Figure @fig-bill shows the relationship between flipper length and bill length.

📊 4. Referencing Tables

You can also label tables:

```{r}
#| label: tbl-summary
#| tbl-cap: "Summary statistics of the penguins dataset"
knitr::kable(summary(penguins))
```

Then refer to it like this:

See Table @tbl-summary for summary statistics of the dataset.

✅ Try It Yourself:

  • Create a section, figure, and code chunk using the penguins data
  • Give each one a label
  • Add a sentence that references each one

🚫 Part 2: Ignoring Files with .gitignore

When using Git, you often don’t want to track certain files (e.g., temporary files, data, or system files). That’s where .gitignore comes in!

🗂️ 1. What is .gitignore?

A .gitignore file tells Git what to ignore — Git will pretend these files don’t exist.

Example contents of .gitignore:

.Rproj.user
*.html
*.csv
.DS_Store

This would ignore:

  • RStudio project files
  • All .html and .csv files
  • macOS system files

🛠️ 2. Create and Use .gitignore

  1. In your project folder, create a file called .gitignore
  2. Add the files or patterns you want Git to ignore
  3. Save the file
  4. Add a CSV file to your project folder
  5. Check what Git sees:
git status

✅ If the ignored files aren’t listed, .gitignore is working.

⚠️ Important Note

If you already added a file to Git before putting it in .gitignore, Git will still track it.

To stop tracking it:

git rm --cached filename.csv

Then commit:

git commit -m "Stop tracking filename.csv"

✅ Summary

  • Use .gitignore to keep your Git repository clean
  • Avoid committing files like datasets, HTML outputs, or IDE settings
  • Helps keep collaboration and version control simple

🎉 Great job — your Git repo is now cleaner and more professional!

📦 Mini Exercise: Using git stash

Sometimes you make changes in your working directory, but you’re not ready to commit them — and you need to switch branches or pull updates. git stash lets you save your changes temporarily without committing.

🛠️ Goal

Learn how to: - Save changes using git stash - Switch branches safely - Reapply your stashed work

🧪 Step-by-Step Instructions

  1. Make sure you’re inside a Git-tracked project (any project will do).

  2. Open a file and make some changes — but don’t commit yet.

  3. Check your Git status:

git status

You should see the file listed as modified.

📦 1. Stash Your Changes

Run:

git stash

✅ This saves your changes and returns your working directory to a clean state.

🔄 2. Switch Branches (or Pull)

Now try switching to another branch:

git checkout main

Or do a pull:

git pull

✅ Your working directory stays clean — no conflicts!

♻️ 3. Reapply the Stash

When you’re ready to bring back your changes:

git stash apply

✅ Your edits will be restored to the files you changed.

🗑️ 4. (Optional) Clear the Stash

After applying, you can remove the stash:

git stash drop

Or, to both apply and drop in one step:

git stash pop

✅ Try It

  1. Modify a file
  2. Run git stash
  3. Switch branches
  4. Return to your branch and run git stash apply
  5. Confirm your changes are back
  6. Commit if needed!

🎉 You’ve learned how to pause your work safely and come back to it later!