The Git Workflow
Overview
This guide explains the basic workflow for using the command line git client.
Before you start
Before you start working with the git command line client, ensure:
- You have installed Git
- You have setup a suitable means of authentication (eg, ssh keys or access tokens)
The Git CLI Workflow
Although Git is a very powerful tool, with many advanced and ‘power user’ features, getting started is very streight forward. You only need to know a handful of commands.
Clone the respository
Before you start working, you need a copy of the code to work on. Downloading a repository for the first time is called ‘cloning’ it. Once we have cloned the repository onto the computer we are using, we don’t need to worry about this in the future - we just use the same copy.
git clone <git url goes here>
There are two main types of URLs you are likley to encounter when dealing with Git servers:
- SSH
- HTTPS
The difference between these isn’t particularly important for using Git. For our purposes, the biggest difference is how authentication is handled. SSH uses keys, where HTTPS generally uses some form of username and password. I tend to prefer SSH (as it tends to be easier to manage at scale), but either will work.
The Git workflow
The standard development cycle looks something like this:
Although I’ve referenced ‘server’ in this workflow, unlike some version control systems, Git does not rely on a server to work. You can use git for code that never touches a Git server, and many projects do. You can also have code stored on more than one Git server (mirroring) - if you want to keep a copy elsewhere.
Getting Changes
Before we start working, we need to make sure that people haven’t changed the project since the last time we worked on it. This is called ‘pulling’.
git pull
Most of the time, this should ‘just work’ and we’ll have a local copy of the repository. However, we have made changes that we forgot to push and our copy is very different, this might result in something called a ‘conflict’ - don’t worry, it’s reasonably easy to deal with, but we’ll cover this later when we talk about pushing.
Make Changes
Our main way of interating with Git will be to keep track of what changed (and who changed it). So the next step in the process is to make changes. Depending on the project, and the changes being made this step can very wildly. This is basically just, “do what you ordinary do when programming”.
When working in version control, we group work into blocks called ‘commits’. How how much work should go into a ‘commit’?
Generally, you want a commit to be one ‘unit of work’ which is not too big, and not too small. This is more of an art than a science, but lets look at some examples:
- Adding a new (small) feature
- Fixing a bug
- Getting a function to work
- Adding a new class
Generally, an ideal commit should be something you could explain to someone susinctly, and makes sense to be applied or rolled back ‘in one go’. If the commit is too big or too small, it can be tricky to figure out exactly what has changed and why. Don’t worry too much about this right now - it’s something that gets easier with practice.
With very few exceptions, once we have declared something to be a ‘commit’ we don’t change it - we have ‘committed’ to this being a unit of work for this project. Once we have given this commit to other people, altering it will break things (we can always add more commits that build upon or remove what we have added).
You can ’tidy up’ commits before you publish them, but it’s a bit fiddly and can result in a bit of a mess - definately something to avoid when you’re just getting started.
Test your changes
I would recommend testing at this point. Testing isn’t something people always do – they should, but they don’t always.
Why would we test before we ‘commit’ our work? Well, as I said in the above section - altering a commit is generally considered bad practice. If we commit broken code, then we’ll need to make a new commit which ‘fixes’ it.
It’s not uncommon in projects to see a string of commits that look like this:
- Added the ability for the player to jump
- Fixed the ability for the player to jump
- Fixed the fix for the ability to the player to jump
- Rewrote jumping code to fix bugs
To avoid this, it’s best to test before you commit. Testing can mean many things from, ‘check the code does what I expect’ to a full testing suite.
Committing our changes
We are happy that this ‘unit of work’ is in a state we are happy with (or at least, happy enouph for now). Now it’s time to ‘commit’ our work.
This requires two commands:
git add .
git commit -m 'a brief description of what we did'
git add .means ‘add all the changes in the current directory (represented by a single.in Unix-like environments).- We can also add individual files (
git add mything.py), or parts of files.
**Q** Why are these two commands?
Well changes you want to commit. You could choose to add changes after you make changes to each file (rather than at the end). If you have made lots of changes, you might choose to stage some of these, then commit, then stage the rest and commit those (useful when you realise this should be two commits rather than one!)Once we have let git know what should be included in the commit (everything that’s changed in the case of .) - we can
commit our change. We give commits a brief description using the command-line argument -m followed by a message.
If we don’t provide one, git will prompt us for a longer message (assuming we have a lot to say) and open our default editor. Depending on your setup, that might be vim or nano.
Continue working
Generally, we would probably make additional changes (work on the next thing) at this point. If we want to make more changes, great - we go back to the ‘make changes’ section.
If we’re done making changes (or want to let other people have the changes we made) we need to ‘push’ those changes
to another copy of the project. Git knows what copy we want to push to if we cloned this code originally (the copy
we got it from), so we can just use git push.
git push
If no one has altered the code in the original copy since we last ran git pull - this ‘just works’ and git tells
us that the changes are now in the original copy. We can continue making more changes, or we can do something else.
When should you push? Again this is an art more than a science. I generally push when:
- I’ve finished working on something
- I’m working on something else that relies on these changes (for complex interconnected projects)
- I’ve not pushed in a while and what my changes backed up
- It’s time to go home (or go to another session)
If other people (or you on another machine) have made changes, you may need to deal with a merge conflict.
Git is a very powerful tool for making it easy to track changes over time. There are more advanced things you can do with it, such as keeping multiple copies of your code (branches) or automatically testing and releasing code (CI).
We’ll leave it there as a starting point though.