Introduction

Git is widely-used and is a very powerful tool for version control of computer code. It is not particularly easy or intuitive to use, however with a few simple commands you can get productive fairly quickly.

Joining a project

You will typically join a project on a code repository such as GitHub or Bitbucket by cloning it with a Linux command such as:

git clone https://repo-home-url/project.git

This will download the code and automatically configure your local copy of the reposity to point back to the repository website as its origin repository.
See GitHub for examples and screenshots.

Start a new piece of work

Normally when fetching the latest changes that your colleagues have made to a project you will need to be on the master branch. Then you can pull the changes from master. If you cloned the repository with Git then it should already be configured to know where its origin is. I usually combine two commands with the && as shown so that if the first command fails the next one will not attempt to run.

git checkout master && git pull origin master

Then you will create a branch for your work:

git checkout -b my-branch-name

Typically my-branch-name will have in it some ticket number (if you use a work ticketing system), possibly your name, and maybe a concise description of the work. Your team leader will help you understand the conventions that your team uses, and any automatic workflow integrations the team has set up between your repository and your ticketing system. For example, it is possible to set up integrations between Phabricator (for code reviews) and JIRA (for tickets) so that when you create a pull request (PR) on Phabricator it updates the ticket status on JIRA, and then when the PR is landed on Phabricator it updates JIRA again.

Save some changes

Next you will do your work and commit it in small but meaningful changes. If you change a file some_code.py you will commit it like this:

git add some_code.py
git commit -m "Add a new function which does something cool."

It is a good idea to group related changes together in a single commit, even if they span multiple files. It is possible in Git to commit only some changes to a file instead of every change to the file, although this is usally more easily done using graphical tools that are commonly available in integrated development environments (IDEs) such as VS Code, IntelliJ IDEA, or Eclipse. Ideally your commit should not break any existing code. You can see all your changes on your branch (which is based on master) with

git log master.. --oneline

Don’t forget the two dots (..)! If you want to see the three most recent commits in the branch, run

git log HEAD~3.. --oneline

Omit the --oneline argument to see more details. The git log command has many options which provide powerful tools to analyse changes on a branch.

When you have finished making changes, run your test suite to make sure that you haven’t broken anything. When it passes it is time to push your changes up for code review by one of your peers, or the project owner. Run

git push origin my-branch-name

This will create a branch on the remote server with my-branch-name. For tracking your remote branches it is easiest if you use the same name for your remote branch as your local branch. At this point your code reviewer may have suggestions which require you to make some more commits. Make them and then push again with the command above.

Staying up-to-date

You may find, while you are working on your branch or implementing suggestions by your code reviewer, that your branch has become out of date with the master branch, in which case you could get merge conflicts when you try to land your PR. This is a normal part of team work in a software development team. Rectify the conflicts as follows, but first ensure that you have no uncommitted changes in your local repository.
If you have work in progress that you don’t wish to commit but you don’t wish to discard either, stash it:

git stash

You can unstash it at any time with

git stash pop

When you are ready to rebase, remembering to have a clean local repo with no uncommitted changes, do:

git checkout master && git pull origin master
git rebase master my-branch-name

Git will try to replay your changes on top of the latest master. If there are merge conflicts it will stop and force you to fix them before proceeding. If you make a mistake and want to start again, run

git rebase --abort

Otherwise make your changes and run

git add . && git rebase --continue

as many times as necessary until rebase is complete. Notice that you don’t do git commit during rebase! All you need to do is make the changes to the files and Git will save them with the current commit as it works through every change in your branch. If you want to do an interactive rebase, so that you can squash a few commits together, leave out some commits, or re-order them, do

git rebase -i master my-branch-name

This will open up your default text editor and provide you instructions on how to proceed. When you have finished, push your changes up to the remote server again. If the standard git push command shown earlier does not work, you may need to force push, as follows:

git push origin my-branch-name --force

That should get you started with a simple Git workflow. Git is not particularly user-friendly, but it is very powerful and has a lot of features. It is also widely used so it is worth learning.

Learning more

To get more help from Git you can view the man pages or print the help, as shown in the following examples:

man git-pull
git push --help

Acknowledgements

The author acknowledges the traditional custodians of the Daruk and the
Eora People and pays respect to the Elders past and present.