2.2 Git#

Git is a type of version control system. It allows you to keep track of changes to your code and to collaborate with others.

Why is it a good idea to use version control? You can:

  • Backup your code without making separate copies of it.

  • Review what you’ve changed.

  • Reverse mistakes.

  • Maintain several versions of your code at the same time.

  • Share your code with others.

Git is not the same as GitHub. GitHub is a website that hosts Git repositories. You can use Git without GitHub, but GitHub (or similar websites like GitLab or BitBucket) is a good place to store your code.

We will only cover the basics of Git here. The most basic Git workflow is as follows:

  • Make changes to your code in the working directory.

  • Stage the changes you want to commit.

  • Commit the changes to the repository.

What should we add to Git?#

You should add all of your code to Git. Things you should not add to Git include:

  • Files that are unrelated to your project (e.g. .DS_Store files).

  • Files that are generated by your code (e.g. .csv files).

  • Large data files.

  • Files that contain sensitive information (e.g. passwords).

Developing#

There are different types of Git workflows. The most basic workflow is to have one main/master branch and to make changes to that. This is fine for small projects.

For larger projects, it is better to have a main branch and a develop branch. The develop branch is where you make changes to your code. When you are ready to release a new version of your code, you merge the develop branch into the main branch.

Example#

Let’s go through an example of how to use Git. We will create a new repository, add some files, and commit them.

Installing#

Firstly, you’ll need to install Git. You can do this by following the instructions here.

Initialising your repository#

To create a new repository, you can either initialise Git in an existing directory, or create a new directory and initialise Git there. You can also retrieve an existing repository. In this example we will create a new directory.

Name the new directory called my_project and navigate to it with:

mkdir my_project
cd my_project

We can check we are in the right directory with:

pwd

Initialise the directory with:

git init

This will initialise a Git repository and name the current branch main.

If you want to retrieve an existing repository from online, you can do so with:

git clone <repository_url>

Configuring your git details#

Before you start using Git, you’ll need to configure your Git details. You can do this with:

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

The --global flag means the configurations will apply to all of your repositories. If you don’t want to use the --global flag, you can omit it and the configurations will only apply to the current repository.

Adding files#

Now that we have initialised our repository, we can add some files. In Unix operating systems we can create a new file with:

touch my_file.txt

For Windows users, you can create a new file with:

echo. > my_file.txt

We can check that the file has been created by checking the contents of the directory with ls for Unix users and dir for Windows users.

Now that we have created a file, we need add it to the repository so that Git can track it. We can do this with:

git add my_file.txt

We can check that the file has been added with:

git status

This will show us the status of the repository:

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

  new file:   my_file.txt

git status will tell us which files have been added, which files have been modified, and which files have been deleted. If you are happy with your additions, the next step is to commit them. You can think of committing as taking a snapshot of your code. Commit your changes with the following command:

git commit -m "Add my_file.txt"

The -m flag allows you to add a message to your commit. This is useful for keeping track of what changes you have made. You can also commit without a message, but you will be prompted to add one when you commit. It is good practice to add an informative message to your commits, so if you want to track the history you know what changes have been made.

To view the history of your commits, you can run:

git log

This will show you the history of your commits. You can use the arrow keys to scroll through the history if the list of commits is long. To exit, press q.

Let’s create a new branch to keep track of different versions of our code. One way of using branches is to keep track of various experiments. We will create a new branch called develop and switch to it with:

git checkout -b develop

We can check we are on the right branch by running git branch. This will list all of the branches in the repository. The branch with a * next to it is the current branch.

* develop
  main

If you make changes to my_file.txt using your favourite text editor, you can see the differences between the current version of the file and the version in the repository with:

git diff my_file.txt

We’ll commit the changes to the develop branch with git add my_file.txt and git commit -m "Add some text to my_file.txt".

Then we can switch back to the main branch with:

git checkout main

If we run git diff my_file.txt, we will see that there are no differences between the current version of the file and the version in the repository. This is because we have not made any changes to the main branch. If you want to merge the changes from the develop branch into the main branch, you can do so with:

git merge develop

Then if you run git log again, you can see the commit from the develop branch has been added into the main branch.

Finally, if you are happy with your changes, you can push them to a remote repository. origin refers to the remote repository in the below command. If you have not set up a remote repository, set up a project on a website with GitHub. After you’ve done that, you integrate the remote repository with your local repository with:

git remote add origin <repository_url>

To push the changes, you can then do this with:

git push origin main

Note you do not need to use the command line to use Git. There are many graphical user interfaces (GUIs) available for Git. You can use the command line, or a GUI, whichever you prefer. vscode for example has a built in Git GUI (documentation here).

Resources#

If you want to learn more, check out the following: