Basics in git, working alone

Marie-Pierre Etienne

https://github.com/MarieEtienne/reproductibilite

2025-09-10

Introduction to git

What is it?

  • Developed by Linus Torvalds: “I’m an egotistical bastard, and I name all my projects after myself. First Linux, now git.”
  • Git is a version control system (the most widely used today).
  • It allows tracking all changes made to code since its creation.
  • Git is incredibly efficient.

Starting from an existing directory

Cloning an existing reprository

This means copy locally on your computer the content of a repository which means

  • copy the actual code and text contents
  • copy the history of all changes

We will be using Git in CLI. The relevant command in CLI are given in the survival kit. The most useful git command will be discovered during the course

Cloning an existing reprository

Go to your git Directory and write

git clone git@github.com:MarieEtienne/OCR_TP.git

What is happening ?

ls
cd OCR_TP
ls

Where to find this magical address to clone

Navigate to the repository you want to clone On the main page, click on the “Code” green button, be sure to select SSH and copy paste the address.

Reviewing the code development

git log
  • Shows the full history: commit hash, author, date, message
  • Most recent commit first
git log --oneline
  • Same history, condensed to one line per commit (short hash + message)
  • Much easier to scan when the history grows
gitk
  • Graphical viewer for the same history

Possible problems with gitk

macOS

brew install git
brew install git-gui
  • Verifying : which gitk
  • Xcode CLT only does not include gitk
  • If error with Tk :
brew install tcl-tk

Vérification

gitk --all

Visualizing the commit tree

Each commit points to its parent — this is what git log is walking through, one line at a time:

%%{init: { 'theme': 'neutral' } }%%
gitGraph
   commit id: "Initial commit"
   commit id: "Add README"
   commit id: "Fix typo"
   commit id: "Add Penguins_chapter.qmd"

  • git log --oneline shows this same sequence, most recent on top
  • We’ll come back to this graph once branches enter the picture

Forking an existing repository

What is forking?

Forking creates your own copy of someone else’s repository in your GitHub account. This lets you experiment with changes without affecting the original project. How to fork a repo:

How

Navigate to the repository you want to fork on GitHub Click the “Fork” button in the top-right corner of the repository page Choose where to fork it - usually to your personal account Wait a moment - GitHub will create the copy in your account

What happens next:

You’ll have a complete copy of the repo in your GitHub account You can clone this forked version to your local machine using git clone Make changes, commit them, and push back to your fork If you want to contribute back to the original project, you can create a pull request

Key points

Your fork is independent of the original repo. You have full control over your forked version The original repo remains unchanged unless you submit a pull request that gets accepted You can sync your fork with the original repo later if it gets updated

This workflow is essential for contributing to open-source projects or collaborating on code when you don’t have direct write access to the original repository.

Exercise

Creating new content

Your first commit

  • Open the file Penguins_chapter.qmd and add your name and the list of authors, then save your file.
  • Type the command git log in the console.
  • Enter the following commands:
git status # project status
git diff

  • Type the command git add Penguins_chapter.qmd, then repeat the previous commands.

  • Type the command git commit -m "Added an author", and once again check the project status.

  • Check the project on Github

  • Type the command git push", and once again check the project on Github

Identifying files to be committed

  • Make a small change in Penguins_chapter.qmd

  • Render the website locally with quarto renderand examine the contents of your directory.

  • Use git statusto identify the status of each file

  • Which files should be commited

  • The role of the .gitignore file

  • Add _site/ to the list of ignore files, then add .gitignore and commit.

. . . Generated files should not be versionned

Branches

What is a branch?

  • A branch is just a movable pointer to a commit
  • main (or master) is the default branch — the one you’ve been committing to so far
  • A new branch lets you work on something (an experiment, a fix, a chapter) without touching main until you’re ready

%%{init: { 'theme': 'neutral' } }%%
gitGraph
   commit id: "Initial commit"
   commit id: "Add Penguins_chapter.qmd"
   branch feature
   checkout feature
   commit id: "Try something new"
   checkout main
   commit id: "Fix typo"

  • main keeps moving forward on its own
  • feature diverges from the commit it was created on

Creating and listing branches

git branch          # list all local branches (* marks the current one)
git branch new_branch   # create a new branch (does NOT switch to it)

Switching branches

git switch new_branch   # move to an existing branch
git switch main          # move back
  • git switch changes which branch you’re working on — your files in the working directory are updated to match that branch
  • Shortcut: create and switch in one command
git switch -c new_branch

Note

You may see git checkout new_branch used for the same purpose in older tutorials — git switch is the newer, clearer command introduced specifically to replace this use of checkout.

Walking through past commits

Every commit in git log --oneline has a short hash/name (e.g. a1b2c3d) — you can jump straight to it, not just to a branch:

git log --oneline        # find the hash you want
git switch --detach a1b2c3d   # move to that exact commit
  • Your files now look exactly as they did at that commit
  • This is called detached HEAD: you’re not on any branch anymore, just visiting a point in history

%%{init: { 'theme': 'neutral' } }%%
gitGraph
   commit id: "Initial commit"
   commit id: "Add README"
   commit id: "Fix typo"
   commit id: "Add Penguins_chapter.qmd"

  • e.g. git switch --detach to the “Fix typo” commit lets you look around as if you were back at that moment

Coming back

git switch main
  • Leaves the detached HEAD and returns to the tip of main

Important

If you commit while in detached HEAD and then git switch away without creating a branch first, that commit becomes hard to find again. If you want to keep working from a past commit, create a branch from there:

git switch --detach a1b2c3d
git switch -c new_branch_from_past   # now it's safe to commit

Peeking without moving

If you just want to see what a file looked like at a given commit, without leaving your current branch:

git show a1b2c3d:Penguins_chapter.qmd   # print the file as it was then
git diff a1b2c3d main                   # compare that commit to now

Exercise

  • git branch — check which branch you’re currently on
  • git switch -c try_something — create and move to a new branch
  • Edit Penguins_chapter.qmd (any small change), then git add and git commit your change
  • git log --oneline — see your new commit
  • git switch main — go back to main
  • git log --oneline — notice your last commit is not here: it only exists on try_something
  • git switch try_something — go back and check it’s still there
  • git log --oneline — pick the hash of an earlier commit
  • git switch --detach <hash> — visit it, open Penguins_chapter.qmd, check its content
  • git switch try_something — come back to the present