Structuring a git workshop: Idea

This is how I would like to structure a git workshop if I had to prepare one.

The structure of the workshop is thought to be split on three different sessions, separated by at least one day, although possibly it's better to leave a week between them:

Session 1: Using git "Single player mode"

This first session allows anyone to use git on his/her personal projects, backing them up on github/gitlab. It gives enough autonomy so people can start using git by themselves, earning the convenience of "backing up" the code on private gitlab projects, and using gitlab to browse previous commits if they need to. Branches, merge requests, conflict resolution, forking, collaborators, continuous integration are intentionally left out of this first session.

  • What is git
  • Set up git
  • Basic git commands to use git alone and locally:
  • Start: git init
  • How things are: git status
  • Tracking stuff: git add, git rm, git commit
  • Browsing commit messages, seeing differences between commits, "going temporarily to the past": git log, git diff, git checkout
  • Ignoring files: .gitignore
  • (Optionally) IDEs: jupyterlab with git plugin, vscode, RStudio
  • Intro to either Github/Gitlab/Bitbucket
  • Creating a repository/project on github/gitlab
  • Basic git commands to use git alone and remotely: git push/pull/clone
  • Conventions: README.md

Session 2: Using git with others

This second session focus on how to use git with other people. After this session the attendant should be able to create a branch and merge it back, create an issue, submit a merge request, invite collaborators to a repository on gitlab, forking other people's repositories. He/She should be given advice on how to structure commits so they are self-contained and reviewable, how to write commit messages that are useful to others, what to write on a pull/merge request message.

  • Branching and merging: git checkout -b feature-my-new-feature, git merge
  • Github/Gitlab:
  • Creating and managing issues
  • Creating and merging a pull request
  • Inviting collaborators / Introduction to gitlab groups
  • Forking read-only repositories and submitting a merge request to them
  • Best practices on:
  • Commits: Small "a single minor thing", self-contained "deal with one thing at a time".
  • Commit message: First line: short summary. Next paragraph: Motivation/General Idea. Closing issues from commit messages.
  • Pull request: A good description
  • Issue: Reproducible example, expected results, use of screenshots
  • Contributing with others:
    • Respect code style
    • Aesthetic code contributions (changing spaces/indentation...) should not be mixed in the same commit with other code changes.
  • (Optionally) Intro/Mentioning continuous integration

Session 3: More advanced git commands

This third session focuses on more advanced git commits or less crucial commands, as well as rewriting history commands.

The attendant will be able to quickly revert a commit, tag important commits to give them version numbers, go back to a previous commit and forget about anything newer than it, rewrite the history, pushing rewritten histories and their consequences, stashing commits blaming and bisecting.

Overall there are either easy, non-essential commands, rewriting history commands (git reset --hard, git rebase, git push -f), and convenient commands to deal with issues (git blame, git bisect).

  • Other convenient commands:
  • Undo a change (git revert)
  • Tag important commits (git tag)
  • Other commands (git cp, git mv)
  • Taking a quick&dirty local snapshot (git stash)
  • Rewriting history
  • Undo a change, strong version (git reset --hard)
  • Rewrite history (git rebase, git rebase --interactive)
  • Force push
  • Managing issues
  • Find the author of that piece of code: git blame (and blame on github/gitlab)
  • Find the commit that introduces a bug: git bisect