Skip to content

Technical Guides ‐ Git

Jump to bottom
Jonathan Sharpe edited this page Oct 2, 2024 · 4 revisions

Git

📋 Description

Git is a distributed version control system (DVCS). You can interact with it via the git CLI, or various GUI tools including the GitHub web interface.

It's a very powerful tool, but if misused can create very confusing results.

✅ Do

Know your repo state

Keep track of what state your repository is in by regularly running git status and carefully reading what it says.

Run git status frequently, as often as between every other command you're running, to make sure you know exactly what changes you're making. Keep an eye on which branch you're on, which files you've changed (and which you've added that aren't yet being tracked) and which changes are staged (i.e. prepared for inclusion in the next commit). If you see something unfamiliar or unexpected (e.g. "You are currently rebasing.") make sure you stop, understand and resolve it before trying to keep working on top of it - in the worst case, your work may become unrecoverable otherwise.

🤔 Consider

Configuring git

Adding some configuration to create aliases and override some less helpful default behaviour can make using the git CLI much easier.

For example, you can run the following as a shell script on Linux/macOS:

#!/bin/sh

## Aliases - selected from https://github.com/pivotal/workstation-setup
git config --global alias.ci commit
git config --global alias.co checkout
git config --global alias.ds "diff --staged"
git config --global alias.lg "log --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative"
git config --global alias.st status

## Config - selected from https://jvns.ca/blog/2024/02/16/popular-git-config-options/
git config --global branch.sort "-committerdate"
git config --global diff.algorithm histogram
git config --global diff.context 10
git config --global log.date iso
git config --global merge.conflictstyle zdiff3

This will give you a few shortcuts to do frequent actions with fewer keystrokes (try using git st instead of git status, for example) and some other selected configuration.

GUIs

It can be helpful to use a tool that can give you a more graphical interface to your branches and commits. But remember: the git CLI works everywhere, you might not always have access to other UIs.

For example, you may already have GitHub Desktop installed from the CYF course. Many IDEs (including Visual Studio Code and e.g. JetBrains' WebStorm) have their own version control integration. There are also specific tools optimised around working with git in and out of GitHub, like Tower and GitKraken.

❌ Don't

Write meaningless commit messages

Think of commit messages like comments - they should add context telling the reader why those changes were made.

Although you can use the --message/-m option to add the message inline, it's easier to write a good, multi-line commit message with sensible line lengths in an actual text editor (it's usually something lightweight like vim or nano by default, but you can use e.g. VS Code for this too).

Just commit everything

git add . is the easiest way to make a commit but also the easiest way to include things you didn't intend to! Be the first reviewer of your own work, give yourself the chance to spot simple errors or e.g. debugging code you've left lying around.

Use the --patch/-p option to interactively review each change and decide what you want to stage for the next commit. This will show you all of your changes bit-by-bit and for each one give you the option to:

  • y stage the change
  • a stage the change and subsequent changes in the same file (useful for generated files like e.g. package-lock.json or yarn.lock)
  • n don't stage the change
  • d don't stage the change or subsequent changes in the same file
  • q stop reviewing changes

If you've created new files, you'll see the following in your status:

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        # ... files and directories

So that these will be included as part of what you're reviewing, use the --intent-to-add/-N option; run e.g. git add -N <files-or-directories> to start tracking those files, but not stage all of their content without review.

📚 Resources

Clone this wiki locally