scnlf.me/2025-12-01-supergit

git gives you superpowers

(+ licensing your software)

@samcunliffe and @mscroggs

CDT CCMI Software Engineering Fundamentals, 90 High Holborn. 2025-12-01.

Our plan for today

0. Commit cleanliness.
1. Log, checkout.
2. Branching, merging, rebasing.
   • Using a UI to look at branches.
3. Revert, soft reset, hard reset, force push.
4. Collaboration, pull requests, bug reports, ettiquette.
   • Co authoring commits, credit.
5. Choosing a license.

Labouring the superhero and scifi analogy

0. ...
1. Time travelling.
2. Alternate universes.
3. With great power comes great responsibility.
4. Superhero teamups!
5. ...

A few ice-breaker questions...

menti.com/ alyib1bai6nh

Or enter code: 1276 2603

0. Staging area, and commit cleanliness

• Commits should be logical, atomic units of change that represent a specific idea.

• But, not all humans work that way.

• Use --amend to fix things...

  git add a_file another_file  # two files on the stage
  git commit -m "Fix somthing."  # typo in commit message
  git add forgot_this_file
  git commit --amend  # add forgotten files or fix typos
  

• Use the --staged diff to check...

  git diff --staged
  git diff HEAD~1  # What does this do?
  

• Bypass the staging area with -a,--all.
  Commits all changes to all tracked files:

  git commit --all -m "I'm very confident"
  

Good commit messages

Short descriptive and less than 50 characters

Short descriptive and less than 50 characters

A longer message that explains WHY the change was made in detail. Also
wrapped at 72 characters. Many editors will do this for you but if not,
it's worth remembering to do it manually.

Another paragraph is fine if you need it.

Co-authored-by: Matthew Scroggs <mscroggs@users.no-reply.github.com>

Quick warm-up exercise

Rank these commits on cleanliness:

1. Time travelling

(Understanding git log and git checkout)

• This is Linus.
• He started the Linux kernel project.
• He started the git project.
• ...because he needed something for collaborating on the kernel.
• The software project git was kept in git from quite early on.
• Remember the human on the internet.

Demo: let's look at git's history in git.

• The Git source code repository

• Look at the recent history:

  git log 
  git log --oneline
  

• Look at the first commit:

  git log --reverse
  

• Actually travel back in time to an old commit:

  git checkout <commit-hash>
  git checkout <branch-name>  # go back to the future
  

2. Parallel universes

(git branch, git merge, git rebase, and looking at branches)

• List all branches:

  git branch
  

• Create a branch without switching to it:

  git branch <branch-name>
  

• Create a new branch and switch to it:

  git checkout -b <branch-name>
  git switch --create <branch-name>  # git 2.23+
  

• Switch between branches that already exist:

  git checkout <branch-name>  # or switch since git 2.23
  

Demo: visualising branches

• Make a nice terminal graph:

  git log --graph --all --decorate --oneline
  

Exercise: creating a branch and a merge conflict

Exercise instructions

Exercise (time permitting): rebasing

Exercise instructions

Merging

• Merging a branch into main:

  git checkout main
  git merge <branch-name>
  

  • All commits from the feature branch are preserved.

• Squash merging a branch into main:

  git checkout main
  git merge --squash <branch-name>
  git commit -m "A single commit message for all changes"
  

  • Combines all changes from the feature branch into a single commit.

The grand important internet battle:

Merge by commit or squash and merge?

• I'm on team squash.
• Provided everyone's careful about attribution.

3. With great power comes great responsibility

(git reset, git push --force when and when not to)

The safest way to undo things

• Whether or not you've pushed:

  git revert <commit-hash>
  git revert HEAD~1  # This again!
  

  • Makes a new commit that undoes the changes.

• If you haven't pushed yet, you can also use reset:

  git reset --soft <commit-hash>  # keep changes staged
  git reset --hard <commit-hash>  # discard changes
  

  • Moves the branch pointer to an earlier commit.
  • Can also use HEAD~1 etc.

Force pushes

• Either rebaseing or resetting after pushing needs a force push.
• Force pushes rewrite history.

• 

  git reset --mixed HEAD~1
  git commit --amend -m "A better commit message" 
  git push --force-with-lease
  

• This can mess up other people's work.

  git reset --hard HEAD~1  # obliterate the last commit
  git push --force
  

Force pushes

• Don't fear the force push.
• But also, don't do it if you don't need to.
• A rule of thumb: if you're doing it more than once per month you've got a very strange workflow.

A MUCH BETTER option

--force-with-lease

You almost always should be using that.

Or:

1. create a new branch for your rewritten history;
2. rebase the new branch;
3. and push that instead.

4. Superhero teamups!

Collaboration, pull requests, bug reports, etiquette

Jargon

• Repo: A Git repository. "GitHub repo" == Git repository on GitHub.

• Org: GitHub organisation.

• Fork: A copy of a repository in your own GitHub account or organisation.
  Also a verb:

  we've forked that repo into our org

• PR: Pull request. MR: Merge request (GitLab).

• CI: Continuous integration (automated tests that run on each PR).

  The CI is broken! Please fix the CI for this

