3. Introduction to git, GitHub and GitHub pages

Getting started with git for version control

Geert van Geest

2024-07-12

Versions

  • final_version.docx 🎉

  • final_version_corrected_supervisor1.docx

  • final_version_corrected_supervisor2.docx

  • final_version_tookmehourstocombineallcomments.docx 🤯

  • final_version_corrected.docx

  • ..

Take control of your versions!

  • Dare to break stuff ➡️ go back to any previous version
  • Define and describe changes
  • Combine versions and suggested changes by pull requests and merging

flowchart LR
  A(first version) --> B(some changes)
  B --> C(Something experimental)
  B --> D(Bug fix)
  C --> E(Merge)
  D --> E
  
  linkStyle 1,3 stroke:red;

Question

Using git for version control

  • At the level of a directory, typically a project
  • Everything needed for version control is in .git/
  • Commit: building block -> defined step through versions
  • Branch:
    • independent sequence of commits
    • typically merged with a main branch after work is done

flowchart LR
  A(first version) --commit--> B(some changes)
  B --new branch--> C(Something experimental)
  B --commit--> D(Bug fix)
  C --> E((Merge commit))
  D --> E
  
  linkStyle 1,3 stroke:red;

Committing changes - 2 steps!

  1. Stage: Pick files with changes or files to be tracked

git add index.qmd

  1. Commit: Create a new ‘version’ with a good description

git commit -m "Adds a paragraph"

Stage and commit in one command:

git commit -am "Adds a paragraph"

Project status

  • Overview of changes and staged files in workdirectory:

git status

  • Get overview of commits with their hashes:

git log --oneline

Undoing changes

  • Remove unstaged changes:

git restore index.qmd

  • Retrieve a file version after a commit (unstaged in working directory):

git restore --source fa4f3deac index.qmd

  • Reset commits:

git reset [--soft|--hard|--mixed] fa4f3deac

Collaborating with git

  • Sync with a remote (e.g. on GitHub)

  • All commits are associated with a user

  • If you’re collaborating:

    • Make sure to sync with the remote regularly (git pull + git push)

    • Work with branches and pull requests

Creating a remote repository

  • Create an empty repository on GitHub

  • Link your local repository to the created repository:

git remote origin https://github.com/OWNER/REPOSITORY.git

  • Push your local repository to the remote:

git push -u origin main

Ignoring files

  • .gitignore enables you to not version control files, e.g.:
    • output files
    • user-specific files
  • For a typical quarto project, that would be e.g.:
    • _site/
    • .Rproj.user

Tags and releases

  • Tag a special commit

  • Typically this is done to create versions, e.g. v1.0.0

  • With git tag or creating a release in GitHub

  • For Zenodo: a DOI is linked to a release

flowchart LR
  A(commit 1) --> B(commit 2)
  B --> C(commit 3)
  C --> D("commit 4 
        tag:v1.0.0")
  D --> E(commit 5)
  
  style D fill:#f9f,stroke:#333,stroke-width:4px

Question

Quarto and GitHub

  • Work in the main branch - contains the source files

  • Use quarto publish gh-pages to:

    • Create a branch called gh-pages and push the rendered html files

    • Tell GitHub to use the files in gh-pages to host it as a website

  • Find your website at OWNER.github.io/REPOSITORY 🚀

Quarto and GitHub actions

  • GitHub actions: jobs running on the GitHub server that can be triggered by e.g. a push, merge, cron job etc.

  • Let GitHub actions render the content - ultimate reproducibility

GitHub actions

  • .github/workflows/my_workflow.yml

  • For most purposes steps have predefined actions

name: Install R

on:
  push:
    branches: main
    
jobs:
  my_job:
    runs_on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.3.1'

More git