GitHub

• A website for hosting Git repositories (a "forge")

  • Very widely used. Lots of nice features.
  • @UCL, @imperialcollegelondon and this @CCMI-CDT use it.

• There are other options. Here are some...

Quick warm-up exercise

Rank each of these bug reports...

• There are lots of nice features in GitHub issues and GitHub projects.
• No spoilers here: they'll be covered on Friday.

Activity: add yourself to the CCMI CDT website

• Your CDT has a website.
• The source code that builds the website is in a Git source code repository.

1. Clone to your computer.
2. Create a branch and switch to it.
3. Add yourself like this.
4. Commit changes and push to your branch.
5. Open a pull request.
6. Review someone else's PR.
7. Squash merge!

Sam and Matt's tips for collaborating on GitHub

• Read the CONTRIBUTING guidelines
  • Or chat with collaborators and agree on some (can change them later).
• Open draft pull requests early.
  • If in doubt, get feedback and ask for help.
• When you're pull request is ready:
  • Make sure the descriptions are clear and you've linked any issues.
  • Make sure tests and linters pass.
  • Review it yourself.
  • (Maybe contentious) Ask @Copilot to review it.
  • Then mark it as ready for review and request reviews from humans.

Working together

• Two people together at one keyboard or coding together over a video call.
• Screen sharing, pair programming tools (VS code live share).
• Share credit with co-authored commits:

git commit -m "A commit message

Co-authored-by: Matthew Scroggs <mscroggs@users.no-reply.github.com>"

5. Choosing a license

Open source

• Open source initiative defines 10 things that make a project open source.
• If you're writing research code for funded research you may have to open it.
• If you're working on a project with an industrial partner: check first.
• As students you normally retain intellectual property of your work
  (policies: UCL, Imperial).

• We tend to work "open by default".
  • More secure?
  • Easier to debug.
  • Easier to collaborate.
  • Easier to cite and get credit.

Sam and Matt's tips for choosing a license

Browse choosealicense.com

• Think about this at the start of a project.
• Use an OSI approved license (don't write your own).
• Go as permissive as you can.
• Be aware of GPL code and linking against GPL libraries.
• Follow your community’s normal license if you don’t have some reason to do something else.

The main ones

Public code but no license?

Here's what choosealicense.com says

Conclusions

• git is a really useful tool and you'll probably use it all the time.
• GitHub is a place where a lot of code is, and yours will probably go there too.
• Working together is much more fun.
• Think about licenses.

Extras

Git worktree

• Branching is great.
• Working on something, get a critical bug report
  (or your supervisor turns up and asks for something specific).
• What do you do?

• Commit your (messy) changes, or stash them, switch branches...

  git commit -m "WIP: messy changes"
  git push  # push to a remote
  git switch --create supervisor-request-branch
  # do some work
  

• When you've finished...

  git commit -m "Do supervisor request"
  git push
  git switch what-i-was-doing-before
  git reseet --soft HEAD~1 # get back to messy changes
  # ...
  

• Then they come back with some PR review comments or (worse) in person to sit over your shoulder...

  git commit -m "WIP: messy changes" # again
  git push # probably doesn't work because we pushed and reset before
  git push --force-with-lease
  git switch supervisor-request-branch
  

git worktree makes this less painful

• Been around in git for a while.
• Not really used much.
• Multiple checkouts from the same repository.
  • Like having multiple clones but easier to create and throw away.
• Let's replay the supervisor example...

• Supervisor turns up...

  git worktree add ../supervisor-request-branch
  cd ../supervisor-request-branch
  # do some work
  

• When you've finished...

  git commit -m "Do supervisor request"
  git push
  cd ../original-repository
  # back where you were before
  

• Then they come back with more requests...

  cd ../supervisor-request-branch
  

Some worktree tips

• Conventions

  git worktree add ../<something>
  

  vs

  mkdir .worktrees
  git worktree add .worktrees/<something>
  

• By default the last thing in the path is a branch name (it will create it if it doesn't exist).

• To checkout a specific branch with a different worktree directory name:

  git worktree add ../i-prefer-to-name-directories [-b] <branch-name>
  

• List them:

  git worktree list
  

• Remove them:

  git worktree remove ../supervisor-request-branch
  

• Nice to quickly make a worktree, leave it for a while, then remove it when done.

  • Reviewing PRs (and you want a checkout to test something).
  • Bugfixes.

Contributing guide

CONTRIBUTING.md

• Conventionally SHOUTED at the root of a repository.
• Explains how to contribute to the project.
• A good idea to write one yourselves when starting a new collaborative project together.
• Doesn't need to be long. Just write down what is expected.

Things to think about

• Do you want people to fork and PR, or work in branches in the main repo?
• Branch naming convention?
  {feature/xyz, bugfix/abc, hotfix/123} or user prefix {sc/fix-bug-1337, ms/add-feature-42}.
• Who merges PRs? (The reviewer? The PR author?)
• Should you squash merge or not?
• Code style guidelines? Linters?
• How do you want bugs to be reported?
• How do you want features to be requested?
• Internal vs external collaborators.